ecospace (version 1.0.0)

calc_metrics: Calculate Ecological Disparity (Functional Diversity) Dynamics as Function of Sample Size.

Description

Wrapper to FD::dbFD that calculates common ecological disparity and functional diversity statistics. When used with species-wise simulations of community assembly or ecological diversification, calculates statistical dynamics as a function of species richness. Avoids file-sharing errors so that can be used in 'embarrasingly parallel' implementations in a high-performance computing environment.

Usage

calc_metrics(nreps = 1, samples = NA, Smax = NA, Model = "", Param = "", m = 3, corr = "lingoes", method = "Euclidean")

Arguments

nreps

Sample number to calculate statistics for. Default is the first sample nreps=1, but statistics can be calculated for other samples (i.e., second sample if nreps=2), or multiple samples if assigned a vector (sequence) of integers and function is applied within lapply or related function.

samples

Data frame (if nreps=1) or list of data frames (if nreps=seq() or nreps!=1), with each data frame a species-by-trait matrix with species as rows and traits as columns. Traits can be binary, numeric, ordered numeric, factor, or ordered factor types.

Smax

Maximum number of samples rows (species) to include in calculations, incremented starting with first row. Default (NA) is to increment to the maximum number of samples rows (calculated separately for each data frame sample, if a list of data frames).

Model

Optional character string or numeric value naming simulation model. A warning issues if left blank.

Param

Optional numeric value or character string naming strength parameter used in simulation. A warning issues if left blank.

m

The number of PCoA axes to keep as 'traits' for calculating FRic and FDiv in FD::dbFD. Default m=3 is justified below, but any integer value grater than 1 is possible. See 'details' for more information.

corr

Character string specifying the correction method to use in FD::dbFD when the species-by-species distance matrix cannot be represented in a Euclidean space. Default corr='lingoes' is justified below, but see FD::dbFD for other possible values.

method

Distance measure to use when calculating functional distances between species. Default is method='Euclidean' using stats::dist. method='Gower' or any other value uses Gower distance (using FD::gowdis). Presence of factor or ordered factor character types forces use of Gower distance.

Value

Returns a data frame (if nreps is a single integer or samples is a single data frame) or a list of data frames. Each returned data frame has Smax rows corresponding to incremental species richness (sample size) and 12 columns, corresponding to:

Model

(optional) Model name

Param

(optional) strength parameter

S

Species richness (sample size)

H

Number of functionally unique life habits

D

Mean pairwise distance

M

Maximum pairwise distance

V

Total variance

FRic

Functional richness

FEve

Functional evenness

FDiv

Functional divergence

FDis

Functional dispersion

qual.FRic

proportion ('quality') of total PCoA trait-space used when calculating FRic and FDiv

Details

The primary goal of this function is to describe the statistical dynamics of common ecological disparity (functional diversity) metrics as a function of species richness (sample size). Statistics are calculated incrementally within samples, first for the first row (species), second for the first and second rows, ..., ending with the entire sample (by default, or terminating with Smax total species). The function assumes that supplied samples are ecologically or evolutionary cohesive assemblages in which there is a logical order to the rows (such that the sixth row is the sixth species added to the assemblage) and that such incremental calculations are sensible. See Novack-Gottshall (In pressA, B) for additional context. Samples must have species as rows and traits as columns (of many allowed character types), and have class(data.frame) or a list of such data frames, with each data frame a separate sample.

Statistics calculated include four widely used in ecological disparity studies (adapted from studies of morphological disparity) and four used in functional diversity studies. See Foote (1993), Ciampaglio et al. (2001), and Wills (2001) for definitions and details on morphological disparity measures and Novack-Gottshall (2007; In press A,B) for implementation as measures of ecological disparity. See Mason et al. (2005), Anderson et al. (2006), Villeger et al. (2008), Laliberte and Legendre (2010), Mouchet et al. (2010), Mouillot et al. (2013) for definitions and details on functional diversity statistics. For computation details of functional diversity metrics, see Laliberte and Shipley (2014) package FD, and especially FD::dbFD, which this function wraps around to calculate the functional diversity statistics.

Statistic (S) is species (taxonomic) richness, or sample size.

Statistics that measure disparity (or dispersion of species within ecospace / functional-trait space):

H

Life habit richness, the number of functionally unique trait combinations.

M

Maximum pairwise distance between species in functional-trait space, measured using the distance method specified above.

V

Total variance, the sum of variances for each functional trait across species; when using factor or ordered factor character types, this statistic cannot be measured and is left blank, with a warning.

FRic

Functional richness, the minimal convex-hull volume in multidimensional principal coordinates analysis (PCoA) trait-space ordination.

FDis

Functional dispersion, the total deviance of species from the circle with radius equal to mean distance from PCoA trait-space centroid.

Statistics that measure internal structure (i.e., clumping or inhomogeneities within the trait-space):

M

Mean pairwise distance between species in functional-trait space, measured using the distance method specified above.

FDiv

Functional divergence, the mean distance of species from the PCoA trait-space centroid.

Statistics that measure the extent of spacing among species within the trait-space:

FEve

Functional evenness, the evenness of minimum-spanning-tree lengths between species in PCoA trait-space.

