cultevo (version 1.0.2)

mantel.test: Perform one or more Mantel permutation tests.

Description

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.

Usage

mantel.test(x, y, ...)
# S3 method for default
mantel.test(x, y, plot = FALSE, method = c("spearman",
  "kendall", "pearson"), trials = 9999, omitzerodistances = FALSE, ...)
# S3 method for formula
mantel.test(x, y, groups = NULL,
  stringdistfun = utils::adist, meaningdistfun = hammingdists, ...)
# S3 method for list
mantel.test(x, y, plot = FALSE, ...)
# S3 method for mantel
plot(x, xlab = "generation", ...)

Arguments

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 x

...

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

plot

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

method

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.

trials

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

omitzerodistances

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

groups

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

stringdistfun

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

meaningdistfun

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

xlab

the x axis label used when plotting the result of several Mantel tests next to each other

Value

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 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

p.approx

The theoretical p-value 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, ...).

Methods (by class)

• 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.

Details

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.

References

Dietz, E. J. 1983 <U+201C>Permutation Tests for Association Between Two Distance Matrices.<U+201D> Systematic Biology 32 (1): 21-<U+2013>26. https://doi.org/10.1093/sysbio/32.1.21.

North, B. V., D. Curtis and P. C. Sham. 2002 <U+201C>A Note on the Calculation of Empirical P Values from Monte Carlo Procedures.<U+201D> The American Journal of Human Genetics 71 (2): 439-<U+2013>41. https://doi.org/10.1086/341527.

See Also

cor, adist, hammingdists, normalisedlevenshteindists, orderinsensitivedists

Examples

# NOT RUN {
# 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"))
# }
# NOT RUN {
# }
# NOT RUN {
# 2x2x2x2 design
mantel.test(hammingdists(enumerate.meaningcombinations(c(2, 2, 2, 2))),
  dist(1:16), plot=TRUE)
# }
# 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")
# }