Title: Community Dynamics Metrics
Version: 2.0.5
Date: 2020-11-30
Description: Univariate and multivariate temporal and spatial diversity indices, rank abundance curves, and community stability measures. The functions implement measures that are either explicitly temporal and include the option to calculate them over multiple replicates, or spatial and include the option to calculate them over multiple time points. Functions fall into five categories: static diversity indices, temporal diversity indices, spatial diversity indices, rank abundance curves, and community stability measures. The diversity indices are temporal and spatial analogs to traditional diversity indices. Specifically, the package includes functions to calculate community richness, evenness and diversity at a given point in space and time. In addition, it contains functions to calculate species turnover, mean rank shifts, and lags in community similarity between two time points. Details of the methods are available in Hallett et al. (2016) <doi:10.1111/2041-210X.12569> and Avolio et al. (2019) <doi:10.1002/ecs2.2881>.
Depends: R (≥ 3.2.0)
Imports: assertthat, stats, permute, vegan
Suggests: testthat, knitr, ggplot2, pillar, reshape2, devtools, dplyr, rmarkdown
Encoding: UTF-8
License: Apache License (== 2.0)
URL: https://github.com/NCEAS/codyn/
BugReports: https://github.com/NCEAS/codyn/issues
LazyData: true
VignetteBuilder: knitr
RoxygenNote: 7.1.1
NeedsCompilation: no
Packaged: 2020-12-01 03:16:55 UTC; jones
Author: Lauren Hallett ORCID iD [aut], Meghan L. Avolio ORCID iD [aut], Ian T. Carroll ORCID iD [aut], Sydney K. Jones [aut], A. Andrew M. MacDonald ORCID iD [aut], Dan F. B. Flynn ORCID iD [aut], Peter Slaughter ORCID iD [aut], Julie Ripplinger ORCID iD [aut], Scott L. Collins ORCID iD [aut], Corinna Gries ORCID iD [aut], Matthew B. Jones ORCID iD [aut, cre]
Maintainer: Matthew B. Jones <jones@nceas.ucsb.edu>
Repository: CRAN
Date/Publication: 2020-12-01 07:40:06 UTC

Community Dynamics Metrics

Description

Univariate and multivariate temporal and spatial diversity indices, rank abundance curves, and community stability metrics for ecologists.

Details

The functions in codyn implement metrics that are either explicitly temporal and include the option to calculate them over multiple replicates, or spatial and include the option to calculate them over multiple time points. Functions fall into five categories: static diversity indices, temporal diversity indices, spatial diversity indices, rank abundance curves, and community stability metrics. The diversity indices in codyn are temporal and spatial analogs to traditional diversity indices. Specifically, codyn includes functions to calculate community richness, evenness and diversity at a given point in space and time. In addition, codyn contains functions to calculate species turnover, mean rank shifts, and lags in community similarity between two time points. For the components of rank abundance curves, the shape of the rank abundance curve, species abundances and multivariate metrics of community composition, codyn contains functions to calculate these metrics either between time points or a single time point between two paired replicates. The community stability metrics in codyn calculate overall stability and patterns of species covariance and synchrony over time. Finally, codyn contains vignettes that describe methods and reproduce figures from published papers to help users contextualize and apply functions to their own data. Work on this package was supported by National Science Foundation grant #1262458 to the National Center for Ecological Analysis and Synthesis (NCEAS), the University of Wisconsin, and the University of New Mexico, and a SESYNC Synthesis Postdoctoral Fellowship to MLA.

Functions

Author(s)

Rank Abundance Curve Changes

Description

Calculates change of the five aspects of rank abundance curves (richness, evenness, rank, species gains, and species losses) for a replicate between two time points.

Usage

RAC_change(
  df,
  time.var,
  species.var,
  abundance.var,
  replicate.var = NULL,
  reference.time = NULL
)

Arguments

df

A data frame containing time, species, and abundance columns and an optional columns of replicates.

time.var

The name of the time column.

species.var

The name of the species column.

abundance.var

The name of the abundance column.

replicate.var

The name of the optional replicate column. If specified, replicate must be unique within the dataset and cannot be nested within treatments or blocks.

reference.time

The name of the optional time point that all other time points should be compared to (e.g. the first year of data). If not specified, each comparison is between consecutive time points (the first and second year, second and third year, etc.)

Value

The RAC_change function returns a data frame with a subset of the following columns:

References

Avolio et al. Submitted

Examples

data(pplots)
# Without replicates
df <- subset(pplots, plot == 25)
RAC_change(df = df,
           species.var = "species",
           abundance.var = "relative_cover",
           time.var = "year")

# With replicates
df <- subset(pplots, year < 2004 & plot %in% c(6, 25, 32))
RAC_change(df = df,
           species.var = "species",
           abundance.var = "relative_cover",
           replicate.var = "plot",
           time.var = "year")
           
# With reference year
df <- subset(pplots, year < 2005 & plot %in% c(6, 25, 32))
RAC_change(df = df,
           species.var = "species",
           abundance.var = "relative_cover",
           replicate.var = "plot",
           time.var = "year",
           reference.time = 2002)

Rank Abundance Curve Differences

Description

Calculates differences between two samples for four comparable aspects of rank abundance curves (richness, evenness, rank, species composition). There are three ways differences can be calculated. 1) Between treatments within a block (note: block.var and treatment.var need to be specified). 2) Between treatments, pooling all replicates into a single species pool (note: pool = TRUE, treatment.var needs to be specified, and block.var will be NULL). 3) All pairwise combinations between all replicates (note: block.var = NULL, pool = FALSE and specifying treatment.var is optional. If treatment.var is specified, the treatment that each replicate belongs to will also be listed in the output).

Usage

RAC_difference(
  df,
  time.var = NULL,
  species.var,
  abundance.var,
  replicate.var,
  treatment.var = NULL,
  pool = FALSE,
  block.var = NULL,
  reference.treatment = NULL
)

Arguments

df

A data frame containing a species, abundance, and replicate columns and optional time, treatment, and block columns.

time.var

The name of the optional time column.

species.var

The name of the species column.

abundance.var

