add.monthly.annual.cycle {bsts}

Monthly Annual Cycle State Component

Description

A seasonal state component for daily data, representing the contribution of each month to the annual seasonal cycle. I.e. this is the "January, February, March, ..." effect, with 12 seasons. There is a step change at the start of each month, and then the contribution of that month is constant over the course of the month.

Note that if you have anything other than daily data, then you're probably looking for AddSeasonal instead.

The state of this model is an 11-vector \gamma_t where the first element is the contribution to the mean for the current month, and the remaining elements are the values for the 10 most recent months. When t is the first day in the month then

\gamma_{t+1} = -\sum_{i = 2}^11 \gamma_{t, i} + % \epsilon_t \qquad \epsilon_t \sim \mathcal{N}(0, \sigma)

And the remaining elements are \gamma_t shifted down one. When t is any other day then \gamma_{t+1} = % \gamma_t.

Usage

AddMonthlyAnnualCycle(state.specification,
                      y,
                      date.of.first.observation = NULL,
                      sigma.prior = NULL,
                      initial.state.prior = NULL,
                      sdy)

Arguments

state.specification

A list of state components, to which the monthly annual cycle will be added. If omitted, an empty list will be assumed.

y

The time series to be modeled, as a numeric vector.

date.of.first.observation

The time stamp of the first observation in y, as a Date or POSIXt object. If y is a zoo object with appropriate time stamps then this argument will be deduced.

sigma.prior

An object created by SdPrior describing the prior distribution for the standard deviation of the random walk increments.

initial.state.prior

An object created using NormalPrior, describing the prior distribution of the the initial state vector (at time 1).

sdy

The standard deviation of the series to be modeled. This will be ignored if y is provided, or if all the required prior distributions are supplied directly.

Examples

  ## Let's simulate some fake daily data with a monthly cycle.
## Not run: 
  residuals <- rnorm(365 * 5)

## End(Not run)

  n <- length(residuals)
  dates <- seq.Date(from = as.Date("2014-01-01"),
                    len = n,
                    by = 1)
  monthly.cycle <- rnorm(12)
  monthly.cycle <- monthly.cycle - mean(monthly.cycle)
  timestamps <- as.POSIXlt(dates)
  month <- timestamps$mon + 1

  new.month <- c(TRUE, diff(timestamps$mon) != 0)
  month.effect <- cumsum(new.month) 
  month.effect[month.effect == 0] <- 12

  response <- monthly.cycle[month] + residuals
  response <- zoo(response, timestamps)

  ## Now let's fit a bsts model to the daily data with a monthly annual
  ## cycle.
  ss <- AddLocalLevel(list(), response)
  ss <- AddMonthlyAnnualCycle(ss, response)

  ## In real life you'll probably want more iterations.
  model <- bsts(response, state.specification = ss, niter = 200)
  plot(model)
  plot(model, "monthly")