simba (version 0.3-4)

pcol: Permuted Correlation (on strata)

Description

The function is a wrapper for several functions related to the permuted correlation between distance matrices: calculate permuted correlation between vectors or calculate permuted correlation on strata. This can be useful to obtain data-points for a multivariate Mantel correlogram. Two matrices and a matrix dividing these into strata (levels) are to be specified.

Usage

pcol(x, y = NULL, z = NULL, width = NULL, bins = 5, method = "pearson", 
permutations = 1000, alpha = 0.5, trace = FALSE, ...)
mantl(x, y, method = "pearson", permutations = 1000, sub = NULL,
loop = FALSE, ...)
## S3 method for class 'mantl':
plot(x, y, ...)

Arguments

x

dist-object containing distances or similarities returned by sim, vegdist, dist,

y

A similar object like x with the same dimensions representing resemblance between the same objects as for x but based on other variables. Defaults to NULL. See details

z

A similar object like x containing distances or distance classes. If the latter is true set width to 1 (bins is without effect then). If y is provided the function calculates Mantel statistic for the correlation betw

width

Numeric. If width=1 z is assumed to contain classes already. If width is NULL (default), the classes are defined inside the function by using bins to derive n = bins distance cl

bins

Numeric. If width is NULL (default), the distance classes derived from z are defined inside the function by using bins to derive n = bins distance classes that span the same distance range.

method

Method of correlation, as it is done by cor.test, see help there for details. Defaults to Pearson correlation coefficients. Other options are Kendall and Spearman rank correlations.

permutations

Integer giving the number of permutations in mantl, defaults to 1000 to get a significance level of p = 0.001.

alpha

Numeric. The initial alpha-level against which should be tested. In case of testing on strata (z != NULL)it is internally corrected using Bonferronis method.

trace

Logical. Set to TRUE to follow the calculation succession in case x, y, and z are specified.

...

Arguments to other functions, for instance to cor.test regarding specifications of the test, however only the correlation value is taken from this function. but here you could change from pearson to k

sub

If Case is 1 (see details) a subset of cases from x and y can be defined for correlation. Therefore, sub has to be a logical matrix with the same dimensions as a matrix derived from x and

loop

Triggers the method for permutation inside the function mantl. Shall it be looped (for-loop, loop = TRUE) or be done by an apply method (loop = FALSE)?

Value

• Returns different objects, depending on given arguments and triggers. In case 1 a permcor-object with the following items is returned:
• call
  The call to the function.
• method
  The correlation method as used by cor.test.
• statistic
  The initial correlation value which is tested against the permuted values.
• signif
  The significance of the calculation.
• n
  The number of cases.
• permutations
  The number of permutations as specified by permutations.
• perms
  The result of the permuted runs. It is not printed by default but can be accessed via result$perms. The correlation value can be plotted against an histogram of the distribution of the permuted values to visualize the significance with the default plotting method.
• In cases 2 and 3 a pclist-object with the following items is returned. It might be as well worth to set trace = TRUE to display the progress of the calculation because it can take a while:
• call
  The call to the function.
• method
  The correlation method as used by cor.test.
• gesN
  The total number of cases.
• strata
  The number of strata (or levels) for which permutation has been done.
• permutations
  The number of permutations as specified by permutations.
• out
  A data.frame with 3 columns containing the result for each stratum in the rows: statistic contains the correlation values for the corresponding stratum, sig the obtained significance, and nop the number of cases found and used for permutation on this very level.

encoding

UTF-8

Details

pcol is doing the handling whereas all permutations are done with mantl. Depending on what is given to y, z, and width and bins respectively, the following is carried out:

1. Ifxandyare given butz = NULLa simple permuted correlation withmantlis run. This corresponds to a Mantel test. The two data-objects are correlated withcor, then the rows and corresponding rows inyare permuted and withcorthe correlation is calculated again. This is repeatedpermutationtimes. Finally, the initial correlation value is compared to the permuted values. The number of times, the permuted values exceed the initial value is divided by the number of permutations to obtain a significance value. Thus, with 1000 permutations a minimum p of 0.001 can be tested. A diagnostic plot of the resulting object of classpermcorcan be plotted with the corresponding plot function.
2. Ifx,y, andzare given, the permuted correlation is done for every stratum or level given by z - this could e.g. be direction or distance classes flagging which plots share a similar distance and therefore fall into the same class. Ifzis a distance matrix ordist-objectwidthorbinshave to be specified to obtain distance classes. If run with defaults the function finds 5 classes (bins) of equal distance range. The resulting data-points can be used to plot a correlogram which allows for the analysis of non-stationarity in the relationships betweenxandy.
3. Ifxandzare specified andy = NULL, the matrix or vector inxis correlated against the classes given in or derived fromz. This produces the data-points for a multivariate Mantel correlogram in the sense of Oden & Sokal (1986) (see also Legendre & Legendre 1998 for a comprehensive coverage of the subject).

References

Legendre, P, & Legendre, L. (1998) Numerical Ecology. 2nd English Edition. Elsevier. Oden, N. L. & Sokal, R. R. (1986) Directional Autocorrelation: An Extension of Spatial Correlograms to Two Dimensions. Systematic Zoology 35: 608-617.

See Also

mantel for a different implementation of Mantel tests, cor.test

Examples

data(abis)

## calulcate soerensen of species data
abis.soer <- sim(abis.spec)
## calculate distance (Euclidean) regarding some disturbance 
## variables (feces counts)
abis.pert <- dist(abis.env[,19:25])
## are compositional similarity and dissimilarity of disturbance related?
pcol(abis.soer, abis.pert)
## the relationship is significant, but not very strong

## compare one resemblance matrix with several others
# we compare bray-curtis against this selection of indices:
indices <- c("soerensen", "jaccard", "ochiai", "mountford", "whittaker", 
"lande", "wilsonshmida", "cocogaston", "magurran", "harrison")
# we use mantl() inside a sapply call
t(sapply(indices, function(x) unlist(mantl(vegdist(abis.spec), sim(abis.spec, method=x))[3:5])))