Learn R Programming

bsts (version 0.6.1)

bsts: Bayesian structural time series

Description

Uses MCMC to sample from the posterior distribution of a Bayesian structural time series model. This function can be used either with or without contemporaneous predictor variables (in a time series regression).

If predictor variables are present, the regression coefficients are fixed (as opposed to time varying, though time varying coefficients might be added as state component). The predictors and response in the formula are contemporaneous, so if you want lags and differences you need to put them in the predictor matrix yourself.

If no predictor variables are used, then the model is an ordinary state space time series model.

Usage

bsts(formula,
     state.specification,
     save.state.contributions = TRUE,
     save.prediction.errors = TRUE,
     data,
     bma.method = c("SSVS", "ODA"),
     prior,
     oda.options = list(
         fallback.probability = 0.0,
         eigenvalue.fudge.factor = 0.01),
     contrasts = NULL,
     na.action = na.pass,
     niter,
     ping = niter / 10,
     seed = NULL,
     ...)

Arguments

formula
A formula describing the regression portion of the relationship between y and X.

If no regressors are desired then the formula can be replaced by a numeric vector giving the time series to be modeled. Missing values are not allowed.

state.specification
A list with elements created by AddLocalLinearTrend, AddSeasonal, and similar functions for adding components of state. See the help
save.state.contributions
Logical. If TRUE then a 3-way array named state.contributions will be stored in the returned object. The indices correspond to MCMC iteration, state model number, and time. Setting save.state.contributions
save.prediction.errors
Logical. If TRUE then a matrix named one.step.prediction.errors will be saved as part of the model object. The rows of the matrix represent MCMC iterations, and the columns represent time. The matrix entries are th
data
An optional data frame, list or environment (or object coercible by as.data.frame to a data frame) containing the variables in the model. If not found in data, the variables
bma.method
If the model contains a regression component, this argument specifies the method to use for Bayesian model averaging. "SSVS" is stochastic search variable selection, which is the classic approach from George and McCulloch (1997). "ODA" is ort
oda.options
If bma.method == "ODA" then these are some options for fine tuning the ODA algorithm.
  • fallback.probability: Each MCMC iteration will use SSVS instead of ODA with this probability. In cases where the latent data ha
prior
If regressors are supplied in the model formula, then this is a prior distribution for the regression component of the model, as created by SpikeSlabPrior. The prior for the
contrasts
An optional list. See the contrasts.arg of model.matrix.default. This argument is only used if a model formula is specified. Even then the default is usually what you
na.action
What to do about missing values. The default is to allow missing responses, but no missing predictors. Set this to na.omit or na.exclude if you want to omit missing responses altogether.
niter
A positive integer giving the desired number of MCMC draws.
ping
A scalar giving the desired frequency of status messages. If ping > 0 then the program will print a status message to the screen every ping MCMC iterations.
seed
An integer to use as the random seed for the underlying C++ code. If NULL then the seed will be set using the clock.
...
Extra arguments to be passed to SpikeSlabPrior (see the entry for the prior argument, above).

Value

  • An object of class bsts which is a list with the following components
  • coefficientsA niter by ncol(X) matrix of MCMC draws of the regression coefficients, where X is the design matrix implied by formula. This is only present if a model formula was supplied.
  • sigma.obsA vector of length niter containing MCMC draws of the residual standard deviation.
  • The returned object will also contain named elements holding the MCMC draws of model parameters belonging to the state models. The names of each component are supplied by the entries in state.specification. If a model parameter is a scalar, then the list element is a vector with niter elements. If the parameter is a vector then the list element is a matrix with niter rows. If the parameter is a matrix then the list element is a 3-way array with first dimension niter.

    Finally, if a model formula was supplied, then the returned object will contain the information necessary for the predict method to build the design matrix when a new prediction is made.

References

Harvey (1990), "Forecasting, structural time series, and the Kalman filter", Cambridge University Press.

Durbin and Koopman (2001), "Time series analysis by state space methods", Oxford University Press.

Goerge and McCulloch (1997) "Approaches for Bayesian variable selection", Statistica Sinica pp 339--374.

Ghosh and Clyde (2011) "Rao-Blackwellization for Bayesian variable selection and model averaging in linear and binary regression: a novel data augmentation approach", JASA pp 1041 --1052.

See Also

bsts, AddLocalLevel, AddLocalLinearTrend, AddGeneralizedLocalLinearTrend, AddSeasonal AddDynamicRegression SpikeSlabPrior, SdPrior.

Examples

Run this code
## Example 1:  Time series (ts) data
  data(AirPassengers)
  y <- log(AirPassengers)
  ss <- AddLocalLinearTrend(list(), y)
  ss <- AddSeasonal(ss, y, nseasons = 12)
  model <- bsts(y, state.specification = ss, niter = 500)
  pred <- predict(model, horizon = 12, burn = 100)
  par(mfrow = c(1,2))
  plot(model)
  plot(pred)

MakePlots <- function(model, ask = TRUE) {
    ## Make all the plots callable by plot.bsts.
    opar <- par(ask = ask)
    on.exit(par(opar))
    plot.types <- c("state", "components", "residuals",
                    "prediction.errors", "forecast.distribution")
    for (plot.type in plot.types) {
      plot(model, plot.type)
    }
    if (model$has.regression) {
      regression.plot.types <- c("coefficients", "predictors", "size")
      for (plot.type in regression.plot.types) {
        plot(model, plot.type)
      }
    }
  }

  ## Example 2: GOOG is the Google stock price, an xts series of daily
  ##            data.
  data(goog)
  ss <- AddGeneralizedLocalLinearTrend(list(), goog)
  model <- bsts(goog, state.specification = ss, niter = 500)
  MakePlots(model)

  ## Example 3:  Change GOOG to be zoo, and not xts.
  goog <- zoo(goog, index(goog))
  ss <- AddGeneralizedLocalLinearTrend(list(), goog)
  model <- bsts(goog, state.specification = ss, niter = 500)
  MakePlots(model)

  ## Example 4:  Naked numeric data works too
  y <- rnorm(100)
  ss <- AddLocalLinearTrend(list(), y)
  model <- bsts(y, state.specification = ss, niter = 500)
  MakePlots(model)

  ## Example 5:  zoo data with intra-day measurements
  y <- zoo(rnorm(100),
           seq(from = as.POSIXct("2012-01-01 7:00 EST"), len = 100, by = 100))
  ss <- AddLocalLinearTrend(list(), y)
  model <- bsts(y, state.specification = ss, niter = 500)
  MakePlots(model)

Run the code above in your browser using DataLab