bfast01 {bfast}

Checking for one major break in the time series

Description

A function to select a suitable model for the data by choosing either a model with 0 or with 1 breakpoint.

Usage

bfast01(
  data,
  formula = NULL,
  test = "OLS-MOSUM",
  level = 0.05,
  aggregate = all,
  trim = NULL,
  bandwidth = 0.15,
  functional = "max",
  order = 3,
  lag = NULL,
  slag = NULL,
  na.action = na.omit,
  reg = c("lm", "rlm"),
  stl = "none",
  sbins = 1
)

Arguments

data

A time series of class ts, or another object that can be coerced to such. The time series is processed by bfastpp. A time series of class ts can be prepared by a convenience function bfastts in case of daily, 10 or 16-daily time series.

formula

formula for the regression model. The default is intelligently guessed based on the arguments order/lag/slag i.e. response ~ trend + harmon, i.e., a linear trend and a harmonic season component. Other specifications are possible using all terms set up by bfastpp, i.e., season (seasonal pattern with dummy variables), lag (autoregressive terms), slag (seasonal autoregressiv terms), or xreg (further covariates). See bfastpp for details.

test

character specifying the type of test(s) performed. Can be one or more of BIC, supLM, supF, OLS-MOSUM, ..., or any other test supported by sctest.formula

level

numeric. Significance for the sctest.formula performed.

aggregate

function that aggregates a logical vector to a single value. This is used for aggregating the individual test decisions from test to a single one.

trim

numeric. The mimimal segment size passed to the from argument of the Fstats function.

bandwidth

numeric scalar from interval (0,1), functional. The bandwidth argument is passed to the h argument of the sctest.formula.

functional

arguments passed on to sctest.formula

order

numeric. Order of the harmonic term, defaulting to 3.

lag

numeric. Order of the autoregressive term, by default omitted.

slag

numeric. Order of the seasonal autoregressive term, by default omitted.

na.action

arguments passed on to bfastpp

reg

whether to use OLS regression lm() or robust regression MASS::rlm().

stl

argument passed on to bfastpp

sbins

argument passed on to bfastpp

Details

bfast01 tries to select a suitable model for the data by choosing either a model with 0 or with 1 breakpoint. It proceeds in the following steps:

1. The data is preprocessed with bfastpp using the arguments order/lag/slag/na.action/stl/sbins.

2. A linear model with the given formula is fitted. By default a suitable formula is guessed based on the preprocessing parameters.

3. The model with 1 breakpoint is estimated as well where the breakpoint is chosen to minimize the segmented residual sum of squares.

4. A sequence of tests for the null hypothesis of zero breaks is performed. Each test results in a decision for FALSE (no breaks) or TRUE (structural break(s)). The test decisions are then aggregated to a single decision (by default using all() but any() or some other function could also be used).

Available methods for the object returned include standard methods for linear models (coef, fitted, residuals, predict, AIC, BIC, logLik, deviance, nobs, model.matrix, model.frame), standard methods for breakpoints (breakpoints, breakdates), coercion to a zoo series with the decomposed components (as.zoo), and a plot method which plots such a zoo series along with the confidence interval (if the 1-break model is visualized). All methods take a 'breaks' argument which can either be 0 or 1. By default the value chosen based on the 'test' decisions is used.

Note that the different tests supported have power for different types of alternatives. Some tests (such as supLM/supF or BIC) assess changes in all coefficients of the model while residual-based tests (e.g., OLS-CUSUM or OLS-MOSUM) assess changes in the conditional mean. See Zeileis (2005) for a unifying view.

Value

bfast01 returns a list of class "bfast01" with the following elements:

call

the original function call.

data

the data preprocessed by "bfastpp".

formula

the model formulae.

breaks

the number of breaks chosen based on the test decision (either 0 or 1).

test

the individual test decisions.

breakpoints

the optimal breakpoint for the model with 1 break.

model

A list of two 'lm' objects with no and one breaks, respectively.

Author(s)

Achim Zeileis, Jan Verbesselt

References

De Jong R, Verbesselt J, Zeileis A, Schaepman ME (2013). “Shifts in Global Vegetation Activity Trends.” Remote Sensing, 5(3), 1117–1133. ISSN 2072-4292, doi: 10.3390/rs5031117, https://doi.org/10.3390/rs5031117.

Zeileis A (2005). “A Unified Approach to Structural Change Tests Based on ML Scores, F Statistics, and OLS Residuals.” Econometric Reviews, 24(4), 445–466. ISSN 0747-4938, doi: 10.1080/07474930500406053, https://doi.org/10.1080/07474930500406053.

See Also

bfastmonitor, breakpoints

Examples

library(zoo)
## define a regular time series
ndvi <- as.ts(zoo(som$NDVI.a, som$Time))

## fit variations
bf1 <- bfast01(ndvi)
bf2 <- bfast01(ndvi, test = c("BIC", "OLS-MOSUM", "supLM"), aggregate = any)
bf3 <- bfast01(ndvi, test = c("OLS-MOSUM", "supLM"), aggregate = any, bandwidth = 0.11) 

## inspect test decisions
bf1$test
bf1$breaks
bf2$test
bf2$breaks
bf3$test
bf3$breaks

## look at coefficients
coef(bf1)
coef(bf1, breaks = 0)
coef(bf1, breaks = 1) 

## zoo series with all components
plot(as.zoo(ndvi))
plot(as.zoo(bf1, breaks = 1))
plot(as.zoo(bf2))
plot(as.zoo(bf3))

## leveraged by plot method
plot(bf1, regular = TRUE)
plot(bf2)
plot(bf2, plot.type = "multiple",
     which = c("response", "trend", "season"), screens = c(1, 1, 2))
plot(bf3)