The name of the abundance column.

replicate.var

The name of the replicate column. Replicate identifiers must be unique within the dataset and cannot be nested within treatments or blocks.

treatment.var

The name of the optional treatment column.

pool

An argument to allow abundance values to be pooled within a treatment. The default value is "FALSE", a value of "TRUE" averages abundance of each species within a treatment at a given time point.

block.var

The name of the optional block column.

reference.treatment

The name of the optional treatment that all other treatments will be compared to (e.g. only controls will be compared to all other treatments). If not specified all pairwise treatment comparisons will be made.

Value

The RAC_difference function returns a data frame with the following attributes:

References

Avolio et al. Submitted

Examples

data(pplots)
# With block and no time
df <- subset(pplots, year == 2002 & block < 3)
RAC_difference(df = df,
               species.var = "species",
               abundance.var = "relative_cover",
               treatment.var = 'treatment',
               block.var = "block",
               replicate.var = "plot")

# With blocks and time
df <- subset(pplots, year < 2004 & block < 3)
RAC_difference(df = df,
               species.var = "species",
               abundance.var = "relative_cover",
               treatment.var = 'treatment',
               block.var = "block",
               replicate.var = "plot",
               time.var = "year")

# With blocks, time and reference treatment
df <- subset(pplots, year < 2004 & block < 3)
RAC_difference(df = df,
               species.var = "species",
               abundance.var = "relative_cover",
               treatment.var = 'treatment',
               block.var = "block",
               replicate.var = "plot",
               time.var = "year",
               reference.treatment = "N1P0")

# Pooling by treatment with time
df <- subset(pplots, year < 2004)
RAC_difference(df = df,
               species.var = "species",
               abundance.var = "relative_cover",
               treatment.var = 'treatment',
               pool = TRUE,
               replicate.var = "plot",
               time.var = "year")

# All pairwise replicates with treatment
df <- subset(pplots, year < 2004 & plot %in% c(21, 25, 32))
RAC_difference(df = df,
               species.var = "species",
               abundance.var = "relative_cover",
               replicate.var = "plot",
               time.var = "year",
               treatment.var = "treatment")

# All pairwise replicates without treatment
df <- subset(pplots, year < 2004 & plot %in% c(21, 25, 32))
RAC_difference(df = df,
               species.var = "species",
               abundance.var = "relative_cover",
               replicate.var = "plot",
               time.var = "year")

Species Abundance Changes

Description

Calculates the abundance change for species in a replicate between two time points. Changes are on abundance values provided, if relative data is used, then changes in relative abundance will be calculated.

Usage

abundance_change(
  df,
  time.var,
  species.var,
  abundance.var,
  replicate.var = NULL,
  reference.time = NULL
)

Arguments

df

A data frame containing time, species, and abundance columns and an optional columns of replicates.

time.var

The name of the time column.

species.var

The name of the species column.

abundance.var

The name of the abundance column.

replicate.var

The name of the optional replicate column. If specified, replicate must be unique within the dataset and cannot be nested within treatments or blocks.

reference.time

The name of the optional time point that all other time points should be compared to (e.g. the first year of data). If not specified, each comparison is between consecutive time points (the first and second year, second and third year, etc.)

Value

The abundance_change function returns a data frame with a subset of the following columns:

References

Avolio et al. Submitted

Examples

data(pplots)
# Without replicates
df <- subset(pplots, plot == 25)
abundance_change(df = df,
                 species.var = "species",
                 abundance.var = "relative_cover",
                 time.var = "year")

# With replicates
df <- subset(pplots, year < 2004 & plot %in% c(6, 25, 32))
abundance_change(df = df,
                 species.var = "species",
                 abundance.var = "relative_cover",
                 replicate.var = "plot",
                 time.var = "year")
                 
# With reference year
df <- subset(pplots, year < 2005 & plot %in% c(6, 25, 32))
abundance_change(df = df,
                 species.var = "species",
                 abundance.var = "relative_cover",
                 replicate.var = "plot",
                 time.var = "year",
                 reference.time = 2002)

Abundance Differences

Description

Calculates the abundance difference for species between two samples. Differences are on abundance values provided, if relative data is used, then differences in relative abundance will be calculated. There are three ways differences can be calculated. 1) Between treatments within a block (note: block.var and treatment.var need to be specified). 2) Between treatments, pooling all replicates into a single species pool (note: pool = TRUE, treatment.var needs to be specified, and block.var = NULL). 3) All pairwise combinations between all replicates (note: block.var = NULL, pool = FALSE and specifying treatment.var is optional. If treatment.var is specified, the treatment that each replicate belongs to will also be listed in the output).

Usage

abundance_difference(
  df,
  time.var = NULL,
  species.var,
  abundance.var,
  replicate.var,
  treatment.var = NULL,
  pool = FALSE,
  block.var = NULL,
  reference.treatment = NULL
)

Arguments

df

A data frame containing a species, abundance, and replicate columns and optional time, treatment, and block columns.

time.var

The name of the optional time column.

species.var

The name of the species column.

abundance.var

The name of the abundance column.

replicate.var

The name of the replicate column. Replicate identifiers must be unique within the dataset and cannot be nested within treatments or blocks.

treatment.var

The name of the optional treatment column.

pool

An argument to allow abundance values to be pooled within a treatment. The default value is "FALSE", a value of "TRUE" averages abundance of each species within a treatment at a given time point.

block.var

The name of the optional block column.

reference.treatment

The name of the optional treatment that all other treatments will be compared to (e.g. only controls will be compared to all other treatments). If not specified all pairwise treatment comparisons will be made.

Value

The abundance_difference function returns a data frame with a subset of the following columns:

References

Avolio et al. Submitted

Examples

data(pplots)
# With block and no time
df <- subset(pplots, year == 2002 & block < 3)
abundance_difference(df = df,
                     species.var = "species",
                     abundance.var = "relative_cover",
                     treatment.var = "treatment",
                     block.var = "block",
                     replicate.var = "plot")

