bsts (version 0.7.0)

plot.bsts: Plotting functions for Bayesian structural time series

Description

Functions to plot the results of a model fit using bsts.

Usage

# S3 method for bsts
plot(x, y = c("state", "components", "residuals",
              "coefficients", "prediction.errors",
              "forecast.distribution",
              "predictors", "size", "dynamic", "seasonal", "help"),
      ...)
  PlotBstsCoefficients(bsts.object, burn = SuggestBurn(.1, bsts.object),
                       inclusion.threshold = 0, number.of.variables = NULL, ...)
  PlotBstsComponents(bsts.object, burn = SuggestBurn(.1, bsts.object),
                       time, same.scale = TRUE,
                       layout = c("square", "horizontal", "vertical"),
                       style = c("dynamic", "boxplot"),
                       ylim = NULL, ...)
  PlotDynamicRegression(bsts.object, burn = SuggestBurn(.1, bsts.object),
                        time = NULL, style = c("dynamic", "boxplot"),
                        layout = c("square", "horizontal", "vertical"),
                        ...)
  PlotBstsState(bsts.object, burn = SuggestBurn(.1, bsts.object),
                       time, show.actuals = TRUE,
                       style = c("dynamic", "boxplot"),
                       scale = c("linear", "mean"),
                       ylim = NULL,
                       ...)
  PlotBstsResiduals(bsts.object, burn = SuggestBurn(.1, bsts.object),
                       time, style = c("dynamic", "boxplot"), ...)
  PlotBstsPredictionErrors(bsts.object, burn = SuggestBurn(.1, bsts.object),
                       time, style = c("dynamic", "boxplot"), ...)
  PlotBstsSize(bsts.object, burn = SuggestBurn(.1, bsts.object), style =
                       c("histogram", "ts"), ...)
  PlotSeasonalEffect(bsts.object, nseasons = 7, season.duration = 1,
                     same.scale = TRUE, ylim = NULL, get.season.name = NULL,
                     burn = SuggestBurn(.1, bsts.object),  ...)

Arguments

x

An object of class bsts.

bsts.object

An object of class bsts.

y

A character string indicating the aspect of the model that should be plotted.

burn

The number of MCMC iterations to discard as burn-in.

time

An optional vector of values to plot against. If missing, the default is to diagnose the time scale of the original time series.

same.scale

Logical. If TRUE then all the state components will be plotted with the same scale on the vertical axis. If FALSE then each component will get its own scale for the vertical axis.

show.actuals

Logical. If TRUE then actual values from the fitted series will be shown on the plot.

scale

The scale on which to plot the state. If the error family is "logit" or "poisson" then the state can either be plotted on the scale of the linear predictor (e.g. trend + seasonal + regression) or the linear predictor can be passed through the link function so as to plot the distribution of the conditional mean.

style

The desired plot style. Partial matching is allowed, so "dyn" would match "dynamic", for example.

layout

For controlling the layout of functions that generate mutiple plots.

inclusion.threshold

An inclusion probability that individual coefficients must exceed in order to be displayed when what == "coefficients". See the help file for plot.lm.spike.

number.of.variables

If non-NULL this specifies the number of coefficients to plot, taking precedence over inclusion.threshold. See plot.lm.spike.

ylim

Limits for the vertical axis. If NULL these will be inferred from the state components and the same.scale argument. Otherwise all plots will be created with the same ylim values.

nseasons

If there is only one seasonal component in the model, this argument is ignored. If there are multiple seasonal components then nseasons and season.duration are used to select the desired one.

season.duration

If there is only one seasonal component in the model, this argument is ignored. If there are multiple seasonal components then nseasons and season.duration are used to select the desired one.

get.season.name

A function that can be used to infer the title of each seasonal plot. It should take a single POSIXt, Date, or similar object as an argument, and return a single string that can be used as a panel title. If get.season.name is NULL and nseasons is specified or inferred to be one of the following values, then the following functions will be used.

• 4: quarters
• 7: weekdays
• 12: months

...

Additional arguments to be passed to PlotDynamicDistribution

Value

These functions are called for their side effect, which is to produce a plot on the current graphics device.

PlotBstsState invisibly returns the state object being plotted.

Details

PlotBstsState, PlotBstsComponents, and PlotBstsResiduals all produce dynamic distribution plots. PlotBstsState plots the aggregate state contribution (including regression effects) to the mean, while PlotBstsComponents plots the contribution of each state component. PlotBstsResiduals plots the posterior distribution of the residuals given complete data (i.e. looking forward and backward in time). PlotBstsPredictionErrors plots filtering errors (i.e. the one-step-ahead prediction errors given data up to the previous time point). PlotBstsForecastDistribution plots the one-step-ahead forecasts instead of the prediction errors.

PlotBstsCoefficients creates a significance plot for the predictors used in the state space regression model. It is obviously not useful for models with no regressors.

PlotBstsSize plots the distribution of the number of predictors included in the model.

PlotSeasonalEffect generates an array of plots showing how the distibution of the seasonal effect changes, for each season.

See Also

bsts PlotDynamicDistribution plot.lm.spike

Examples

  data(AirPassengers)
  y <- log(AirPassengers)
  ss <- AddLocalLinearTrend(list(), y)
  ss <- AddSeasonal(ss, y, nseasons = 12)
  model <- bsts(y, state.specification = ss, niter = 500)
  plot(model, burn = 100)
  plot(model, "residuals", burn = 100)
  plot(model, "components", burn = 100)
  plot(model, "forecast.distribution", burn = 100)