mantel.test {cultevo}  R Documentation 
Perform correlation tests between pairs of distance matrices. The Mantel
test is different from classical correlation tests (such as those
implemented by cor.test
) in that the null distribution
(and significance level) are obtained through randomisation. The null
distribution is generated by shuffling the locations (matrix rows and
columns) of one of the matrices to calculate an empirical null distribution
for the given data set.
mantel.test(x, y, ...)
## Default S3 method:
mantel.test(x, y, plot = FALSE, method = c("spearman",
"kendall", "pearson"), trials = 9999, omitzerodistances = FALSE, ...)
## S3 method for class 'formula'
mantel.test(x, y, groups = NULL,
stringdistfun = utils::adist, meaningdistfun = hammingdists, ...)
## S3 method for class 'list'
mantel.test(x, y, plot = FALSE, ...)
## S3 method for class 'mantel'
plot(x, xlab = "generation", ...)
x 
a formula, distance matrix, or list of distance matrices (see below) 
y 
a data frame, distance matrix, or list of distance matrices of the
same length as 
... 
further arguments which are passed on to the default method (in
particular 
plot 
logical: immediately produce a plot of the test results (default:

method 
correlation coefficient to be computed. Passed on to

trials 
integer: maximum number of random permutations to be computed (see Details). 
omitzerodistances 
logical: if 
groups 
when 
stringdistfun 
when 
meaningdistfun 
when 
xlab 
the x axis label used when plotting the result of several Mantel tests next to each other 
If the number of possible permutations of the matrices is reasonably close
to the number of permutations specified by the trials
parameter, a
deterministic enumeration of all the permutations will be carried out
instead of random sampling: such a deterministic test will return an exact
pvalue.
plot()
called on a data frame of class mantel
plots a
visualisation of the test results (in particular, the distribution of
the permutated samples against the veridical correlation coefficient). If
the veridical correlation coefficient is plotted in blue it means
that it was higher than all other coefficients generated by random
permutations of the data. When the argument contains the result of more than
one Mantel tests, a sidebyside boxplot visualisation shows the mean and
standard deviation of the randomised samples (see examples). Additional
parameters ...
to plot()
are passed on to
plot.default
.
A dataframe of class mantel
, with one row per Mantel test carried
out, containing the following columns:
method
Character string: type of correlation coefficient used
statistic
The veridical correlation coefficient between the entries in the two distance matrices
rsample
A list of correlation coefficients calculated from the permutations of the input matrices
mean
Average correlation coefficient produced by the permutations
sd
Standard deviation of the sampled correlation coefficients
p.value
Empirical pvalue computed from the Mantel
test: let ngreater
be the number of correlation coefficients
in rsample
greater than or equal to statistic
, then
p.value
is (ngreater+1)/(length(rsample)+1
p.approx
The theoretical pvalue that would correspond
to the standard z
score as calculated above.
is.unique.max
Logical, TRUE
iff the veridical
correlation coefficient is greater than any of the coefficients
calculated for the permutations. If this is true, then
p.value == 1 / (length(rsample)+1)
Multiple mantel
objects can easily be combined by calling
rbind(test1, test2, ...)
.
default
: Perform Mantel correlation test on two distance
matrices. The distance matrices can either be of type
dist
, plain R matrices or any object that can be
interpreted by check.dist
. The order of the two matrices does
not matter unless omitzerodistances = TRUE
, in which case cells with
a 0 in the second matrix are omitted from the calculation of the
correlation coefficient. For consistency it is therefore recommended to
always pass the string distance matrix first, meaning distance matrix second.
formula
: This function can be called with raw experimental
result data frames, distance matrix calculation is taken care of internally.
x
is a formula of the type s ~ m1 + m2 + ...
where s
is the column name of the character strings in data frame or matrix y
,
while m1
etc. are the column names specifying the different meaning
dimensions. To calculate the respective distances, the function
stringdistfun
is applied to the strings, meaningdistfun
to the
meaning columns.
list
: When x
is a list of distance matrices, and
y
is either a single distance matrix or a list of distance matrices
the same length as x
: runs a Mantel test for every pairwise
combination of distance matrices in x
and y
and returns a
mantel
object with as many rows.
Dietz, E. J. 1983 “Permutation Tests for Association Between Two Distance Matrices.” Systematic Biology 32 (1): 21–26. https://doi.org/10.1093/sysbio/32.1.21.
North, B. V., D. Curtis and P. C. Sham. 2002 “A Note on the Calculation of Empirical P Values from Monte Carlo Procedures.” The American Journal of Human Genetics 71 (2): 439–41. https://doi.org/10.1086/341527.
cor
,
adist
, hammingdists
,
normalisedlevenshteindists
,
orderinsensitivedists
# small distance matrix, Mantel test run deterministically
mantel.test(dist(1:7), dist(1:7))
## Not run:
# run test on smallest distance matrix which requires a random
# permutation test, and plot it
plot(mantel.test(dist(1:8), dist(1:8), method="kendall"))
## End(Not run)
## Not run:
# 2x2x2x2 design
mantel.test(hammingdists(enumerate.meaningcombinations(c(2, 2, 2, 2))),
dist(1:16), plot=TRUE)
## End(Not run)
# using the formula interface in combination with a data frame:
print(data < cbind(word=c("aa", "ab", "ba", "bb"),
enumerate.meaningcombinations(c(2, 2))))
mantel.test(word ~ Var1 + Var2, data)
## Not run:
# pass a list of distance matrices as the first argument, but just one
# distance matrix as the second argument: this runs separate tests on
# the pairwise combinations of the first and second argument
result < mantel.test(list(dist(1:8), dist(sample(8:1)), dist(runif(8))),
hammingdists(enumerate.meaningcombinations(c(2, 2, 2))))
# print the result of the three independently run permutation tests
print(result)
# show the three test results in one plot
plot(result, xlab="group")
## End(Not run)