bfast01: Checking for one major break in the time series

In bfast: Breaks for Additive Season and Trend

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

\insertRef

rogierbfast01bfast

\insertRef

achimstrucchangebfast

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)

bfast documentation built on Oct. 22, 2024, 5:07 p.m.