mod.commcorrelogram: Community Correlogram Model In CommunityCorrelogram: Ecological Community Correlogram

Description

Function mod.commcorrelogram automatically fits a Gaussian curve to the significance plot of a commcorrelogram object and calculates the correlation range of the data.

Usage

 1 2 mod.commcorrelogram(object,Ch=1,Cc=5,Cw=0.01,plot=T,alpha=0.05, alternative='one.tailed',pw=5,lgpos='topleft',...)

Arguments

 object A community.correlogram object Ch An initial guess for the asymptotic maximum significance. Default = 1. The user is advised to consider values for Ch appropriate for their particular dataset and specify values accordingly. Cc An initial guess for the center of the Gaussian curve. Default = 5. The user is advised to consider values for Cc appropriate for their particular dataset and specify values accordingly. Cw An initial guess for the Gaussian curve incline. Default = 0.01. The user is advised to consider values for Cw appropriate for their particular dataset and specify values accordingly. plot A switch specifying whether to plot results. Default = T. alpha The level of Type I error to be applied to the analysis. Default = 0.05. alternative A switch specifying alternative hypothesis for statistical tests to be applied. Options include: 'one.tailed' = statistic <= 0, 'two.tailed' = statistic = 0. Default = 'one.sided'. Note: This selection must match the alternative hypothesis used in the calculation of link{commcorrelogram}. pw Weight given to significance points in proximity of alpha. The user is advised to consider values for pw appropriate for their particular dataset and specify values accordingly. lgpos A switch specify position of the legend, and passed to legend. Default = 'topleft'. ... Other parameters passed to commcorrelogram

Details

One of the main purposes of constructing a correlogram is to determine the maximum distance at which the samples are statistically similar, or range of correlation. Typically, the range of correlation of a multivariate correlogram is determined by finding on the primary plot the class for which the statistic is no longer significant. However, depending on the lag size and tolerance of the correlogram, this may not be a very precise figure. Depending on the spatial (or temporal) structure reflected in the plot, or the number of pairs in the deciding lag class, the figure may not be very accurate, either.

The approach developed here is to instead plot the significance values of the correlogram in a separate plot and model this plot to determine the point at which the curve is equal to a chosen Type I error rate (alpha, typically 0.05). In univariate geostatistics, the range of correlation is typically found by modeling the semivariogram structure function (Goovaerts, 1997). To model the correlogram significance plot, we developed a Gaussian model similar to that used to model univariate semivariograms:

y^s(h) = C_h(1-e^{C_w(h-C_C)^2})

where C_h is the curve height, C_w the curve width/steepness, C_c the curve center, and h the lag separation.

The mod.commcorrelogram() function automatically fits this Gaussian curve to commcorrelogram objects using the nlminb optimization function and calculates the correlation distance (where the resulting curve equals alpha) using the uniroot function. The function allows the user to provide initial guesses for each parameter and also allows the user to adjust the weight of points that are closest to the alpha level in the optimization routine. This enhances the fit of the curve around the alpha line. In the case where a two-tailed correlogram has been calculated, the ranges at which the modeled curve crosses the alpha/2 line (where samples are no longer statistical similar) and where it crosses the 1-alpha/2 line (where samples become statistically different), called here the "outer range" are reported.

Value

Returns a list of objects of class community.correlogram, each with different lag size used to compute them.

 model.coefficients A vector of fitted values for C_h, C_c, and C_w empirical The original empirical community correlogram used for modeling predicted A dataframe of predicted values against lag separation distance for use in external plotting or other functions range The correlation range (one.tailed analyses use model = alpha, two.tailed analyses use model=alpha/2) outer.range The outer correlation range for two.tailed analyses (model=1-alpha/2)

Plots of community correlogram metrics, significance values, modeled significance curve and the correlation range are created when plot=TRUE.

Author(s)

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

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

References

Goovaerts, P. 1997. Geostatistics for natural resources evaluation. Oxford, England: Oxford University Press.