pcol: Permuted Correlation (on strata)
In simba: A Collection of functions for similarity analysis of vegetation data

Description Usage Arguments Details Value Note Author(s) References See Also Examples

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.

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

`x`	`dist`-object containing distances or similarities returned by `sim`, `vegdist`, `dist`, `dist.binary` or a complete resemblance matrix (nrow==ncol). For the plotting method a `mantl`-object.
`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 between `x` and `y` on the strata that are defined by `z`. If `y` is not given the function correlates the `x` against the classes in `z` leading to data points for a multivariate Mantel correlogram in the sense of Olden & Sokal (1986). See details.
`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 classes that span the same distance range. If `width` is specified this gives the bin width instead of a number of bins.
`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. Defaults to 5 bins.
`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 kendall for instance.
`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 `y`.
`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`)? Determines speed. For many reasonably huge data sets, the latter will be faster. However, when the datasets get really huge it may run faster on `for`-loops.

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:

If x and y are given but z = NULL a simple permuted correlation with mantl is run. This corresponds to a Mantel test. The two data-objects are correlated with cor, then the rows and corresponding rows in y are permuted and with cor the correlation is calculated again. 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. A diagnostic plot of the resulting object of class permcor can be plotted with the corresponding plot function.
If x, y, and z are 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. If z is a distance matrix or dist-object width or bins have 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 between x and y.
If x and z are specified and y = NULL, the matrix or vector in x is correlated against the classes given in or derived from z. 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).

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.

Depending on what is done and the size of the matrices it may take a while to calculate. The slowest is case 3.

Gerald Jurasinski gerald.jurasinski@uni-rostock.de

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.

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

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