commcorrelogram: Community Correlogram
In CommunityCorrelogram: Ecological Community Correlogram

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

View source: R/commcorrelogram.R

The function commcorrelogram computes community correlograms using either the multivariate metric ANOSIM R (Clarke, 1993) or the Mantel statistic (Mantel, 1967), and includes functionality for both directional analyses and combinations of temporal or spatial analyses or both. The Mantel correlogram was originally proposed by Sokal (1986) and Oden and Sokal (1986). The ANOSIM correlogram is suggested here.

commcorrelogram(sampleData,sampleTime=NULL,sampleLocation=NULL,
LocationNames=NULL,option=1,metric='anosim',lagNumber,lagSize,lagTol,
numTests=999,anisotropic=FALSE,azimuth,azimuthTol,bandwidth,dipAngle,dipTol,
dipBandwidth,distmeth='bray',mantmeth='spearman',adj='holm',prog=TRUE,
alternative='one.sided')

`sampleData`	A matrix or dataframe with samples as rows and species or populations as columns
`sampleTime`	A numeric, date, or POSIX format vector of sample collection times for the objects in `sampleData` (used for temporal analyses only)
`sampleLocation`	A matrix or dataframe of xyz, xy (surface) plane and the z (depth) plane, geographical coordinates for objects in `sampleData` (used for spatial analyses only)
`LocationNames`	A character vector of location names for the objects in `sampleData` (used for temporal analyses grouped by location)
`option`	A switch specifying type of correlogram to be determined (spatial, temporal, or a combintation of both). Options include: 1 = spatial analysis only (provide `sampleLocation`), 2 = temporal analysis only (provide `sampleTime`), 3 = spatial analysis grouped by sampling event (provide `sampleLocation` and `sampleTime`), 4 = temporal analysis grouped by sampling location (provide `sampleTime` and either `sampleLocation` or `LocationNames`). Default = 1.
`metric`	A switch specifying statistical test for similarity to be applied. Options include: 'anosim' = ANOSIM Correlogram, 'mantel' = Mantel Correlogram. Default = 'anosim'.
`lagNumber`	Number of distance (lag) classes for correlogram
`lagSize`	Multiple for which the centers of distance (lag) classes are calculated
`lagTol`	Lag tolerance. Default is half the width of each distance (lag) class.
`numTests`	Number of permutation tests for significance testing. Default = 999.
`anisotropic`	A switch specifying whether sample pairs are restricted by geographic separation angles. Default = F. The user is advised to consider whether anisotropic analsyses are appropriate for their dataset and specify a value for `anisotropic` accordingly.
`azimuth`	Direction of sample restriction in the xy plane (degrees)
`azimuthTol`	Tolerance of sample restriction angle in the xy plane (degrees)
`bandwidth`	Maximum perpendicular distance from vector of sample restriction angle in the z direction
`dipAngle`	Direction of sample restriction in the z (depth) direction (degrees)
`dipTol`	Tolerance of sample restriction angle in the z direction (degrees)
`dipBandwidth`	Maximum perpendicular distance from vector of sample restriction angle in the z direction
`distmeth`	A switch specifying method to be applied for calculation of ecological distances between `sampleData`. A complete listing of available options are described in `vegdist`. Default = 'bray'.
`mantmeth`	A switch specifying method to be applied for calculation of the Mantel statistic between ecological and geographical or temporal distance matrices. Default = 'spearman' for Spearman rank correlation. Other options are 'pearson' and 'kendall', as described in `cor`.
`adj`	A switch specifying method for adjustment of significance values for multiple comparison tests to be applied. Default = 'holm'. Other options are as in described in `p.adjust`.
`prog`	A switch specifying whether to adjust significance progressively as described in Legendre and Legendre (1998, p. 721). Significance for distance class k = correction for k multiple tests. Default = T.
`alternative`	A switch specifying alternative hypothesis for statistical tests to be applied. Options include: 'one.sided' = statistic <= 0, 'two.sided' = statistic = 0. Default = 'one.sided'.

Mantel correlograms, a form of geostatistical structure function, have often been used in ecological analyses to evaluate the spatial variation of ecological communities or other multidimensional datasets (Mantel, 1967; Oden and Sokal, 1986; Sokal, 1986; Legendre and Legendre, 2012). The correlogram bins sample pairs by their spatial or temporal separation distance and then plots the average multidimensional similarity between pairs versus their (binned) separation distance; the approach tests whether pairs of samples that are separated by a particular distance are more similar than those that are separated by a different distance. By not including lesser distances in a distance class, recurring or oscillating patterns can be detected as well as gradients.