# With blocks and time
df <- subset(pplots, year < 2004 & block < 3)
abundance_difference(df = df,
                     species.var = "species",
                     abundance.var = "relative_cover",
                     treatment.var = "treatment",
                     block.var = "block",
                     replicate.var = "plot",
                     time.var = "year")

# With blocks, time and reference treatment
df <- subset(pplots, year < 2004 & block < 3)
abundance_difference(df = df,
                     species.var = "species",
                     abundance.var = "relative_cover",
                     treatment.var = "treatment",
                     block.var = "block",
                     replicate.var = "plot",
                     time.var = "year",
                     reference.treatment = "N1P0")

# Pooling by treatment with time
df <- subset(pplots, year < 2004)
abundance_difference(df = df,
                     species.var = "species",
                     abundance.var = "relative_cover",
                     treatment.var = "treatment",
                     pool = TRUE,
                     replicate.var = "plot",
                     time.var = "year")

# All pairwise replicates with treatment
df <- subset(pplots, year < 2004 & plot %in% c(21, 25, 32))
abundance_difference(df = df,
                     species.var = "species",
                     abundance.var = "relative_cover",
                     replicate.var = "plot",
                     time.var = "year",
                     treatment.var = "treatment")

# All pairwise replicates without treatment
df <- subset(pplots, year < 2004 & plot %in% c(21, 25, 32))
abundance_difference(df = df,
                     species.var = "species",
                     abundance.var = "relative_cover",
                     replicate.var = "plot",
                     time.var = "year")

Konza data from Collins et al. 2008

Description

A dataset of tallgrass prairie plant composition at one annually burned and one unburned site over time at the Konza Prairie LTER, Manhattan Kansas (Collins et al. 2008).

Usage

data(collins08)

Format

A data frame with 2058 rows and 4 variables

Details

A data frame containing a column for replicate, year, species and abundance:

Source

Collins, Scott L., Katharine N. Suding, Elsa E. Cleland, Michael Batty, Steven C. Pennings, Katherine L. Gross, James B. Grace, Laura Gough, Joe E. Fargione, and Christopher M. Clark. (2008) "Rank clocks and plant community dynamics." Ecology 89, no. 12: 3534-41.

Community Diversity

Description

Calculates Shannon's or Inverse Simpson's diversity of a community, but only one measure of diversity can be calculated at a time and must be specified.

Usage

community_diversity(
  df,
  time.var = NULL,
  abundance.var,
  replicate.var = NULL,
  metric = c("Shannon", "InverseSimpson")
)

Arguments

df

A data frame containing species and abundance columns and optional columns of time and/or replicate.

time.var

The name of the optional time column

abundance.var

The name of the abundance column

replicate.var

The name of the optional replicate column. If specified, replicate must be unique within the dataset and cannot be nested within treatments or blocks.

metric

The diversity measure to return:

  • "Shannon": The default measure, calculates Shannon's diversity.

  • "InverseSimpson": Calculates inverse of Simpson's diversity.

Value

The community_diversity function returns a data frame with the following attributes:

References

Magurran, A.E. 2004. Measuring Biological Diversity. Blackwell Publishing, Malden MA, USA.

Examples

data(pplots)
#Example with both time and replicates
df <- subset(pplots, plot == 25 | plot == 6)
community_diversity(df,
                    time.var="year", 
                    replicate.var = "plot", 
                    abundance.var = "relative_cover") # for Shannon's diversity measure

df <- subset(pplots, plot == 25 | plot == 6)
community_diversity(df, 
                    time.var="year", 
                    replicate.var = "plot", 
                    abundance.var = "relative_cover", 
                    metric = "InverseSimpson") # for Inverse of Simpson's diversity measure

#Example with no replicates
df <- subset(pplots, plot == 25)
community_diversity(df,
                    time.var="year", 
                    abundance.var = "relative_cover") # for Shannon's diversity measure
                    
#Example with no time or replicate
df <- subset(pplots, plot == 25 & year == 2002)
community_diversity(df,
                    abundance.var = "relative_cover") # for Shannon's diversity measure

Community Stability

Description

Calculates the stability of the overall community over time as the temporal mean / temporal standard deviation of aggregate species abundances (Tilman 1999).

Usage

community_stability(df, time.var, abundance.var, replicate.var = NA)

Arguments

df

A data frame containing time, species and abundance columns and an optional column of replicates

time.var

The name of the time column

abundance.var

The name of the abundance column

replicate.var

The name of the optional replicate column

Details

The input data frame needs to contain columns for time, species and abundance; time.var, species.var and abundance.var are used to indicate which columns contain those variables. If multiple replicates are included in the data frame, that column should be specified with replicate.var. Each replicate should reflect a single experimental unit - there should be a single community represented within each time point and replicate.

Value

The community_stability function returns a numeric stability value unless a replication column is specified in the input data frame. If replication is specified, the function returns a data frame with the following columns:

References

Tilman, D. "The Ecological Consequences of Changes in Biodiversity: A Search for General Principles." Ecology 80, no. 5 (July 1999): 1455-74. doi:10.1890/0012-9658(1999)080[1455:TECOCI]2.0.CO;2.

Examples

data(knz_001d)
community_stability(knz_001d[knz_001d$subplot=="A_1",], 
                     time.var = "year", 
                     abundance.var = "abundance") # for one subplot
community_stability(knz_001d,
                     time.var = "year", 
                     abundance.var = "abundance",
                     replicate.var = "subplot") # across all subplots

Community Structure

Description

Calculates species richness and evenness of a community. Evenness may be calculated as Simpson's (1/D/S), EQ, or Evar, but only one metric of evenness can be calculated at a time and must be specified.

Usage

community_structure(
  df,
  time.var = NULL,
  abundance.var,
  replicate.var = NULL,
  metric = c("Evar", "SimpsonEvenness", "EQ")
)

Arguments

df

A data frame containing species and abundance columns and optional columns of time and/or replicate.

time.var

The name of the optional time column

abundance.var

The name of the abundance column

replicate.var

The name of the optional replicate column. If specified, replicate must be unique within the dataset and cannot be nested within treatments or blocks.

metric

