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

Description Usage Arguments Details Value Methods (by class) References See Also Examples

View source: R/mantel.R

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
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", ...)

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

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.

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

(North, Curtis and Sham 2002).

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)

References

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.

See Also

cor, adist, hammingdists, normalisedlevenshteindists, orderinsensitivedists

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
# 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)

kevinstadler/cultevo documentation built on April 25, 2018, 9:05 a.m.