The default number of PCoA axes used in calculating of FRic and FDiv equals m=3. Because their calculation requires more species than traits (here the m=3 PCoA axes), the four functional diversity statistics are only calculated when a calculated sample contains a minimum of m species (S) or unique life habtis (H). qual.FRic is appended to the output to record the proportion ('quality') of PCoA space retained by this loss of dimenstionality. Although including more PCoA axes allows greater statistical power (Villeger et al. 2011, Maire et al. 2015), the use of m=3 here is computationally manageable, ecologically meaningful, and allows standardized measurement of statistical dynamics across the wide range of sample sizes typically involved in simulations of ecological/evolutionary assemblages, especially when functionally redundant data occur. Other integers greater than 1 can also be specified. See the help file for FD::dbFD for additional information.

Lingoes correction corr='lingoes',as recommended by Legendre and Anderson (1999), is called when the species-by-species distance matrix cannot be represented in a Euclidean space. See the help file for FD::dbFD for additional information.

References

Anderson, M. J., K. E. Ellingsen, and B. H. McArdle. 2006. Multivariate dispersion as a measure of beta diversity. Ecology Letters 9(6):683-693.

Ciampaglio, C. N., M. Kemp, and D. W. McShea. 2001. Detecting changes in morphospace occupation patterns in the fossil record: characterization and analysis of measures of disparity. Paleobiology 27(4):695-715.

Foote, M. 1993. Discordance and concordance between morphological and taxonomic diversity. Paleobiology 19:185-204.

Laliberte, E., and P. Legendre. 2010. A distance-based framework for measuring functional diversity from multiple traits. Ecology 91(1):299-305.

Legendre, P., and M. J. Anderson. 1999. Distance-based redundancy analysis: testing multispecies responses in multifactorial ecological experiments. Ecological Monographs 69(1):1-24.

Maire, E., G. Grenouillet, S. Brosse, and S. Villeger. 2015. How many dimensions are needed to accurately assess functional diversity? A pragmatic approach for assessing the quality of functional spaces. Global Ecology and Biogeography 24(6):728-740.

Mason, N. W. H., D. Mouillot, W. G. Lee, and J. B. Wilson. 2005. Functional richness, functional evenness and functional divergence: the primary components of functional diversity. Oikos 111(1):112-118.

Mouchet, M. A., S. Villeger, N. W. H. Mason, and D. Mouillot. 2010. Functional diversity measures: an overview of their redundancy and their ability to discriminate community assembly rules. Functional Ecology 24(4):867-876.

Mouillot, D., N. A. J. Graham, S. Villeger, N. W. H. Mason, and D. R. Bellwood. 2013. A functional approach reveals community responses to disturbances. Trends in Ecology and Evolution 28(3):167-177.

Novack-Gottshall, P.M. 2007. Using a theoretical ecospace to quantify the ecological diversity of Paleozoic and modern marine biotas. Paleobiology 33: 274-295.

Novack-Gottshall, P.M. In review at Paleobiology, submitted Oct. 5, 2015. General models of ecological diversification. I. Conceptual synthesis.

Novack-Gottshall, P.M. In review at Paleobiology, submitted Oct. 5, 2015. General models of ecological diversification. II. Simulations and empirical applications.

Villeger, S., N. W. H. Mason, and D. Mouillot. 2008. New multidimensional functional diversity indices for a multifaceted framework in functional ecology. Ecology 89(8):2290-2301.

Villeger, S., P. M. Novack-Gottshall, and D. Mouillot. 2011. The multidimensionality of the niche reveals functional diversity changes in benthic marine biotas across geological time. Ecology Letters 14(6):561-568.

Wills, M. A. 2001. Morphological disparity: a primer. Pp. 55-143. In J. M. Adrain, G. D. Edgecombe, and B. S. Lieberman, eds. Fossils, phylogeny, and form: an analytical approach. Kluwer Academic/Plenum Publishers, New York.

Laliberte, E., and B. Shipley. 2014. FD: Measuring functional diversity from multiple traits, and other tools for functional ecology, Version 1.0-12.

See Also

FD::dbFD for details on the core function wrapped here for calculating functional diversity statistics. neutral, redundancy, partitioning, expansion for building samples using simulations. rbind_listdf for efficient way to combine lists of data frames for subsequent analyses.

Examples

# Build ecospace framework and a random 50-species sample using neutral rule:
ecospace <- create_ecospace(nchar=15, char.state=rep(3, 15), char.type=rep("numeric", 15))
sample <- neutral(Sseed=5, Smax=50, ecospace=ecospace)
# Using Smax=10 here for fast example
metrics <- calc_metrics(samples=sample, Smax=10, Model="Neutral", Param="NA")
metrics

# Plot statistical dynamics as function of species richness
op <- par()
par(mfrow=c(2,4), mar=c(4, 4, 1, .3))
attach(metrics)
plot(S, H, type="l", cex=.5)
plot(S, D, type="l", cex=.5)
plot(S, M, type="l", cex=.5)
plot(S, V, type="l", cex=.5)
plot(S, FRic, type="l", cex=.5)
plot(S, FEve, type="l", cex=.5)
plot(S, FDiv, type="l", cex=.5)
plot(S, FDis, type="l", cex=.5)

par(op)

# Can take a few minutes to run to completion
# Calculate for 5 samples
nreps <- 1:5
samples <- lapply(X=nreps, FUN=neutral, Sseed=5, Smax=50, ecospace)
metrics <- lapply(X=nreps, FUN=calc_metrics, samples=samples, Model="Neutral", Param="NA")
alarm()
str(metrics)