The measure of evenness to return:

  • "Evar": The default measure, calculates evenness as Evar from Smith and Wilson 1996

  • "SimpsonEvenness": Calculates Simpson's evenness

  • "EQ": Calculates evenness as EQ from Smith and Wilson 1996

Value

The community_structure function returns a data frame with the following attributes:

References

Smith, B. and Wilson, J. B. 1996. A consumer's guide to evenness indices. Oikos 76: 70-82.

Examples

data(pplots)
#Example with both time and replicates
df <- subset(pplots, plot == 25 | plot == 6)
community_structure(df, 
                    time.var="year", 
                    replicate.var = "plot", 
                    abundance.var = "relative_cover") # for Evar evenness measure

df <- subset(pplots, plot == 25 | plot == 6)
community_structure(df,
                    time.var="year", 
                    replicate.var = "plot", 
                    abundance.var = "relative_cover", 
                    metric = "SimpsonEvenness") # for Simpson's evenness measure

#Example with no replicates
df <- subset(pplots, plot == 25)
community_structure(df, 
                    time.var="year", 
                    abundance.var = "relative_cover",
                    metric = "EQ") # for EQ evenness measure

#Example with only a single time point and no replicates
df <- subset(pplots, plot == 25 & year == 2002)
community_structure(df, 
                    abundance.var = "relative_cover") # for Evar evenness measure

Confidence Intervals from a Cyclic Shift Permutation

Description

Calculates confidence intervals for the S3 object produced by cyclic_shift

Usage

## S3 method for class 'cyclic_shift'
confint(object, parm = "out", level = 0.95, ...)

Arguments

object

An object of class cyclic_shift

parm

which parameter is to be given a confidence interval. At present there is only one option: the mean of the null distribution. Defaults to "out", referring to the null distribution in objects of class cyclic_shift.

level

the confidence level required.

...

further arguments to quantile

Value

A dataframe with the following columns:

References

Hallett, Lauren M., Joanna S. Hsu, Elsa E. Cleland, Scott L. Collins, Timothy L. Dickson, Emily C. Farrer, Laureano A. Gherardi, et al. "Biotic Mechanisms of Community Stability Shift along a Precipitation Gradient." Ecology 95, no. 6 (2014): 1693-1700.

Harms, Kyle E., Richard Condit, Stephen P. Hubbell, and Robin B. Foster. "Habitat Associations of Trees and Shrubs in a 50-Ha Neotropical Forest Plot." Journal of Ecology 89, no. 6 (2001): 947-59.

Examples

# Calculate a covariance matrix on a null community
data(knz_001d)
a1_cyclic <- cyclic_shift(subset(knz_001d, subplot == "A_1"),
                   time.var = "year",
                   species.var = "species",
                   abundance.var = "abundance",
                   FUN = cov,
                   bootnumber = 10)

# Return CI on a1_cyclic
confint(a1_cyclic)

Curve Change

Description

Calculates the area difference between two rank abundance curves between two time periods. If replicate is specified, it must be measured in both time points, otherwise it will be dropped for that time period comparison.

Usage

curve_change(
  df,
  time.var,
  species.var,
  abundance.var,
  replicate.var = NULL,
  reference.time = NULL
)

Arguments

df

A data frame containing time, species, and abundance columns and an optional columns of replicates.

time.var

The name of the time column.

species.var

The name of the species column.

abundance.var

The name of the abundance column.

replicate.var

The name of the optional replicate column. If specified, replicate must be unique within the dataset and cannot be nested within treatments or blocks.

reference.time

The name of the optional time point that all other time points should be compared to (e.g. the first year of data). If not specified, each comparison is between consecutive time points (the first and second year, second and third year, etc.)

Value

The curve_change function returns a data frame with the following attributes:

References

Avolio et al. Submitted

Examples

data(pplots)
# Without replicates
df <- subset(pplots, plot == 25)
curve_change(df = df,
           species.var = "species",
           abundance.var = "relative_cover",
           time.var = "year")

# With replicates
df <- subset(pplots, year < 2004 & plot %in% c(6, 25, 32))
curve_change(df = df,
           species.var = "species",
           abundance.var = "relative_cover",
           replicate.var = "plot",
           time.var = "year")
           
# With reference year
df <- subset(pplots, year < 2005 & plot %in% c(6, 25, 32))
curve_change(df = df,
           species.var = "species",
           abundance.var = "relative_cover",
           replicate.var = "plot",
           time.var = "year",
           reference.time = 2002)

Curve Difference

Description

Calculates the area difference between two rank abundance curves. There are three ways differences can be calculated. 1) Between all treatments within a block (note: block.var and treatment.var need to be specified. 2) Between treatments, pooling all replicates into a single species pool (note: pool = TRUE, treatment.var needs to be specified, and block.var = NULL. 3) All pairwise combinations between all replicates (note:block.var = NULL, pool = FALSE and specifying treatment.var is optional. If treatment.var is specified, the treatment that each replicate belongs to will also be listed in the output).

Usage

curve_difference(
  df,
  time.var = NULL,
  species.var,
  abundance.var,
  replicate.var,
  treatment.var = NULL,
  pool = FALSE,
  block.var = NULL,
  reference.treatment = NULL
)

Arguments

df

A data frame containing a species, abundance, and replicate columns and optional time, treatment, and block columns.

time.var

The name of the optional time column.

species.var

The name of the species column.

abundance.var

The name of the abundance column.

replicate.var

The name of the replicate column. Replicate identifiers must be unique within the dataset and cannot be nested within treatments or blocks.

treatment.var

The name of the optional treatment column.

pool

An argument to allow abundance values to be pooled within a treatment. The default value is "FALSE", a value of "TRUE" averages abundance of each species within a treatment at a given time point.

block.var

The name of the optional block column.

reference.treatment

The name of the optional treatment that all other treatments will be compared to (e.g. only controls will be compared to all other treatments). If not specified all pairwise treatment comparisons will be made.

Value

The curve_difference function returns a data frame with the following attributes:

References

Avolio et al. Submitted

Examples

data(pplots)
# With block and no time
df <- subset(pplots, year == 2002 & block < 3)
curve_difference(df = df,
                 species.var = "species",
                 abundance.var = "relative_cover",
                 treatment.var = "treatment",
                 block.var = "block",
                 replicate.var = "plot")