Basic Mantel correlograms are implemented in both the vegan (Oksanen et al., 2012) and ecodist (Goslee and Urban, 2007) packages; however, anisotropy, or directional differences in spatial structure, is frequently encountered in geostatistical analyses. The commcorrelogram() function, unlike other implementations, includes the ability to impose directional restrictions on the distance classes, facilitating identification and characterization of spatial patterns(Andrus et al. 2013). The current implementation further allows the integration of temporal and spatial data; strictly temporal or spatial correlograms can be performed, or alternatively temporal correlograms holding spatial locations constant or spatial correlograms holding sample times constant are possible. This functionality allows multiple perspectives of analysis of data that has been collected in several locations over time.

The distance classes are specified by the parameters lag size (h, the interval between distance classes) and lag tolerance (width of the distance classes) and must be optimized for each dataset (see lagSelect). To include all samples in one distance class the lag tolerance is set to half the lag size. Directional parameters are standard geostatistical terms, for example as used in the gamv program of the FORTRAN geostatistics package GS-Lib (Deutsch and Journel, 1998). The azimuth is the direction of the analysis along a horizontal plane, while the allowed variation in this direction is the azimuth tolerance, and the allowed perpendicular distance from the azimuth is the bandwidth. Similarly, parameters related to deflection from this surface in the depth direction (dip angle, dip tolerance, and dip bandwidth) can also be defined.

Additionally, the function also allows selection of either the ANOSIM R statistic (Clarke and Green, 1988; Clarke, 1993) or the Mantel statistic R_M (Mantel, 1967) as measures of similarity within the correlogram. In univariate analyses, various statistics have been developed to quantify autocorrelation: e.g. Moran's I (Moran, 1950), Geary's C (1954). The ANOSIM statistic is commonly used in microbial ecology to test differences in community between factor groups, and therefore may be more accessible for microbial ecologists performing spatial or temporal community analyses. It is a nonparametric statistic based on the ranks of similarities between sample pairs. The similarity metric used to calculate similarity is user-specified.

The implementation of ANOSIM in a correlogram is an adaptation of the original statistic for pairs of samples separated by a particular distance rather than for membership in a particular group. The statistic is calculated for a specific distance class h:

R(h) = (r_b(h) - r_w(h))/(1/4 * n(n-1))

where r_b(h) is the mean rank of similarities for sample pairs between groups (with a separation distance not equal to h), r_w(h) is the mean rank of similarities for sample pairs within groups (separated by a distance of h), and n is the total number of samples.

Legendre and Legendre (2012) advise adjusting the p-values for each distance class in a multidimensional correlogram for multiple comparison. This function allows the specification of a particular multiple comparison adjustment via p.adjust and whether the comparison should be adjusted progressively or uniformly. Furthermore, the p-value can be calculated based on whether a one- or two-tailed test is desired. For a two-tailed test, the p-value reflects the probability that the Mantel R_M or ANOSIM R statistic is zero, or in other words, there is no difference in similarity between sample pairs having a particular separation distance and those that do not.

Returns an object of class community.correlogram, which is a dataframe consisting of:

`lag.distance`	The average lag distance separating pairs in the lag class
`Num.Pairs`	The number of pairs in the lag class
`statistic`	The value of the statistic (Mantel or ANOSIM) for the lag class
`significance`	The p-value (adjusted if required) of the statistic

J. Malia Andrus, Timothy Kuehlhorn, Luis F. Rodriguez, Angela D. Kent, and Julie L. Zilles

Maintainer: J. Malia Andrus <jmaliaandrus@gmail.com>

Andrus, J. M., Matthew D. Porter, Luis F. Rodriguez, Timothy Kuehlhorn, R. A. C. Cooke, Yuanhui Zhang, Angela D. Kent, and Julie L. Zilles. 2013. "Spatial Variation in the Bacterial and Denitrifying Bacterial Community in a Biofilter Treating Subsurface Agricultural Drainage." Microbial Ecology. DOI 10.1007/s00248-013-0286-0.

Clarke KR, Green RH (1988) Statistical design and analysis for a biological effects study. Mar Ecol-Prog Ser 46 (1-3):213-226.

Clarke KR (1993) Nonparametric multivariate analyses of changes in community structure. Aust J Ecol 18 (1):117-143.

