envPred is a package that calculates five statistics from
environmental time-series data: seasonality, the colour of environmental
noise (hereafter colour), constancy, contingency and predictability.
Seasonality entails the regularity in the timing and magnitude of fluctuations in the average environmental state over seasons. Colour is defined by how predictable and similar the environment is between successive time points, or how far into the future the environmental state is likely to stay the same, independent of the mean environmental state. White noise occurs when there is no correlation between one measurement and the next, while for reddened noise, there is some correlation between measurements separated by a finite time-scale.
Seasonality and colour are calculated following the steps described in Barneche et al. (2018). 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 first 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. By definition, white noise means that θ = 0, and reddened noise means that θ > 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.
Constancy, contingency and predictability are calculated following Colwell (1974). Constancy measures the extent to which the environment is the same for all months in all years. Contingency measures the extent to which the environmental differences between months are the same in all years. Predictability is the sum of constancy and contingency. Maximum predictability can be attained as a consequence of either complete constancy, complete contingency, or a combination of constancy and contingency.
The envPred package can be installed from GitHub using the
devtools package using
devtools::install_github.
If you do not yet have devtools, install with
install.packages("devtools").
Then install envPred using the following:
library(devtools)
install_github("dbarneche/envPred")
library(envPred)
envPred provides two test datasets for the user to understand the
behaviour and output of package functions: sst (Sea Surface
Temperature), and npp (ocean Net Primary Productivity). The former
contains evenly, complete distributed data at a daily interval; the
latter contains unevenly, incomplete (i.e. missing data) data. Both
sample datasets were obtained from a random coordinate using the
noaaErddap R package:
The package can be used for any time-series data, e.g. temperature, rainfall, light intensity, etc.
Dr. Diego Barneche (Australian Institute of Marine Science) and Dr. Scott Burgess (Florida State University Tallahassee)
Further information about envPred, including vignettes and help files,
can be seen on the on-line project
page.
This R package is provided for use under the MIT License (MIT) by the authors.
Please report any issues or bugs.