# With blocks and time
df <- subset(pplots, year < 2004 & block < 3)
curve_difference(df = df,
                 species.var = "species",
                 abundance.var = "relative_cover",
                 treatment.var = "treatment",
                 block.var = "block",
                 replicate.var = "plot",
                 time.var = "year")

# With blocks, time, and reference treatment
df <- subset(pplots, year < 2004 & block < 3)
curve_difference(df = df,
                 species.var = "species",
                 abundance.var = "relative_cover",
                 treatment.var = "treatment",
                 block.var = "block",
                 replicate.var = "plot",
                 time.var = "year",
                 reference.treatment = "N1P0")

# Pooling by treatment with time
df <- subset(pplots, year < 2004)
curve_difference(df = df,
                 species.var = "species",
                 abundance.var = "relative_cover",
                 treatment.var = "treatment",
                 pool = TRUE,
                 replicate.var = "plot",
                 time.var = "year")

# All pairwise replicates with treatment
df <- subset(pplots, year < 2004 & plot %in% c(21, 25, 32))
curve_difference(df = df,
                 species.var = "species",
                 abundance.var = "relative_cover",
                 replicate.var = "plot",
                 time.var = "year",
                 treatment.var = "treatment")

# All pairwise replicates without treatment
df <- subset(pplots, year < 2004 & plot %in% c(21, 25, 32))
curve_difference(df = df,
                 species.var = "species",
                 abundance.var = "relative_cover",
                 replicate.var = "plot",
                 time.var = "year")

Cyclic Shift Permutations

Description

Performs a user-specified function on a null ecological community created via cyclic shift permutations (Harms et al. 2001, Hallett et al. 2014). The null community is formed by randomly selected different starting years for the time series of each species. This generates a null community matrix in which species abundances vary independently but within-species autocorrelation is maintained. The user-specified function must require a species x time input.

Usage

cyclic_shift(
  df,
  time.var,
  species.var,
  abundance.var,
  replicate.var = NA,
  FUN,
  bootnumber
)

Arguments

df

A data frame containing time, species and abundance columns and an optional column of replicates

time.var

The name of the time column

species.var

The name of the species column

abundance.var

The name of the abundance column

replicate.var

The name of the replicate column. Defaults to NA, indicating no replicates (i.e., data are from a single plot).

FUN

A function to calculate on the null community

bootnumber

Number of null simulations to run

Details

The input data frame needs to contain columns for time, species and abundance; time.var, species.var and abundance.var are used to indicate which columns contain those variables.

Value

The cyclic_shift function returns an S3 object of class "cyclic_shift" and parameter "out". The length of the "out" parameter is the number of null iterations as specified by bootnumber. If multiple replicates are specified, null values are averaged among replicates for each iteration, but a different cyclic shift permutation is applied to each replicate within an iteration.

References

Hallett, Lauren M., Joanna S. Hsu, Elsa E. Cleland, Scott L. Collins, Timothy L. Dickson, Emily C. Farrer, Laureano A. Gherardi, et al. "Biotic Mechanisms of Community Stability Shift along a Precipitation Gradient." Ecology 95, no. 6 (2014): 1693-1700.

Harms, Kyle E., Richard Condit, Stephen P. Hubbell, and Robin B. Foster. "Habitat Associations of Trees and Shrubs in a 50-Ha Neotropical Forest Plot." Journal of Ecology 89, no. 6 (2001): 947-59.

Examples

# Calculate a covariance matrix on a null community
data(knz_001d)
a1_cyclic <- cyclic_shift(subset(knz_001d, subplot == "A_1"),
                   time.var = "year",
                   species.var = "species",
                   abundance.var = "abundance",
                   FUN = cov,
                   bootnumber = 10)

Data from Konza Prairie, watershed 001d

Description

Plant composition within multiple replicates at an annually burned tallgrass prairie site in the Konza Prairie LTER, Manhattan KS (Watershed 001d).

Usage

data(knz_001d)

Format

A data frame with 8768 rows and 4 variables

Details

A data frame containing a column for species, year, subplot and abundance:

Source

Konza Prairie LTER Dataset ID: PVC02, watershed 1D

Collins, S. L. (2000) Disturbance frequency and community stability in native tallgrass prairie. American Naturalist 155:311-325.

Mean Rank Shifts

Description

A measure of the relative change in species rank abundances, which indicates shifts in relative abundances over time (Collins et al. 2008). Mean rank shifts are calculated as the average difference in species' ranks between consecutive time periods, among species that are present across the entire time series.

Usage

mean_rank_shift(
  df,
  time.var,
  species.var,
  abundance.var,
  replicate.var = as.character(NA)
)

Arguments

df

A data frame containing time, species and abundance columns and an optional column of replicates

time.var

The name of the time column

species.var

The name of the species column

abundance.var

The name of the abundance column

replicate.var

The name of the optional replicate column

Details

The input data frame needs to contain columns for time, species and abundance; time.var, species.var and abundance.var are used to indicate which columns contain those variables. If multiple replicates are included in the data frame, that column should be specified with replicate.var. Each replicate should reflect a single experimental unit - there must be a single abundance value per species within each time point and replicate.

Value

mean_rank_shift returns a data frame with the following columns:

Using dissimilarity-based measures to calculate changes in composition and dispersion

Description

Calculates the changes in composition and dispersion based off a Bray-Curtis dissimilarity matrix. Composition change is the pairwise distance between centroids of compared time periods and ranges from 0-1, where identical communities give 0 and completely different communities give 1. Dispersion change is the difference between time periods in the dispersion of replicates, i.e. the average distance between a replicate and its centroid.

Usage

multivariate_change(
  df,
  time.var,
  species.var,
  abundance.var,
  replicate.var,
  treatment.var = NULL,
  reference.time = NULL
)

Arguments

df

A data frame containing time, species, abundance and replicate columns and an optional column of treatment.

time.var

The name of the time column.

species.var

The name of the species column.

abundance.var

The name of the abundance column.

replicate.var