Deutsch, C. V. and A. G. Journel. 1998. GSLIB geostatistical software library and user's guide. Oxford: Oxford University Press.

Geary, R.C. (1954). "The Contiguity Ratio and Statistical Mapping". The Incorporated Statistician 5 (3): 115-145.

Goslee, S.C. and Urban, D.L. 2007. The ecodist package for dissimilarity-based analysis of ecological data. Journal of Statistical Software 22(7): 1-19.

Legendre, P., and L. Legendre. 1998. Numerical Ecology. 2nd English Edition. Elsevier Science: Amsterdam.

Legendre, P., and L. Legendre. 2012. Numerical Ecology. 3rd English Edition. Elsevier Science: Amsterdam.

Mantel, N. 1967. The detection of disease clustering and a generalized regression approach. Cancer Res. 27: 209-220.

Moran, P.A.P.(1950). Notes on Continuous Stochastic Phenomena. Biometrika 37 (1): 17-23.

Oden, N. L. and R. R. Sokal. 1986. Directional autocorrelation: an extension of spatial correlograms to two dimensions. Syst. Zool. 35: 608-617.

Oksanen, J., F. G. Blanchet, R. Kindt, P. Legendre, P. R. Minchin, R. B. O'Hara, G. L. Simpson, P. Solymos, M. Henry, H. Stevens and H. Wagner (2012). vegan: Community Ecology Package. R package version 2.0-4. http://CRAN.R-project.org/package=vegan

Sokal, R. R. 1986. Spatial data analysis and historical processes. 29-43 in: E. Diday et al. [eds.] Data analysis and informatics, IV. North-Holland, Amsterdam.

mod.commcorrelogram

lagSelect

#spatial community ANOSIM correlogram
data(mite)
data(mite.xy)
commcorrelogram(sampleData=mite,sampleLocation=cbind(mite.xy,z=0)
,lagSize=0.3,lagNumber=17,lagTol=0.15,option=1,numTests=5)

## Not run: 
  #spatial community Mantel correlogram
  data(mite)
  data(mite.xy)
  commcorrelogram(sampleData=mite,sampleLocation=cbind(mite.xy,z=0)
  ,lagSize=0.3,lagNumber=17,lagTol=0.15,option=1,metric="mantel"
  ,mantmeth="spearman",numTests=9)
  
  #anisotropic community correlograms
  commcorrelogram(sampleData=mite,sampleLocation=cbind(mite.xy,z=0)
  ,lagSize=0.3,lagNumber=8,lagTol=0.15,option=1,anisotropic=TRUE
  ,azimuth=0,azimuthTol=15,bandwidth=2,numTests=9,dipAngle=0
  ,dipTol=90,dipBandwidth=1)
  
  commcorrelogram(sampleData=mite,sampleLocation=cbind(mite.xy,z=0)
  ,lagSize=0.5,lagNumber=10,lagTol=0.25,option=1,anisotropic=TRUE
  ,azimuth=90,azimuthTol=15,bandwidth=2,numTests=9,dipAngle=0
  ,dipTol=90,dipBandwidth=1)
  
  commcorrelogram(sampleData=mite,sampleLocation=cbind(mite.xy,z=0)
  ,lagSize=0.5,lagNumber=10,lagTol=0.25,option=1,anisotropic=TRUE
  ,azimuth=45,azimuthTol=15,bandwidth=2,numTests=9,dipAngle=0
  ,dipTol=90,dipBandwidth=1)
  
  #temporal community correlogram
  data(pyrifos)
  pyrifos.levels<-data.frame(ditch=gl(12,1,length=132),
  dose=factor(rep(c(0.1, 0, 0, 0.9, 0, 44, 6, 0.1, 44, 0.9, 0, 6),11)),
      week=as.numeric(as.character(gl(11, 12,
      labels=c(-4, -1, 0.1, 1, 2, 4, 8, 12, 15, 19, 24)))))
  commcorrelogram(sampleData=pyrifos,sampleTime=pyrifos.levels$week,
  option=2,lagSize=3,lagTol=1.5,numTests=9,lagNumber=10)
  
  #temporal community correlogram holding location constant
  commcorrelogram(sampleData=pyrifos,sampleTime=pyrifos.levels$week,
  LocationNames=pyrifos.levels$ditch,option=4,lagSize=3,lagTol=1.5,
  numTests=9,lagNumber=10)

## End(Not run)