Package Earlywarnings': R Topics Documented
Package Earlywarnings': R Topics Documented
Title Early Warning Signals Toolbox for Detecting Critical Transitions in Timeseries
Version 1.0.32
Date 2013-02-18
LazyLoad yes
URL
http://www.early-warning-signals.org, http://www.vasilisdakos.net
R topics documented:
bdstest_ews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
ch_ews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
circulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
ddjnonparam_ews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
foldbif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
generic_ews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
livpotential_ews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
movpotential_ews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
1
2 bdstest_ews
sensitivity_ews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
surrogates_ews . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
YD2PB_grayscale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Description
bdstest_ews is used to estimate the BDS statistic to detect nonlinearity in the residuals of a
timeseries after first-difference detrending, fitting an ARMA(p,q) model, and fitting a GARCH(0,1)
model. The function is making use of bds.test from the tseries package.
Usage
bdstest_ews(timeseries, ARMAoptim = TRUE,
ARMAorder = c(1, 0), GARCHorder = c(0, 1), embdim = 3,
epsilon = c(0.5, 0.75, 1), boots = 1000,
logtransform = FALSE, interpolate = FALSE)
Arguments
timeseries a numeric vector of the observed univariate timeseries values or a numeric ma-
trix where the first column represents the time index and the second the observed
timeseries values. Use vectors/matrices with headings.
ARMAoptim is the order of the ARMA(p,q) model to be fitted on the original timeseries. If
TRUE the best ARMA model based on AIC is applied. If FALSE the ARMAorder
is used.
ARMAorder is the order of the AR(p) and MA(q) process to be fitted on the original time-
series. Default is p=1 q=0.
GARCHorder fits a GARCH model on the original timeseries where GARCHorder[1] is the
GARCH part and GARCHorder[2] is the ARCH part.
embdim is the embedding dimension (2, 3,... embdim) up to which the BDS test will be
estimated (must be numeric). Default value is 3.
epsilon is a numeric vector that is used to scale the standard deviation of the timeseries.
The BDS test is computed for each element of epsilon. Default is 0.5, 0.75 and
1.
boots is the number of bootstraps performed to estimate significance p values for the
BDS test. Default is 1000.
logtransform logical. If TRUE data are logtransformed prior to analysis as log(X+1). Default
is FALSE.
interpolate logical. If TRUE linear interpolation is applied to produce a timeseries of equal
length as the original. Default is FALSE (assumes there are no gaps in the
timeseries).
Details
See also bds.test{tseries} for more details. The function requires the installation of pack-
ages tseries and quadprog that are not available under Linux and need to be manually installed
under Windows.
ch_ews 3
Value
bdstest_ews returns output on the R console that summarizes the BDS test statistic for all em-
bedding dimensions and epsilon values used, and for first-differenced data, ARMA(p.q) resid-
uals, and GARCH(0,1) residuals). Also the significance p values are returned estimated both by
comparing to a standard normal distribution and by bootstrapping.
In addition, bdstest_ews returns a plot with the original timeseries, the residuals after first-
differencing, and fitting the ARMA(p,q) and GARCH(0,1) models. Also the autocorrelation acf
and partial autocorrelation pacf functions are estimated serving as guides for the choice of lags of
the linear models fitted to the data.
Author(s)
References
J. B. Cromwell, W. C. Labys and M. Terraza (1994): Univariate Tests for Time Series Models, Sage,
Thousand Oaks, CA, pages 32-36.
Dakos, V., et al (2012)."Methods for Detecting Early Warnings of Critical Transitions in Time Series
Illustrated Using Simulated Ecological Data." PLoS ONE 7(7): e41010. doi:10.1371/journal.pone.0041010
See Also
Examples
#
data(foldbif)
bdstest_ews(foldbif,ARMAoptim=FALSE,ARMAorder=c(1,0),embdim=3,epsilon=0.5, boots=200,logt
Description
ch_ews is used to estimate changes in conditional heteroskedasticity within rolling windows along
a timeseries
Usage
Arguments
timeseries a numeric vector of the observed timeseries values or a numeric matrix where
the first column represents the time index and the second the observed timeseries
values. Use vectors/matrices with headings.
winsize is length of the rolling window expressed as percentage of the timeseries length
(must be numeric between 0 and 100). Default is 10%.
alpha is the significance threshold (must be numeric). Default is 0.1.
optim logical. If TRUE an autoregressive model is fit to the data within the rolling
window using AIC optimization. Otherwise an autoregressive model of specific
order lags is selected.
lags is a parameter that determines the specific order of an autoregressive model to
fit the data. Default is 4.
logtransform logical. If TRUE data are logtransformed prior to analysis as log(X+1). Default
is FALSE.
interpolate logical. If TRUE linear interpolation is applied to produce a timeseries of equal
length as the original. Default is FALSE (assumes there are no gaps in the
timeseries).
Details
see ref below
Value
ch_ews returns a matrix that contains:
In addition, ch_ews plots the original timeseries and the R2 where the level of significance is also
indicated.
Author(s)
T. Cline, modified by V. Dakos
References
Seekell, D. A., et al (2011). "Conditional heteroscedasticity as a leading indicator of ecological
regime shifts." American Naturalist 178(4): 442-451
Dakos, V., et al (2012)."Methods for Detecting Early Warnings of Critical Transitions in Time Series
Illustrated Using Simulated Ecological Data." PLoS ONE 7(7): e41010. doi:10.1371/journal.pone.0041010
circulation 5
See Also
generic_ews; ddjnonparam_ews; bdstest_ews; sensitivity_ews; surrogates_ews;
ch_ews; movpotential_ews; livpotential_ews
Examples
data(foldbif)
out=ch_ews(foldbif, winsize=50, alpha=0.05, optim=TRUE, lags)
Description
circulation data set
Format
TBA
Source
TBA
References
See citation("earlywarnings")
Examples
#
Description
ddjnonparam_ews is used to compute nonparametrically conditional variance, drift, diffusion
and jump intensity in a timeseries. It also interpolates to obtain the evolution of the nonparametric
statistics in time.
Usage
ddjnonparam_ews(timeseries, bandwidth = 0.6, na = 500,
logtransform = TRUE, interpolate = FALSE)
6 ddjnonparam_ews
Arguments
timeseries a numeric vector of the observed univariate timeseries values or a numeric ma-
trix where the first column represents the time index and the second the observed
timeseries values. Use vectors/matrices with headings.
bandwidth is the bandwidht of the kernel regressor (must be numeric). Default is 0.6.
na is the number of points for computing the kernel (must be numeric). Default is
500.
logtransform logical. If TRUE data are logtransformed prior to analysis as log(X+1). Default
is FALSE.
interpolate logical. If TRUE linear interpolation is applied to produce a timeseries of equal
length as the original. Default is FALSE (assumes there are no gaps in the
timeseries).
Details
The approach is based on estimating terms of a drift-diffusion-jump model as a surrogate for the
unknown true data generating process: [1] dx = f (x, θ)dt + g(x, θ)dW + dJ Here x is the state
variable, f() and g() are nonlinear functions, dW is a Wiener process and dJ is a jump process.
Jumps are large, one-step, positive or negative shocks that are uncorrelated in time.
Value
avec is the mesh for which values of the nonparametric statistics are estimated.
S2.vec is the conditional variance of the timeseries x over avec.
TotVar.dx.vec
is the total variance of dx over avec.
Diff2.vec is the diffusion estimated as total variance - jumping intensity
vs avec.
LamdaZ.vec is the jump intensity over avec.
Tvec1 is the timeindex.
S2.t is the conditional variance of the timeseries x data over Tvec1.
TotVar.t is the total variance of dx over Tvec1.
Diff2.t is the diffusion over Tvec1.
Lamda.t is the jump intensity over Tvec1.
In addition, ddjnonparam_ews returns a first plot with the original timeseries and the residuals
after first-differencing. A second plot shows the nonparametric conditional variance, total variance,
diffusion and jump intensity over the data, and a third plot the same nonparametric statistics over
time.
Author(s)
References
Carpenter, S. R. and W. A. Brock (2011). "Early warnings of unknown nonlinear shifts: a nonpara-
metric approach." Ecology 92(12): 2196-2201
Dakos, V., et al (2012)."Methods for Detecting Early Warnings of Critical Transitions in Time Series
Illustrated Using Simulated Ecological Data." PLoS ONE 7(7): e41010. doi:10.1371/journal.pone.0041010
See Also
Examples
data(foldbif)
output<-ddjnonparam_ews(foldbif,bandwidth=0.6,na=500,
logtransform=TRUE,interpolate=FALSE)
Description
Format
TBA
Source
TBA
References
See citation("earlywarnings")
Examples
#
8 generic_ews
Description
generic_ews is used to estimate statistical moments within rolling windows along a timeserie
Usage
Arguments
timeseries a numeric vector of the observed univariate timeseries values or a numeric ma-
trix where the first column represents the time index and the second the observed
timeseries values. Use vectors/matrices with headings. If the powerspectrum is
to be plotted as well, the timeseries lenght should be even number.
winsize is the size of the rolling window expressed as percentage of the timeseries length
(must be numeric between 0 and 100). Default is 50%.
bandwidth is the bandwidth used for the Gaussian kernel when gaussian filtering is applied.
It is expressed as percentage of the timeseries length (must be numeric between
0 and 100). Alternatively it can be given by the bandwidth selector bw.nrd0
(Default).
detrending the timeseries can be detrended/filtered prior to analysis. There are four options:
gaussian filtering, linear detrending and first-differencing. De-
fault is no detrending.
logtransform logical. If TRUE data are logtransformed prior to analysis as log(X+1). Default
is FALSE.
interpolate logical. If TRUE linear interpolation is applied to produce a timeseries of equal
length as the original. Default is FALSE (assumes there are no gaps in the
timeseries).
AR_n logical. If TRUE the best fitted AR(n) model is fitted to the data. Default is
FALSE.
powerspectrum
logical. If TRUE the power spectrum within each rolling window is plotted.
Default is FALSE.
Details
Value
generic_ews returns a matrix that contains:
In addition, generic_ews returns three plots. The first plot contains the original data, the de-
trending/filtering applied and the residuals (if selected), and all the moment statistics. For each
statistic trends are estimated by the nonparametric Kendall tau correlation. The second plot, if
asked, quantifies resilience indicators fitting AR(n) selected by the Akaike Information Criterion.
The third plot, if asked, is the power spectrum estimated by spec.ar for all frequencies within
each rolling window.
Author(s)
Vasilis Dakos <[email protected]>
References
Ives, A. R. (1995). "Measuring resilience in stochastic systems." Ecological Monographs 65: 217-
233
Dakos, V., et al (2008). "Slowing down as an early warning signal for abrupt climate change."
Proceedings of the National Academy of Sciences 105(38): 14308-14312
Dakos, V., et al (2012)."Methods for Detecting Early Warnings of Critical Transitions in Time Series
Illustrated Using Simulated Ecological Data." PLoS ONE 7(7): e41010. doi:10.1371/journal.pone.0041010
See Also
generic_ews; ddjnonparam_ews; bdstest_ews; sensitivity_ews; surrogates_ews;
ch_ews; movpotential_ews; livpotential_ews;
Examples
data(foldbif)
out=generic_ews(foldbif,winsize=50,detrending="gaussian",
bandwidth=5,logtransform=FALSE,interpolate=FALSE)
10 livpotential_ews
Description
livpotential_ews performs one-dimensional potential estimation derived from a uni-variate
timeseries
Usage
livpotential_ews(x, std = 1, bw = -1, xi = NULL,
weights = c(), grid.size = 200)
Arguments
x data vector
std the standard deviation of the noise (defaults to 1, so then you use scaled poten-
tials
bw bandwidth for kernel estimation
xi x values at which the potential is estimated
weights optional weights in ksdensity (used by movpotentials).
grid.size grid size
Details
see ref below
Value
livpotential returns a list with the following elements:
Author(s)
Based on Matlab code from Egbert van Nes modified by Leo Lahti. Implemented in early warnings
package by V. Dakos.
References
Livina, VN, F Kwasniok, and TM Lenton, 2010. Potential analysis reveals changing number of
climate states during the last 60 kyr . Climate of the Past, 6, 77-82.
Dakos, V., et al (2012)."Methods for Detecting Early Warnings of Critical Transitions in Time Series
Illustrated Using Simulated Ecological Data." PLoS ONE 7(7): e41010. doi:10.1371/journal.pone.0041010
movpotential_ews 11
See Also
generic_ews; ddjnonparam_ews; bdstest_ews; sensitivity_ews;surrogates_ews;
ch_ews;movpotential_ews
Examples
data(foldbif)
res <- livpotential_ews(foldbif)
plot(res$xi, res$pot)
Description
movpotential_ews reconstructs a potential derived from data along a gradient of a given pa-
rameter the movpotential_ews calculates the potential for values that correspond to a particular
parameter. see ref below
Usage
movpotential_ews(X, param, sdwindow = NULL, bw = -1,
minparam = NULL, maxparam = NULL, npoints = 50,
thres = 0.002, std = 1, grid.size = 200, cutoff = 0.5)
Arguments
X a vector of the X observations of the state variable of interest
param parameter values that correspond to the X observations
sdwindow window for smoothing kernels (over the param axis)
bw bandwidth used for smoothing kernels
minparam minimum value of parameter on which to estimate potential
maxparam maximum value of parameter on which to estimate potential
npoints number of potentials
thres threshold for local minima to be discarded
std std
grid.size number of evaluation points
cutoff the cuttof value to estimate minima and maxima in the potential
Returns:
Value
A list with the following elements:
pars values of the covariate parameter as matrix
xis values of the x as matrix
pots smoothed potentials
mins minima in the densities (-potentials; neglecting local optima)
maxs maxima in densities (-potentials; neglecting local optima)
plot an object that displays the potential estimated in 2D
12 sensitivity_ews
Author(s)
Based on Matlab code from Egbert van Nes modified by Leo Lahti. Implemented in early warnings
package by V. Dakos.
References
Hirota, M., Holmgren, M., van Nes, E.H. & Scheffer, M. (2011). Global resilience of tropical forest
and savanna to critical transitions. Science, 334, 232-235.
See Also
generic_ews; ddjnonparam_ews; bdstest_ews; sensitivity_ews;surrogates_ews;
ch_ews; livpotential_ews
Examples
X = c(rnorm(1000, mean = 0), rnorm(1000, mean = -2), rnorm(1000, mean = 2))
param = seq(0,5,length=3000)
res <- movpotential_ews(X, param, npoints = 100, thres = 0.003)
Description
sensitivity_ews is used to estimate trends in statistical moments for different sizes of rolling
windows along a timeseries. The trends are estimated by the nonparametric Kendall tau correlation
coefficient.
Usage
sensitivity_ews(timeseries,
indicator = c("ar1", "sd", "acf1", "sk", "kurt", "cv", "returnrate", "densra
winsizerange = c(25, 75), incrwinsize = 25,
detrending = c("no", "gaussian", "linear", "first-diff"),
bandwidthrange = c(5, 100), incrbandwidth = 20,
logtransform = FALSE, interpolate = FALSE)
Arguments
timeseries a numeric vector of the observed univariate timeseries values or a numeric ma-
trix where the first column represents the time index and the second the observed
timeseries values. Use vectors/matrices with headings.
indicator is the statistic (leading indicator) selected for which the sensitivity analysis
is perfomed. Currently, the indicators supported are: ar1 autoregressive co-
efficient of a first order AR model, sd standard deviation, acf1 autocorre-
lation at first lag, sk skewness, kurt kurtosis, cv coeffcient of variation,
returnrate, and densratio density ratio of the power spectrum at low
frequencies over high frequencies.
winsizerange is the range of the rolling window sizes expressed as percentage of the timeseries
length (must be numeric between 0 and 100). Default is 25% - 75%.
sensitivity_ews 13
incrwinsize increments the rolling window size (must be numeric between 0 and 100). De-
fault is 25.
detrending the timeseries can be detrended/filtered. There are three options: gaussian
filtering, linear detrending and first-differencing. Default is no
detrending.
bandwidthrange
is the range of the bandwidth used for the Gaussian kernel when gaussian filter-
ing is selected. It is expressed as percentage of the timeseries length (must be
numeric between 0 and 100). Default is 5% - 100%.
incrbandwidth
is the size to increment the bandwidth used for the Gaussian kernel when gaus-
sian filtering is applied. It is expressed as percentage of the timeseries length
(must be numeric between 0 and 100). Default is 20.
logtransform logical. If TRUE data are logtransformed prior to analysis as log(X+1). Default
is FALSE.
interpolate logical. If TRUE linear interpolation is applied to produce a timeseries of equal
length as the original. Default is FALSE (assumes there are no gaps in the
timeseries).
Details
see ref below
Value
sensitivity_ews returns a matrix that contains the Kendall tau rank correlation estimates for
the rolling window sizes (rows) and bandwidths (columns), if gaussian filtering is se-
lected.
In addition, sensitivity_ews returns a plot with the Kendall tau estimates and their p-values
for the range of rolling window sizes used, together with a histogram of the distributions of the
statistic and its significance. When gaussian filtering is chosen, a contour plot is produced
for the Kendall tau estimates and their p-values for the range of both rolling window sizes and
bandwidth used. A reverse triangle indicates the combination of the two parameters for which the
Kendall tau was the highest
Author(s)
Vasilis Dakos <[email protected]>
References
Dakos, V., et al (2008). "Slowing down as an early warning signal for abrupt climate change."
Proceedings of the National Academy of Sciences 105(38): 14308-14312
Dakos, V., et al (2012)."Methods for Detecting Early Warnings of Critical Transitions in Time Series
Illustrated Using Simulated Ecological Data." PLoS ONE 7(7): e41010. doi:10.1371/journal.pone.0041010
See Also
generic_ews; ddjnonparam_ews; bdstest_ews; sensitivity_ews; surrogates_ews;
ch_ews; movpotential_ews; livpotential_ews
14 surrogates_ews
Examples
data(foldbif)
output=sensitivity_ews(foldbif,indicator="sd",detrending="gaussian",
incrwinsize=25,incrbandwidth=20)
Description
surrogates_ews is used to estimate distributions of trends in statistical moments from different
surrogate timeseries generated after fitting an ARMA(p,q) model on the data. The trends are esti-
mated by the nonparametric Kendall tau correlation coefficient and can be compared to the trends
estimated in the original timeseries to produce probabilities of false positives.
Usage
surrogates_ews(timeseries,
indicator = c("ar1", "sd", "acf1", "sk", "kurt", "cv", "returnrate", "densra
winsize = 50,
detrending = c("no", "gaussian", "linear", "first-diff"),
bandwidth = NULL, boots = 100, logtransform = FALSE,
interpolate = FALSE)
Arguments
timeseries a numeric vector of the observed univariate timeseries values or a numeric ma-
trix where the first column represents the time index and the second the observed
timeseries values. Use vectors/matrices with headings.
indicator is the statistic (leading indicator) selected for which the surrogate timeseries
are produced. Currently, the indicators supported are: ar1 autoregressive co-
efficient of a first order AR model, sd standard deviation, acf1 autocorre-
lation at first lag, sk skewness, kurt kurtosis, cv coeffcient of variation,
returnrate, and densratio density ratio of the power spectrum at low
frequencies over high frequencies.
winsize is the size of the rolling window expressed as percentage of the timeseries length
(must be numeric between 0 and 100). Default valuise 50%.
detrending the timeseries can be detrended/filtered prior to analysis. There are three op-
tions: gaussian filtering, linear detrending and first-differencing.
Default is no detrending.
bandwidth is the bandwidth used for the Gaussian kernel when gaussian filtering is selected.
It is expressed as percentage of the timeseries length (must be numeric between
0 and 100). Alternatively it can be given by the bandwidth selector bw.nrd0
(Default).
boots the number of surrogate data. Default is 100.
logtransform logical. If TRUE data are logtransformed prior to analysis as log(X+1). Default
is FALSE.
interpolate logical. If TRUE linear interpolation is applied to produce a timeseries of equal
length as the original. Default is FALSE (assumes there are no gaps in the
timeseries).
surrogates_ews 15
Details
Value
In addition, surrogates_ews returns a plot with the distribution of the surrogate Kendall tau
estimates and the Kendall tau estimate of the original series. Vertical lines indicate the 5% and 95%
significance levels.
Author(s)
References
Dakos, V., et al (2008). "Slowing down as an early warning signal for abrupt climate change."
Proceedings of the National Academy of Sciences 105(38): 14308-14312
Dakos, V., et al (2012)."Methods for Detecting Early Warnings of Critical Transitions in Time Series
Illustrated Using Simulated Ecological Data." PLoS ONE 7(7): e41010. doi:10.1371/journal.pone.0041010
See Also
Examples
data(foldbif)
output=surrogates_ews(foldbif,indicator="sd",winsize=50,detrending="gaussian",
bandwidth=10,boots=200,logtransform=FALSE,interpolate=FALSE)
16 YD2PB_grayscale
Description
YD2PB_grayscale data set
Format
TBA
Source
TBA
References
See citation("earlywarnings")
Examples
#