envPredictabilityAndColwell: Environmental time series statistics (deprecated)

Description Usage Arguments Details Value Author(s)

Description

Calculates seasonality, colour of environmental noise, constancy, contingency and predictability (deprecated). This function will be removed in future versions of the package. Use env_stats instead.

Usage

1
envPredictabilityAndColwell(rawTimeSeries, datesVector, nStates, ...)

Arguments

rawTimeSeries

A numeric vector containing a raw environmental time series.

datesVector

An vector of class Date of format YYYY-MM-DD (must be in progressive chronological order).

nStates

is a numeric vector of length 1 containing a somewhat arbitrary number, as Colwell's method divides a continuous variable up into discrete states. Default (arbitrary) is 11. See colwell_stats for Details.

...

Additional arguments to envPredictability.

Details

To calculate seasonality, we first remove linear trends by extracting the residuals from a linear regression model fitted to the raw time series. Seasonality is estimated in two forms: 1) as the "unbounded" fraction of the total variance that is due to predictable seasonal periodicities, α / β, where α is the variance of the seasonal trend, and β is the variance of the residual time series (i.e. the time series after the seasonal trend was removed); or 2) as the "bounded" fraction of the total variance that is due to predictable seasonal periodicities, α / (α + β). The seasonal trend is estimated by binning the time-series data into monthly intervals, averaging each month across the duration of the time series, then re-creating a seasonal time-series dataset on the same time-scale as the original data using a linear interpolation between the monthly midpoints.

To calculate colour, we calculate a residual time series by subtracting the corresponding seasonal value from each data point in the time series. The spectral density (i.e. variance in the residual time series) was assumed to scale with frequency, f, according to an inverse power law, 1/f^{θ} (Halley & Kunin, 1999; Vasseur & Yodzis, 2004). The spectral exponent θ is then estimated as the negative slope of the linear regression of the natural log of spectral density as a function of the natural log of frequency. White noise occurs when there is no correlation between one measurement and the next (i.e. θ = 0), while for reddened noise, there is some correlation between measurements separated by a finite time-scale (i.e. θ > 0). Spectral density is estimated using the spectrum function from the stats R package if the time series is evenly distributed, and the Lomb–Scargle function lsp from the lomb R package if the time series is unevenly distributed (Glynn et al. 2006). Spectral densities and therefore θ are calculated between the frequencies of 2 / (n Δ t) and 1 / (2 Δ t) (i.e. Nyquist frequency), where Δ t is the time gap between consecutive points in the time series, and n is the number of observations in the time series.

For predictability, constancy, and contingency, this algorithm implements the methods described in Colwell (1974) Ecology 55: 1148–1153, doi: 10.2307/1940366. These three metrics can be calculated from any phenomenon known or suspected to be periodic or cyclic in time which can be scored for at least two states. Scores from each month in the cycle are then collected for as many complete cycles as possible, and the data cast as a frequency matrix with months as columns, and states as rows. Constancy (C) measures the extent to which the environment is the same for all months in all years. Contingency (M) measures the extent to which the environmental differences between months are the same in all years. Predictability (P) is the sum of Constancy (C) and Contingency (M). Maximum predictability can be attained as a consequence of either complete constancy, complete contingency, or a combination of constancy and contingency.

General important notes:

Value

An data.frame of class envpreddata. See ?envpreddata for output details.

Author(s)

Diego Barneche and Scott Burgess.


dbarneche/envPred documentation built on June 28, 2020, 5:04 p.m.