mantel.test {cultevo}R Documentation

Perform one or more Mantel permutation tests.


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", ...)



a formula, distance matrix, or list of distance matrices (see below)


a data frame, distance matrix, or list of distance matrices of the same length as x


further arguments which are passed on to the default method (in particular plot, method, trials and omitzerodistances)


logical: immediately produce a plot of the test results (default: FALSE)


correlation coefficient to be computed. Passed on to cor, so one of "spearman", "kendall", or, inadvisable in the case of ties: "pearson". Following Dietz (1983), "spearman" is used as a default that is both powerful and robust across different distance measures.


integer: maximum number of random permutations to be computed (see Details).


logical: if TRUE, the calculation of the correlation coefficient omits pairs of off-diagonal cells which contain a 0 in the second distance matrix argument. (For the formula interface, this is the matrix which specifies the meaning distances.)


when x is a formula: column name by which the data in y is split into separate data sets to run several Mantel tests on


when x is a formula: edit distance function used to compute the distance matrix from the specified string column. Supports any edit distance function that returns a distance matrix from a vector or list of character strings. Default is Levenshtein distance (adist), other options from this package include normalisedlevenshteindists() and orderinsensitivedists().


when x is a formula: meaning distance function used to compute the distance matrix from the specified meaning columns. Defaults to Hamming distances between meanings (hammingdists()), custom meaning functions can be created easily using wrap.meaningdistfunction().


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 p-value.

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 side-by-side 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:


Character string: type of correlation coefficient used


The veridical correlation coefficient between the entries in the two distance matrices


A list of correlation coefficients calculated from the permutations of the input matrices


Average correlation coefficient produced by the permutations


Standard deviation of the sampled correlation coefficients


Empirical p-value 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


The theoretical p-value that would correspond to the standard z score as calculated above.


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, ...).

Methods (by class)


Dietz, E. J. 1983 “Permutation Tests for Association Between Two Distance Matrices.” Systematic Biology 32 (1): 21-–26.

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.

See Also

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

# show the three test results in one plot
plot(result, xlab="group")

## End(Not run)

[Package cultevo version 1.0.2 Index]