FidelityEst: Compositional measures of live-dead fidelity

In MJKowalewski/PaleoFidelity: Analyze and Visualize Agreement between Live and Dead Communities

Compositional measures of live-dead fidelity

Description

FidelityEst estimates compositional fidelity by comparing two matching (live and dead) matrices with community abundance data. The function returns fidelity measures for individual sites, mean measures across sites, and means for groups of sites. The function also returns sample-standardized, bias-corrected and 'perfect fidelity' estimates.

Usage

FidelityEst(
  live,
  dead,
  gp = NULL,
  cor.measure = "spearman",
  sim.measure = "chao",
  n.filters = 0,
  t.filters = 1,
  report = FALSE,
  iter = 10,
  iter2 = 10,
  min.sam = 30,
  CI = 0.95,
  rm.zero = FALSE,
  tfsd = "none"
)

Arguments

live	A matrix with counts of live-collected specimens (rows=sites, columns=species or other variable). Dimensions and 'rownames' and 'colnames' of 'live' and 'dead' matrices must match exactly.
dead	A matrix with counts of dead-collected specimens (rows=sites, columns=species or other variables). Dimensions and 'rownames' and 'colnames' of 'live' and 'dead' matrices must match exactly.
gp	An optional univariate factor defining groups of sites. The length of 'gp' must equal number of rows of 'live' and 'dead' matrices.
cor.measure	A character string (default='spearman') defining correlation measure (passed on to cor function) used to estimate live-dead correlations.
sim.measure	A character string (default='chao') defining similarity measure (passed on to vegdist) used to estimate live-dead similarity.
n.filters	An integer used to filter out small samples (default n.filters=0, all samples kept).
t.filters	An integer used to filter out rare taxa (default t.filters=1, all taxa with at least one occurrence kept).
report	Logical (default report = FALSE) (suppresses notes, warnings and data summary).
iter	An integer defining number of replicate samples for perfect fidelity resampling model (default iter = 10).
iter2	An integer defining number of resampling iteration for subsampling standardization (default iter2 = 10).
min.sam	An integer defining number of specimens for sample standardization (default = 30).
CI	A numerical value (default = 0.95) defining confidence limits for adjusted and sample-standardized estimates of fidelity based on percentiles of resampled estimates of sample-standardized, bias-corrected, or 'perfect fidelity' measures of correlation/similarity.
rm.zero	Logical (default rm.zero = FALSE) removes double 0's when computing correlation measure.
tfsd	A character string (default='none') specifying data standardization or transformations (applicable only for some similarity measure).The following options are available: 'none' (or any unused character string) - no standardization/transformation, 'total' - relative abundance, 'wisconsin' - double relativization, 'r4' - 4th root transformation, 'log' - ecological log-transformation, 'total4' - 4th root transformation of relative abundances.

Details

FidelityEst assesses compositional fidelity using measures of correlation/associations/similarity.

(1) x - a measure of correlation/association: Spearman, Kendall, or Pearson (2) y - an abundance-based index of similarity such as Bray or Jaccard-Chao

Because fidelity measures are sensitive to under-sampling and unbalanced sampling, FidelityEst function attempts to correct for sampling biases by (1) estimating data-specific biases or (2) standardizing sampling coverage. In the first approach, the bias is estimated using a resampling protocol under the perfect fidelity (PF) model, in which pooled data (live + dead) are randomly partitioned into replicate pairs of samples (using sample sizes of original samples), thus creating sample pairs derived from single underlying rank abundance species distributions (i.e., the perfect fidelity). For an unbiased estimator, the resampled fidelity measures should indicate perfect fidelity (e.g., Spearman rho = 1). The offset between the expected observed PF value (1 - PF) provides a data-specific estimate of sampling bias. The adjusted fidelity measure is then given by Adjusted = Observed + (1 - PF). Replicate samples produce a distribution of PF values and resulting adjusted fidelity measures, from which confidence intervals and significance tests can be derived. In the second approach, fidelity measures are computed for sample standardized data, where all samples are subsampled to a sample size given by the smallest sample. Replicate resampling produces a distribution of sample-standardized fidelity estimates used to generate confidence intervals and means for standardized fidelity estimates.

Value

A list containing the following components:

x	Live-dead correlation coefficients for each site
y	Live-dead similarity coefficients for each live-dead comparison
xc	Adjusted live-dead correlation coefficients, confidence intervals, and estimated live-dead correlation coefficients for perfect fidelity model
yc	Adjusted live-dead similarity coefficients, confidence intervals, and estimated live-dead similarity coefficients for perfect fidelity model
xs	Sample-standardized live-dead correlation coefficients, confidence intervals, and standardized sample size
ys	Sample-standardized live-dead similarity coefficients, confidence intervals, and standardized sample size
x.stats	Statistical summary for raw correlation coefficients for all data and for each group when 'gp' factor provided
y.stats	Statistical summary for raw similarity coefficients for all data and for each group when 'gp' factor provided
xc.stats	Statistical summary for adjusted correlation coefficients for all data and for each group when 'gp' factor provided
yc.stats	Statistical summary for adjusted similarity coefficients for all data and for each group when 'gp' factor provided
xs.stats	Statistical summary for sample-standardized correlation coefficients for all data and for each group when 'gp' factor provided
ys.stats	Statistical summary for sample-standardized similarity coefficients for all data and for each group when 'gp' factor provided
x.pf.dist	Distributions of randomized correlation values under perfect fidelity model for each of the live-dead sample comparison
y.pf.dist	Distributions of randomized correlation values under perfect fidelity model for each of the live-dead sample comparison
xc.dist	Distributions of model adjusted correlation values for each of the samples
yc.dist	Distributions of model adjusted similarity values for each of the samples
live	The post-processed version of 'live' data matrix used in analyses
dead	The post-processed version of 'dead' data matrix used in analyses
gp	The post-processed version of 'gp', when 'gp' factor provided
values	A list with values of parameters used in the analysis

Examples

data(FidData)
out1 <- FidelityEst(live = FidData$live[6:9,], dead = FidData$dead[6:9,],
                    gp = FidData$habitat[6:9], cor.measure='spearman',
                    sim.measure='bray', n.filters=30, iter=99, rm.zero=FALSE, tfsd='none')
SJPlot(out1, gpcol=c('forestgreen', 'coral3'))

MJKowalewski/PaleoFidelity documentation built on Aug. 25, 2024, 8:27 p.m.