The name of the replicate column. Replicate identifiers must be unique within the dataset and cannot be nested within treatments or blocks.

treatment.var

The name of the optional treatment column.

reference.time

The name of the optional time point that all other time points should be compared to (e.g. the first year of data). If not specified, each comparison is between consecutive time points (the first and second year, second and third year, etc.)

Value

The multivariate_change function returns a data frame with the following attributes:

References

Avolio et al. 2015; Avolio et al. Submitted, Marti Anderson et al. 2006.

Examples

data(pplots)
# With treatment
multivariate_change(pplots,
                    time.var="year",
                    replicate.var = "plot",
                    treatment.var = "treatment",
                    species.var = "species",
                    abundance.var = "relative_cover")
# In each year there are 6 replicates and there are 4 years of data for 3
# time comparisons, thus 24 total observations in each treatment.

# With treatment and reference year
multivariate_change(pplots,
                    time.var="year",
                    replicate.var = "plot",
                    treatment.var = "treatment",
                    species.var = "species",
                    abundance.var = "relative_cover",
                    reference.time = 2002)
# In each year there are 6 replicates and there are 4 years of data for 3
# time comparisons, thus 24 total observations in each treatment.

# Without treatment
df <- subset(pplots, treatment == "N1P0")
multivariate_change(df,
                    time.var="year",
                    replicate.var = "plot",
                    species.var = "species",
                    abundance.var = "relative_cover")
# In each year there are 6 replicates and there are 4 years of data for 3
# time comparisons, thus 24 total observations.

Using dissimilarity-based measures to calculate differences in composition and dispersion between pairs of treatments at a single time point

Description

Calculates the difference in composition and dispersion between treatments based off a Bray-Curtis dissimilarity matrix at a single point in time. Composition difference is the pairwise distance between centroids of compared treatments and ranges from 0-1, where identical communities give 0 and completely different communities give 1. Dispersion difference is the difference between treatments in the dispersion of replicates, i.e. the average distance between a replicate and its centroid.

Usage

multivariate_difference(
  df,
  time.var = NULL,
  species.var,
  abundance.var,
  replicate.var,
  treatment.var,
  reference.treatment = NULL
)

Arguments

df

A data frame containing a species, abundance, replicate, and treatment columns and optional time column.

time.var

The name of the optional time column.

species.var

The name of the species column.

abundance.var

The name of the abundance column.

replicate.var

The name of the replicate column. Replicate identifiers must be unique within the dataset and cannot be nested within treatments or blocks.

treatment.var

The name of the treatment column.

reference.treatment

The name of the optional treatment that all other treatments will be compared to (e.g. only controls will be compared to all other treatments). If not specified all pairwise treatment comparisons will be made.

Value

The multivariate_difference function returns a data frame with the following attributes:

References

Avolio et al. Submitted, Avolio et al. 2015, Marti Anderson et al. 2006

Examples

data(pplots)
# Without time
df <- subset(pplots, year == 2002)
multivariate_difference(df,
                        replicate.var = "plot",
                        treatment.var = "treatment",
                        species.var = "species",
                        abundance.var = "relative_cover")
# There are 6 replicates for each of three treatments, thus 18 total
# observations.

# Without time and with reference treatment
df <- subset(pplots, year == 2002)
multivariate_difference(df,
                        replicate.var = "plot",
                        treatment.var = "treatment",
                        species.var = "species",
                        abundance.var = "relative_cover",
                        reference.treatment = "N1P0")
# There are 6 replicates for each of three treatments, thus 18 total
# observations.

# With time
multivariate_difference(pplots,
                        time.var = "year",
                        replicate.var = "plot",
                        species.var = "species",
                        abundance.var = "relative_cover",
                        treatment.var = "treatment")
# In each year there are 6 replicates for each of three treatments, for a
# total of 18 observations.

Phosphorus plots data from Avolio et al. 2014

Description

A dataset of tallgrass prairie plant composition in a nitrogen and phosphorus addition experiment at Konza Prairie, Manhattan Kansas (Avolio et al. 2014). This dataset is a subset of the full dataset.

Usage

data(pplots)

Format

A data frame with 1232 rows and 6 variables

Details

A data frame containing a column for replicate, year, species, abundance, block and treatment :

Source

Avolio, ML, Koerner, S, La Pierre, K, Wilcox, K, Wilson, GTW, Smith, MD, Collins, S. 2014. Changes in plant community composition, not diversity, to a decade of nitrogen and phosphorus additions drive changes in aboveground productivity in a tallgrass prairie. Journal of Ecology. 102: 1649-1660.

Mean Rank Shifts

Description

A measure of the relative change in species rank abundances, which indicates shifts in relative abundances over time (Collins et al. 2008). Mean rank shifts are calculated as the average difference in species' ranks between consecutive time periods, among species that are present across the entire time series.

Usage

rank_shift(
  df,
  time.var,
  species.var,
  abundance.var,
  replicate.var = as.character(NA)
)

Arguments

df

A data frame containing time, species and abundance columns and an optional column of replicates

time.var

The name of the time column

species.var

The name of the species column

abundance.var

The name of the abundance column

replicate.var

The name of the optional replicate column

Details

The input data frame needs to contain columns for time, species and abundance; time.var, species.var and abundance.var are used to indicate which columns contain those variables. If multiple replicates are included in the data frame, that column should be specified with replicate.var. Each replicate should reflect a single experimental unit - there must be a single abundance value per species within each time point and replicate.

Value

rank_shift returns a data frame with the following columns:

References

Collins, Scott L., Katharine N. Suding, Elsa E. Cleland, Michael Batty, Steven C. Pennings, Katherine L. Gross, James B. Grace, Laura Gough, Joe E. Fargione, and Christopher M. Clark. (2008) "Rank clocks and plant community dynamics." Ecology 89, no. 12: 3534-41.

Examples

 # Calculate mean rank shifts within replicates
 data(knz_001d)

 myoutput <- rank_shift(knz_001d,
                     time.var = "year",
                     species.var = "species",
                     abundance.var = "abundance",
                     replicate.var = "subplot")

 # Calculate mean rank shifts for a data frame with no replication

 myoutput_singlerep <- rank_shift(subset(knz_001d, subplot=="A_1"),
                           time.var = "year",
                           species.var = "species",
                           abundance.var = "abundance")

