Tests whether two distance matrices are correlated after removing the
effect of a third: for instance, whether samples with more different
communities are also more different in pH, beyond what geographic
distance between them explains. Gives the same statistic as
vegan::mantel.partial() (Pearson, Spearman, or Kendall partial
correlation), with permutation p-values, computed in parallel C straight
from the distances. mantel() is the simple Mantel test.
Usage
mantel_partial(
dm,
y,
given,
data = NULL,
method = "pearson",
permutations = 999L,
strata = NULL,
alternative = "greater",
seed = 0L,
cpus = n_cpus()
)Arguments
- dm
A
distobject, such as frombeta_div()orbray(), or a symmetric numeric matrix of distances. Must not containNAs or negative values. Its samples are the ones permuted.- y
The distances to correlate with
dm: adistobject or a symmetric numeric matrix, likedm, matched todm's samples by name when both have names, otherwise in the same order. Or numeric values, such as age or pH, whose absolute differences (asstats::dist(y)) are the distances: withdata, the name of one of its numeric columns or a vector with one value per row ofdata; withoutdata, a vector with one value per sample, matched to the samples by name when it has names, otherwise in the same order.- given
The distances whose effect is removed from the correlation of
dmandy, asvegan::mantel.partial()'szdis: such as geographic distances between the samples. Given in any of the formsytakes, including as a column name ofdata. Required.- data
Optional sample metadata: a data frame with one row per sample, whose columns
y,given, andstratacan name. Rows are matched to the samples indmby row name, and rows for other samples are ignored; without row names, they must be in the same order asdm. Default:NULL.- method
The correlation coefficient:
'pearson','spearman', or'kendall'(tau-b), as instats::cor(). Default:'pearson'.- permutations
The number of permutations. Default:
999. Alternatively, a matrix with one permutation of1:nper row, as frompermute::shuffleSet(), to use instead of random ones.- strata
Permute samples only within these groups (blocks), for designs such as repeated measures. With
data, the name of one of its columns, or a vector with one value per row ofdata. Withoutdata, a vector with one value per sample, matched to the samples by name when it has names, otherwise in the same order. Default:NULL(free permutation).- alternative
Which correlations count as more extreme than the observed one:
'greater'(more positive, as invegan::mantel()),'less'(more negative), or'two.sided'(larger in absolute value). Default:'greater'.- seed
An integer seed for the random permutations. The same seed gives the same p-values. Default:
0- cpus
How many parallel processing threads should be used. The default,
n_cpus(), is the CPU cores this R process may use, within any limits set on it. Results are the same for anycpus.
Value
A list of class c('ecodive_mantel', 'ecodive_test'), as from
mantel(), with:
statistic: The partial Mantel statistic,c(r = ...): the partial correlation ofdmandygivengiven.vegan::mantel.partial()'sstatistic.p_value: The permutation p-value.z: The standardized effect size,(r - mean(r_perm)) / sd(r_perm).n_perm: The number of permutations.method: The correlation coefficient:'pearson','spearman', or'kendall'.alternative:'greater','less', or'two.sided'.partial:TRUE.n: The number of samples.permutation: How samples were permuted:'free','within strata', or'supplied matrix'.
Attribute r_perm is a vector of the statistics of the permutations, as
vegan::mantel.partial()'s perm. as.data.frame() gives the main
results as one row, with test = 'mantel_partial'.
Details
Method
The partial Mantel test (Smouse et al. 1986; Legendre & Legendre 2012)
correlates the \(n(n-1)/2\) distances of dm (\(x\)) and y after
removing the effect of given (\(z\)), as the partial correlation
$$r_{xy.z} = \frac{r_{xy} - r_{xz} r_{yz}}{\sqrt{1 - r_{xz}^2}
\sqrt{1 - r_{yz}^2}}$$
where each \(r\) is the Pearson, Spearman, or Kendall correlation of
two sets of distances. As in vegan::mantel.partial(), the p-value comes
from permutations of the samples of dm, with y and given held fixed:
\(r_{xy}\) and \(r_{xz}\) are recomputed for each permutation, and
\(r_{yz}\) is computed once. The p-value is the proportion of
permutations, counting the observed one, with a partial correlation at
least as extreme, as in mantel().
Its p-values can be too small when the distances are spatially autocorrelated (Legendre & Fortin 2010; Guillot & Rousset 2013).
When y and given, or dm and given, are perfectly correlated, there
is no partial correlation: the statistic and p-value are NA, with a
warning.
Speed, memory, and reproducibility
As for mantel(): each permutation is one pass over the distances (two
correlations, \(r_{xy}\) and \(r_{xz}\), in the same pass), with no
\(n \times n\) matrix, and permutations run in parallel. They come from
seed, so p-values are identical from run to run and for any number of
cpus, and agree with vegan::mantel.partial()'s exactly when the same
permutations matrix is given to both.
Differences from vegan::mantel.partial()
yandgivenmay also be numeric vectors, one value per sample, or names of columns ofdata.Samples are matched by name between
dm,y,given,data, andstrata.alternativeadds lower-tail and two-sided tests.There's no
na.rm: distances must not beNA.
References
Guillot, G., & Rousset, F. (2013). Dismantling the Mantel tests. Methods in Ecology and Evolution, 4(4), 336-344. doi:10.1111/2041-210x.12018
Legendre, P., & Fortin, M.-J. (2010). Comparison of the Mantel test and alternative approaches for detecting complex multivariate relationships in the spatial analysis of genetic data. Molecular Ecology Resources, 10(5), 831-844. doi:10.1111/j.1755-0998.2010.02866.x
Legendre, P., & Legendre, L. (2012). Numerical Ecology (3rd ed.), section 10.5. Elsevier.
Smouse, P. E., Long, J. C., & Sokal, R. R. (1986). Multiple regression and correlation extensions of the Mantel test of matrix correspondence. Systematic Zoology, 35(4), 627-632. doi:10.2307/2413122
Examples
# 30 samples along a pH gradient, which shifts the first five genera,
# at random locations.
set.seed(1)
counts <- matrix(rpois(30 * 20, 5), 30, 20)
rownames(counts) <- paste0('S', 1:30)
meta <- data.frame(
row.names = rownames(counts),
ph = round(runif(30, 6, 8), 1),
lat = runif(30, 30, 35),
lon = runif(30, -100, -95) )
counts[, 1:5] <- counts[, 1:5] + round(4 * (meta$ph - 6))
dm <- bray(counts)
geo <- dist(meta[, c('lat', 'lon')])
# Are samples that differ more in pH also more different in
# community composition, beyond the effect of geographic distance?
mantel_partial(dm, 'ph', given = geo, data = meta)
#> Partial Mantel test (Pearson) of Bray-Curtis Dissimilarity
#>
#> r = 0.5931, p = 0.001, z = 9.759
#> Permutations: 999 (free)
#>
#> Correlation: Pearson's product-moment correlation
#> Alternative: greater (r is more positive than by chance)
#> Samples: 30
# With rank correlation.
mantel_partial(dm, 'ph', given = geo, data = meta, method = 'spearman')
#> Partial Mantel test (Spearman) of Bray-Curtis Dissimilarity
#>
#> r = 0.5528, p = 0.001, z = 9.969
#> Permutations: 999 (free)
#>
#> Correlation: Spearman's rank correlation rho
#> Alternative: greater (r is more positive than by chance)
#> Samples: 30
# The same, through dist_test().
dist_test(dm, 'mantel_partial', 'ph', meta, given = geo, method = 'spearman')
#> Partial Mantel test (Spearman) of Bray-Curtis Dissimilarity
#>
#> r = 0.5528, p = 0.001, z = 9.969
#> Permutations: 999 (free)
#>
#> Correlation: Spearman's rank correlation rho
#> Alternative: greater (r is more positive than by chance)
#> Samples: 30
