mixed.frequency {bsts} | R Documentation

## Models for mixed frequency time series

### Description

Fit a structured time series to mixed frequncy data.

### Usage

       bsts.mixed(target.series,
                  predictors,
                  which.coarse.interval,
                  membership.fraction,
                  contains.end,
                  state.specification,
                  regression.prior,
                  niter,
                  ping = niter / 10,
                  seed = NULL,
                  truth = NULL,
                  ...)

### Arguments

`target.series` | A vector object of class `zoo` indexed by calendar dates. The date associated with each element is the LAST DAY in the time interval measured by the corresponding value. The value is what Harvey (1989) calls a 'flow' variable. It is a number that can be viewed as an accumulation over the measured time interval.
`predictors` | A matrix of class `zoo` indexed by calendar dates. The date associated with each row is the LAST DAY in the time interval encompasing the measurement. The dates are expected to be at a finer scale than the dates in `target.series`. Any predictors should be at sufficient lags to be able to predict the rest of the cycle.
`which.coarse.interval` | A numeric vector of length `nrow(predictors)` giving the index of the coarse interval corresponding to the end of each fine interval.
`membership.fraction` | A numeric vector of length `nrow(predictors)` giving the fraction of activity attributed to the coarse interval corresponding to the beginning of each fine interval. This is always positive, and will be 1 except when a fine interval spans the boundary between two coarse intervals.
`contains.end` | A logical vector of length `nrow(predictors)` indicating whether each fine interval contains the end of a coarse interval.
`state.specification` | A state specification like that required by `bsts`.
`regression.prior` | A prior distribution created by `SpikeSlabPrior`. A default prior will be generated if none is specified.
`niter` | The desired number of MCMC iterations.
`ping` | An integer indicating the frequency with which progress reports get printed. E.g. setting `ping = 100` will print a status message with a time and iteration stamp every 100 iterations. If you don't want these messages set `ping < 0`.
`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.

`truth`

For debugging purposes only. A list containing one or more of the following elements. If any are present then corresponding values will be held fixed in the MCMC algorithm.

- A matrix named `state` containing the state of the coarse model from a fake-data simulation.

- A vector named `beta` of regression coefficients.

- A scalar named `sigma.obs`.

`...` | Extra arguments passed to SpikeSlabPrior

### Value

An object of class `bsts.mixed`, which is a list with the following elements. Many of these are arrays, in which case the first index of the array corresponds to the MCMC iteration number.

`coefficients` | A matrix containing the MCMC draws of the regression coefficients. Rows correspond to MCMC draws, and columns correspond to variables.
`sigma.obs` | The standard deviation of the weekly latent observations.
`state.contributions` | A three-dimensional array containing the MCMC draws of each state model's contributions to the state of the weekly model. The three dimensions are MCMC iteration, state model, and week number.
`weekly` | A matrix of MCMC draws of the weekly latent observations. Rows are MCMC iterations, and columns are weekly time points.
`cumulator` | A matrix of MCMC draws of the cumulator variable.

The returned object also contains MCMC draws for the parameters of the state models supplied as part of `state.specification`, relevant information passed to the function call, and other supplemental information.

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

### See Also

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

### Examples

      data <- SimulateFakeMixedFrequencyData(nweeks = 104, xdim = 20)

      ## Setting an upper limit on the standard deviations can help keep the
      ## MCMC from flying off to infinity.
      sd.limit <- sd(data$coarse.target)
      state.specification <-
           AddLocalLinearTrend(list(),
                         data$coarse.target,
                         level.sigma.prior = SdPrior(1.0, 5, upper.limit = sd.limit),
                         slope.sigma.prior = SdPrior(.5, 5, upper.limit = sd.limit))
      weeks <- index(data$predictor)
      months <- index(data$coarse.target)
      which.month <- MatchWeekToMonth(weeks, months[1])
      membership.fraction <- GetFractionOfDaysInInitialMonth(weeks)
      contains.end <- WeekEndsMonth(weeks)

      model <- bsts.mixed(target.series = data$coarse.target,
                          predictors = data$predictors,
                          membership.fraction = membership.fraction,
                          contains.end = contains.end,
                          which.coarse = which.month,
                          state.specification = state.specification,
                          niter = 500,
                          expected.r2 = .999,
                          prior.df = 1)

      plot(model, "state")
      plot(model, "components")

[Package bsts version 0.9.1 Index]