Rate of community change over successive time intervals

Description

Calculates the slope of the differences in species composition within a community over increasing time intervals, which provides a measures of the rate of directional change in community composition. Differences in species composition are characterized by Euclidean distances, which are calculated on pair-wise communities across the entire time series. For example, a data set with six time intervals will have distance values for five one-year time lags (year 1 vs year 2, year 2 vs year 3 ...), four two-year time lags (year 1 vs year 3, year 2 vs year 4 ...) and so forth. These distance values are regressed against the time lag interval. The slope of the regression line is reported as an indication of the rate and direction of compositional change in the community.

Usage

rate_change(df, time.var, species.var, abundance.var, replicate.var = NA)

Arguments

df

A data frame containing time, species and abundance columns and an optional column of replicates

time.var

The name of the time column

species.var

The name of the species column

abundance.var

The name of the abundance column

replicate.var

The name of the optional replicate column

Details

The input data frame needs to contain columns for time, species and abundance; time.var, species.var and abundance.var are used to indicate which columns contain those variables. If multiple replicates are included in the data frame, that column should be specified with replicate.var. Each replicate should reflect a single experimental unit - there must be a single abundance value per species within each time point and replicate.

The rate_change function uses linear regression to relate Euclidean distances to time lag intervals. It is recommended that fit of this relationship be verified using rate_change_interval, which returns the full set of community distance values and associated time lag intervals.

Value

The rate_change function returns a numeric rate change value unless a replication column is specified in the input data frame. If replication is specified, the function returns a data frame with the following attributes:

References

Collins, S. L., Micheli, F. and Hartt, L. 2000. A method to determine rates and patterns of variability in ecological communities. - Oikos 91: 285-293.

Examples

data(knz_001d)
rate_change(knz_001d[knz_001d$subplot=="A_1",],
                       time.var = "year", 
                       species.var = "species",
                       abundance.var = "abundance") # for one subplot
                       
rate_change(knz_001d, 
             time.var = "year", 
             species.var = "species",
             abundance.var = "abundance",
             replicate.var = "subplot") # across all subplots

Differences in community composition over successive time lag intervals

Description

Calculates the differences in species composition within a community over increasing time intervals. Differences in species composition are characterized by Euclidean distances, which are calculated on pair-wise communities across the entire time series. For example, a data set with 6 time intervals will have distance values for five one-year time lags (year 1 vs year 2, year 2 vs year 3 ...), 4 two-year time lags (year 1 vs year 3, year 2 vs year 4 ...) and so forth. Returns the full set of community distance values and associated time lag intervals.

Usage

rate_change_interval(
  df,
  time.var,
  species.var,
  abundance.var,
  replicate.var = NA
)

Arguments

df

A data frame containing time, species and abundance columns and an optional column of replicates

time.var

The name of the time column

species.var

The name of the species column

abundance.var

The name of the abundance column

replicate.var

The name of the optional replicate column

Value

The rate_change_interval function returns a data frame with the following attributes:

The input data frame needs to contain columns for time, species and abundance; time.var, species.var and abundance.var are used to indicate which columns contain those variables. If multiple replicates are included in the data frame, that column should be specified with replicate.var. Each replicate should reflect a single experimental unit - there must be a single abundance value per species within each time point and replicate.

References

Collins, S. L., Micheli, F. and Hartt, L. 2000. A method to determine rates and patterns of variability in ecological communities. - Oikos 91: 285-293.

Examples

data(knz_001d)
rate_change_interval(knz_001d[knz_001d$subplot=="A_1",], 
                     time.var = "year", 
                     species.var = "species",
                     abundance.var = "abundance") # for one subplot
                     
                     
rate_change_interval(knz_001d, 
                     time.var = "year", 
                     species.var = "species",
                     abundance.var = "abundance",
                      replicate.var = "subplot") # across all subplots

Species synchrony

Description

Calculates the degree synchrony in species abundances within a community over time. Includes the option for two different synchrony metrics. The first, developed by Loreau and de Mazancourt (2008), compares the variance of the aggregated community with the variance of individual components. The second, developed by Gross et al. (2014), compares the average correlation of each individual species with the rest of the aggregated community.

Usage

synchrony(
  df,
  time.var,
  species.var,
  abundance.var,
  metric = "Loreau",
  replicate.var = NA
)

Arguments

df

A data frame containing time, species and abundance columns and an optional column of replicates

time.var

The name of the time column

species.var

The name of the species column

abundance.var

The name of the abundance column

metric

The synchrony metric to return:

  • "Loreau": The default metric, calculates synchrony following Loreau and de Mazancourt (2008).

  • "Gross": Calculates synchrony following Gross et al. (2014).

replicate.var

The name of the optional replicate column

Details

The input data frame needs to contain columns for time, species and abundance; time.var, species.var and abundance.var are used to indicate which columns contain those variables. If multiple replicates are included in the data frame, that column should be specified with replicate.var. Each replicate should reflect a single experimental unit - there must be a single abundance value per species within each time point and replicate.

Value

The synchrony function returns a numeric synchrony value unless a replication column is specified in the input data frame. If replication is specified, the function returns a data frame with the following attributes:

References

Gross, Kevin, Bradley J. Cardinale, Jeremy W. Fox, Andrew Gonzalez, Michel Loreau, H. Wayne Polley, Peter B. Reich, and Jasper van Ruijven. (2014) "Species richness and the temporal stability of biomass production: A new analysis of recent biodiversity experiments." The American Naturalist 183, no. 1: 1-12. doi:10.1086/673915.

Loreau, Michel, and Claire de Mazancourt. (2008) "Species synchrony and its drivers: Neutral and nonneutral community dynamics in fluctuating environments." The American Naturalist 172, no. 2: E48-66. doi:10.1086/589746.

Examples

data(knz_001d)
synchrony(knz_001d[knz_001d$subplot=="A_1",],
                     time.var = "year", 
                     species.var = "species",
                     abundance.var = "abundance") # for one subplot
