README.md

In dbarneche/envPred: Calculate Environmental Predictability for Even and Uneven Time Series Data

envPred

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.

Installation

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)

Available data sources in 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:

• Net Primary Productivity (NPP) data
• Sea Surface Temperature (SST)

The package can be used for any time-series data, e.g. temperature, rainfall, light intensity, etc.

Authors

Dr. Diego Barneche (Australian Institute of Marine Science) and Dr. Scott Burgess (Florida State University Tallahassee)

Further Information

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.

Bug reporting

Please report any issues or bugs.

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