bfastpp: Time Series Preprocessing for BFAST-Type Models

In bfast: Breaks for Additive Season and Trend

Description

Time series preprocessing for subsequent regression modeling. Based on a (seasonal) time series, a data frame with the response, seasonal terms, a trend term, (seasonal) autoregressive terms, and covariates is computed. This can subsequently be employed in regression models.

Usage

bfastpp(
  data,
  order = 3,
  lag = NULL,
  slag = NULL,
  na.action = na.omit,
  stl = c("none", "trend", "seasonal", "both"),
  decomp = c("stl", "stlplus"),
  sbins = 1
)

Arguments

data	A time series of class ts, or another object that can be coerced to such. For seasonal components, a frequency greater than 1 is required.
order	numeric. Order of the harmonic term, defaulting to 3.
lag	numeric. Orders of the autoregressive term, by default omitted.
slag	numeric. Orders of the seasonal autoregressive term, by default omitted.
na.action	function for handling NAs in the data (after all other preprocessing).
stl	character. Prior to all other preprocessing, STL (season-trend decomposition via LOESS smoothing) can be employed for trend-adjustment and/or season-adjustment. The "trend" or "seasonal" component or both from stl are removed from each column in data. By default ("none"), no STL adjustment is used.
decomp	"stlplus" or "stl": use the NA-tolerant decomposition package or the reference package (which can make use of time series with 2-3 observations per year)
sbins	numeric. Controls the number of seasonal dummies. If integer > 1, sets the number of seasonal dummies to use per year. If <= 1, treated as a multiplier to the number of observations per year, i.e. ndummies = nobs/year * sbins.

Details

To facilitate (linear) regression models of time series data, bfastpp facilitates preprocessing and setting up regressor terms. It returns a data.frame containing the first column of the data as the response while further columns (if any) are used as covariates xreg. Additionally, a linear trend, seasonal dummies, harmonic seasonal terms, and (seasonal) autoregressive terms are provided.

Optionally, each column of data can be seasonally adjusted and/or trend-adjusted via STL (season-trend decomposition via LOESS smoothing) prior to preprocessing. The idea would be to capture season and/or trend nonparametrically prior to regression modelling.

Value

If no formula is provided, bfastpp returns a "data.frame" with the following variables (some of which may be matrices).

time	numeric vector of time stamps,
response	response vector (first column of data),
trend	linear time trend (running from 1 to number of observations),
season	factor indicating season period,
harmon	harmonic seasonal terms (of specified order),
lag	autoregressive terms (or orders lag, if any),
slag	seasonal autoregressive terms (or orders slag, if any),
xreg	covariate regressor (all columns of data except the first, if any).

If a formula is given, bfastpp returns a list with components X, y, and t, where X is the design matrix of the model, y is the response vector, and t represents the time of observations. X will only contain variables that occur in the formula. Columns of X have names as decribed above.

Author(s)

Achim Zeileis

References

\insertRef

janbfastmonitorbfast

See Also

bfastmonitor

Examples

## set up time series
ndvi <- as.ts(zoo::zoo(cbind(a = som$NDVI.a, b = som$NDVI.b), som$Time))
ndvi <- window(ndvi, start = c(2006, 1), end = c(2009, 23))

## parametric season-trend model
d1 <- bfastpp(ndvi, order = 2)
d1lm <- lm(response ~ trend + harmon, data = d1)
summary(d1lm)
# plot visually (except season, as it's a factor)
plot(zoo::read.zoo(d1)[,-3],
  # Avoid clipping plots for pretty output
  ylim = list(c(min(d1[,2]), max(d1[,2])),
            c(min(d1[,3]), max(d1[,3])),
            c(-1, 1), c(-1, 1), c(-1, 1), c(-1, 1),
            c(min(d1[,6]), max(d1[,6]))
       ))

## autoregressive model (after nonparametric season-trend adjustment)
d2 <- bfastpp(ndvi, stl = "both", lag = 1:2)
d2lm <- lm(response ~ lag, data = d2)
summary(d2lm)

## use the lower level lm.fit function
d3 <- bfastpp(ndvi, stl = "both", lag = 1:2)
d3mm <- model.matrix(response ~ lag, d3)
d3lm <- lm.fit(d3mm, d3$response)
d3lm$coefficients

Example output

Registered S3 method overwritten by 'quantmod':
  method            from
  as.zoo.data.frame zoo 

Call:
lm(formula = response ~ trend + harmon, data = d1)

Residuals:
      Min        1Q    Median        3Q       Max 
-0.228691 -0.041100 -0.004046  0.055139  0.169111 

Coefficients:
              Estimate Std. Error t value Pr(>|t|)    
(Intercept)  4.145e-01  1.610e-02  25.748  < 2e-16 ***
trend       -7.742e-05  3.024e-04  -0.256 0.798563    
harmoncos1   7.279e-03  1.109e-02   0.657 0.513237    
harmoncos2   3.868e-02  1.109e-02   3.488 0.000768 ***
harmonsin1  -3.747e-02  1.130e-02  -3.316 0.001337 ** 
harmonsin2  -1.041e-01  1.114e-02  -9.351 9.51e-15 ***
---
Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1

Residual standard error: 0.07517 on 86 degrees of freedom
Multiple R-squared:  0.5648,	Adjusted R-squared:  0.5395 
F-statistic: 22.32 on 5 and 86 DF,  p-value: 2.8e-14


Call:
lm(formula = response ~ lag, data = d2)

Residuals:
      Min        1Q    Median        3Q       Max 
-0.153435 -0.030022 -0.001384  0.021004  0.214001 

Coefficients:
             Estimate Std. Error t value Pr(>|t|)  
(Intercept) 0.0003608  0.0060051   0.060   0.9522  
lag1        0.2697747  0.1045785   2.580   0.0116 *
lag2        0.2204984  0.1045727   2.109   0.0379 *
---
Signif. codes:  0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1

Residual standard error: 0.05696 on 87 degrees of freedom
Multiple R-squared:  0.1626,	Adjusted R-squared:  0.1433 
F-statistic: 8.446 on 2 and 87 DF,  p-value: 0.0004445

 (Intercept)         lag1         lag2 
0.0003608327 0.2697746828 0.2204983802 

bfast documentation built on May 10, 2021, 5:08 p.m.