R: Dynamic intercept regression model

dirm {bsts} | R Documentation

## Dynamic intercept regression model

### Description

A dynamic intercept regression is a regression model where the intercept term is a state space model. This model differs from `bsts` in that there can be multiple observations per time point.

### Usage

    dirm(formula,
         state.specification,
         data,
         prior = NULL,
         contrasts = NULL,
         na.action = na.pass,
         niter,
         ping = niter / 10,
         model.options = DirmModelOptions(),
         timestamps = NULL,
         seed = NULL,
         ...)

### Arguments

`formula` | A formula, as you would supply to `lm` describing the regression portion of the relationship between y and X.
`state.specification` | A list with elements created by `AddLocalLinearTrend`, `AddSeasonal`, and similar functions for adding components of state. See the help page for `state.specification`. The state specification describes the dynamic intercept term in the regression model.
`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 are taken from `environment(formula)`, typically the environment from which `dirm` is called.
`prior` | A prior distribution for the regression component of the model, as created by `SpikeSlabPrior`. The prior for the time series component of the model will be specified during the creation of state.specification.
`contrasts` | An optional list containing the names of contrast functions to use when converting factors numeric variables in a regression formula. This argument works exactly as it does in `lm`. The names of the list elements correspond to factor variables in your model formula. The list elements themselves are the names of contrast functions (see `help(contr.treatment)` and the `contrasts.arg` argument to `model.matrix.default`). This argument can usually be omitted.
`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.
`model.options` | An object created by `DirmModelOptions` specifying the desired model options.
`timestamps` | The timestamp associated with each value of the response. This is most likely a `Date` or `POSIXt`. It is expected that there will be multiple observations per time point (otherwise 'bsts' should be used instead of 'dirm'), and thus the 'timestamps' argument will contain many duplicate values.
`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).

### Details

The fitted model is a regression model with an intercept term given by a structural time series model. This is similar to the model fit by `bsts`, but it allows for multiple observations per time period.

Currently `dirm` only supports Gaussian observation errors, but look for that to change in future releases.

### Value

An object of class `bsts` which is a list with the following components

`coefficients` | A `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.obs` | A 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.

### Author(s)

Steven L. Scott steve.the.bayesian@gmail.com

### 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.

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

### See Also

`bsts`, `AddLocalLevel`, `AddLocalLinearTrend`, `AddSemilocalLinearTrend`, `AddSeasonal` `AddDynamicRegression` `SpikeSlabPrior`, `SdPrior`.

### Examples

    SimulateDirmData <- function(observation.sd = 1, trend.sd = .1,
                                 time.dimension = 100, nobs.per.period = 3,
                                 xdim = 4) {
      trend <- cumsum(rnorm(time.dimension, 0, trend.sd))
      total.sample.size <- nobs.per.period * time.dimension
      predictors <- matrix(rnorm(total.sample.size * xdim),
        nrow = total.sample.size)
      coefficients <- rnorm(xdim)
      expanded.trend <- rep(trend, each = nobs.per.period)
      response <- expanded.trend + predictors %*% coefficients + rnorm(
        total.sample.size, 0, observation.sd)
      timestamps <- seq.Date(from = as.Date("2008-01-01"),
                             len = time.dimension, by = "day")
      extended.timestamps <- rep(timestamps, each = nobs.per.period)
      return(list(response = response,
        predictors = predictors,
        timestamps = extended.timestamps,
        trend = trend,
        coefficients = coefficients))
    }

    data <- SimulateDirmData(time.dimension = 20)
    ss <- AddLocalLevel(list(), data$response)

    # In real life you'd want more than 50 MCMC iterations.
    model <- dirm(data$response ~ data$predictors, ss, niter = 50,
      timestamps = data$timestamps)

[Package bsts version 0.9.6 Index]