pcol {simba}R Documentation

Permuted Correlation (on strata)

Description

The function is a wrapper for several functions related to the permuted correlation between matrices or vectors: It calls permcor2 to calculate permuted correlation between vectors and permcor to calculate permuted correlation on strata. This can be useful to obtain data-points for a multivariate Mantel correlogram. Two matrices or vectors and a variable dividing these vectors into strata (levels) are to be specified. If the last is not given only permuted correlation between the two matrices (dist-objects) is done. If the second matrix/vector is a subsetting object the correlation can be done on the first object for each of the strata with mancor.

Usage

pcol(x, y, z = NULL, method="pearson", permutations=1000, 
solo=FALSE, ...)

permcor(x, y, subsetter, method="pearson", permutations=1000, 
alpha=0.05, trace=FALSE, ...)

permcor2(x, y, method="pearson", permutations=1000, subset=NULL, 
complete=TRUE, ...)

mancor(dis, classes, width=NULL, method="pearson", permutations=1000, 
alpha=0.05, trace=FALSE, ...)

## S3 method for class 'permcor':
plot(x, y, ...)

Arguments

x Matrix (dist-objekt) or vector of numeric values (atomic) containing distances or similarities returned by sim, vegdist, dist, dist.binary or a similar matrix. Conversion is done automatically and triggered by is.vector. If it is not a vector it is assumed to be a dist-objekt or a similar matrix (with nrow==ncol). For the plotting method a permcor-object.
y If solo=FALSE an object of the same qualities and dimensions (or length) as x to correlate to. See Details for the case solo=TRUE. For the plotting method an optional object. Not needed here.
z Vector or dist-objekt of a variable which defines the strata, or levels for which the permuted correlation shall be calculated. Doesn't have to be a factor but it has to be convertible into factor. see Details for more.
subsetter Vector of a variable which defines the strata, or levels for which the permuted correlation shall be calculated. Usually conversion from dist-object to vector is done in pcol. If permcor is run separately it has to be a vector (same holds for x, y, and z if the background functions are run separately). Doesn't have to be a factor but it has to be convertible into factor. see Details for more.
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 number of permutations, defaults to 1000 to get a significance level of p = 0.001.
solo If TRUE y is assumed to be a subsetting matrix, dist-object or vector giving strata to correlate x with and calculate the data-points for a Multivariate Mantel Correlogram for one distance-matrix.
width If solo=TRUE the subsetting object is assumed to contain classes already. If width is specified (defaults to NULL), the classes are defined inside the function and width gives the class width.
trace Set to TRUE to follow the runs of the for-loops in functions permcor and mancor. See details for when it is appropriate to set via pcol.
complete Should only complete cases be considered? Defaults to TRUE.
alpha The initial alpha-level against which should be tested. Depending on sub-function it is internally changed via Bonferroni-correction if necessary.
subset If Case is 1 (see details) a subset of cases from x and y can be defined for correlation.
dis Same as x for mancor.
classes If mancor shall be run, second item is a vector or dist-objekt of a variable which defines the strata, or levels for which the permuted correlation shall be calculated. Doesn't have to be a factor but it has to be convertible into factor. see Details for more.
permcor (In plot.permcor) an object returned by permcor2 is easily plotted with plot.permcor. The actual correlation value is plotted against an histogram of the distribution of the permuted values.
... 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 kendall for instance.

Details

pcol is a wrapper for the other functions. Depending on the input and the setting of solo the following functions are invoked (They can also be run separately. In this case x, y, and z must be given as vectors).

  1. If x and y are dist-objects, or vectors containing distance or similarity values and everything else is set to defaults a simple permuted correlation with permcor2 is run. This corresponds to a Mantel test. The two data-objects are correlated with cor.test, then the y is permuted and with cor the correlation is calculated again and written to a vector. This is repeated permutation times. 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.
  2. If a subsetter is given in z, the permuted correlation is done for every stratum or level given by the subsetting object - this could e.g. be direction or distance classes flagging which plots share a similar distance and therefore fall into the same class. The resulting data-points can be used to plot a correlogram which allows for the analysis of non-stationarity in the relationships between x and y.
  3. If y is itself a subsetting object (distance classes or so) you have to set solo=TRUE. Than the matrix or vector in x is correlated against this classes. This is handled by mancor. The parameter width allows for the calculation of classes inside the function. If for instance a distance-matrix with geographical distances is given, width specifies the width of the distance classes, they are computed and used to correlate the data in x against. 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).

Value

Returns different objects, depending on given arguments and triggers.

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.
case 2 a pclist-object with the following items (in this case it might be nice to set trace=TRUE to display the progress of the calculation) is returned:
    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.
case 3 a pclist-object with the same items as in Case 2 (in this case it might be as well interesting to set trace=TRUE to display the progress of the calculation) is returned.

Note

Depending on the background-function and the size of the matrices or vectors it may take a while to calculate. The slowest is mancor (case 3).

Author(s)

Gerald Jurasinski

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, and mantell, 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    


[Package simba version 0.2-5 Index]