## Not run: 
synchrony(knz_001d, 
             time.var = "year", 
             species.var = "species",
             abundance.var = "abundance",
             replicate.var = "subplot") # across all subplots
             
synchrony(knz_001d,  
             time.var = "year", 
             species.var = "species",
             abundance.var = "abundance",
             replicate.var = "subplot", 
             metric="Gross") # With Gross et al. (2014) metric.

## End(Not run)

Species Turnover

Description

Computes species turnover between time periods as the proportion of species either gained or lost relative to the total number of species observed across both time periods. Includes an option to compute turnover as just the proportion of species gained (i.e., "appearances") or lost (i.e., "disappearances").

Usage

turnover(
  df,
  time.var,
  species.var,
  abundance.var,
  replicate.var = NA,
  metric = "total"
)

Arguments

df

A data frame containing time, species and abundance columns and an optional column of replicates

time.var

The name of the time column

species.var

The name of the species column

abundance.var

The name of the abundance column

replicate.var

The name of the optional replicate column

metric

The turnover metric to return:

  • total: The default metric, calculates summed appearances and disappearances relative to total species richness across both time periods.

  • appearance: Calculates the number of species that appeared in the second time period relative to total species richness across both time periods.

  • disappearance: Calculates the number of species that disappeared in the second time period relative to total species richness across both time periods.

Details

The input data frame needs to contain columns for time, species and abundance; time.var, species.var and abundance.var are used to indicate which columns contain those variables. If multiple replicates are included in the data frame, that column should be specified with replicate.var. Each replicate should reflect a single experimental unit - there must be a single abundance value per species within each time point and replicate.

Value

The turnover function returns a data frame with the following attributes:

References

Cleland, Elsa E., Scott L. Collins, Timothy L. Dickson, Emily C. Farrer, Katherine L. Gross, Laureano A. Gherardi, Lauren M. Hallett, et al. (2013) "Sensitivity of grassland plant community composition to spatial vs. temporal variation in precipitation." Ecology 94, no. 8: 1687-96.

Examples

 data(knz_001d)

 # Calculate relative total turnover within replicates
 total.res <- turnover(df=knz_001d,  
               time.var = "year", 
               species.var = "species",
               abundance.var = "abundance", 
               replicate.var="subplot")
 
 # Calculate relative species appearances within replicates
 appear.res <- turnover(df=knz_001d, 
               time.var = "year", 
               species.var = "species",
               abundance.var = "abundance",  
               replicate.var="subplot", 
               metric="appearance")
 
 # Calculate relative species disappearances within replicates
 disappear.res <- turnover(df=knz_001d, 
               time.var = "year", 
               species.var = "species",
               abundance.var = "abundance", 
               replicate.var="subplot", 
               metric="disappearance")

Variance Ratio

Description

Computes the ratio of the variance of aggregate species abundances in a community to the sum of the variances of individual, component species. A variance ratio = 1 indicates that species do not covary, a variance ratio > 1 indicates predominately positive covariance among species and a variance ratio < 1 indicates predominately negative covariance (Schluter 1984).

Includes a cyclic shift null modeling option to test if the variance ratio significantly differs from 1. The null community is created by randomly selecting different starting points for each species' time series, which generates a community in which species abundances vary independently but within-species autocorrelation is maintained (Hallett et al. 2014). This randomization is repeated a user-specific number of times and confidence intervals are reported for the resultant null distribution of variance ratios. If the dataframe includes multiple replicates, the variance ratios for the actual and null communities are averaged within each iteration unless specified otherwise.

Usage

variance_ratio(
  df,
  time.var,
  species.var,
  abundance.var,
  bootnumber,
  replicate.var = NA,
  average.replicates = TRUE,
  level = 0.95,
  li,
  ui
)

Arguments

df

A data frame containing time, species and abundance columns and an optional column of replicates

time.var

The name of the time column

species.var

The name of the species column

abundance.var

The name of the abundance column

bootnumber

The number of null model iterations used to calculated confidence intervals

replicate.var

The name of the (optional) replicate column

average.replicates

If true returns the variance ratio and CIs averaged

level

The confidence level for the null mean

li

(deprecated) lower confidence interval

ui

(deprecated) upper confidence interval across replicates; if false returns the variance ratio and CI for each replicate. Defaults to true.

Details

The input data frame needs to contain columns for time, species and abundance; time.var, species.var and abundance.var are used to indicate which columns contain those variables. If multiple replicates are included in the data frame, that column should be specified with replicate.var. Each replicate should reflect a single experimental unit - there must be a single abundance value per species within each time point and replicate.

Null model confidence intervals default to the standard lowest 2.5% and upper 97.5% of the null distribution, typically these do not need to be change, but they can be user-modified to set more stringent CIs. @references Hallett, Lauren M., Joanna S. Hsu, Elsa E. Cleland, Scott L. Collins, Timothy L. Dickson, Emily C. Farrer, Laureano A. Gherardi, et al. (2014) "Biotic Mechanisms of Community Stability Shift along a Precipitation Gradient." Ecology 95, no. 6: 1693-1700. doi: 10.1890/13-0895.1

Schluter, Dolph. (1984) "A Variance Test for Detecting Species Associations, with Some Example Applications." Ecology 65, no. 3: 998-1005. doi:10.2307/1938071.

Value

The variance_ratio function returns a data frame with the following attributes:

Examples

 data(knz_001d)

 # Calculate the variance ratio and CIs averaged within replicates
 # Here the null model is repeated once, for final use it is recommended to set a
 # large bootnumber (eg, 10000)

 res_averagedreplicates <- variance_ratio(knz_001d,
               time.var = "year",
               species.var = "species",
               abundance.var = "abundance",
               bootnumber = 1,
               replicate = "subplot")

 #Calculate the variance ratio and CIs for each replicate

 res_withinreplicates <- variance_ratio(knz_001d,
               time.var = "year",
               species.var = "species",
               abundance.var = "abundance",
               bootnumber = 1,
               replicate = "subplot",
               average.replicates = FALSE)