add.trig {bsts}R Documentation

Trigonometric Seasonal State Component


Add a trigonometric seasonal model to a state specification.


     state.specification = NULL,
     sigma.prior = NULL,
     initial.state.prior = NULL,
     sdy = sd(y, na.rm = TRUE),
     method = c("harmonic", "direct"))



A list of state components that you wish to add to. If omitted, an empty list will be assumed.


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


A positive scalar giving the number of time steps required for the longest cycle to repeat.


A vector of positive real numbers giving the number of times each cyclic component repeats in a period. One sine and one cosine term will be added for each frequency.


An object created by SdPrior describing the prior distribution for the standard deviation of the increments for the harmonic coefficients.


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


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.


The method of including the sinusoids. The "harmonic" method is strongly preferred, with "direct" offered mainly for teaching purposes.


Harmonic Method

Each frequency 2 * pi * j / S where S is the period (number of time points in a full cycle) is associated with two time-varying random components: gamma[j, t], and gamma^*[j, t]. They evolve through time as

gamma[j, t + 1] = γ[j, t] * cos(λ_j) - γ^*[j, t] * sin(lambda_j) + error_0

gamma^*[j, t + 1] = γ^*[j, t] * cos(λ_j) - γ[j, t] * sin(lambda_j) + error_1

where error_0 and error_1 are independent with the same variance. This is the real-valued version of a harmonic function: gamma * exp(i * theta).

The transition matrix multiplies the function by exp(i * lambda_j), so that after 't' steps the harmonic's value is gamma * exp(i * lambda * t).

The model dynamics allows gamma to drift over time in a random walk.

The state of the model is (gamma_jt, gamma^*_jt), for j = 1, ... number of frequencies.

The state transition matrix is a block diagonal matrix, where block 'j' is

cos(lambda_j) sin(lambda_j)

-sin(lambda_j) cos(lambda_j)

The error variance matrix is sigma^2 * I. There is a common sigma^2 parameter shared by all frequencies.

The model is full rank, so the state error expander matrix R_t is the identity.

The observation_matrix is (1, 0, 1, 0, ...), where the 1's pick out the 'real' part of the state contributions.

Direct Method

Under the 'direct' method the trig component adds a collection of sine and cosine terms with randomly varying coefficients to the state model. The coefficients are the states, while the sine and cosine values are part of the "observation matrix".

This state component adds the sum of its terms to the observation equation.

y_t = beta[1, t] * sin(f[1] * t) + ... + beta[F, t] * sin(f[F] * t) + gamma[j, t] * cos(f[1] * t) + ... + gamma[F, t] * cos(f[F] * t)

The evolution equation is that each of the sinusoid coefficients follows a random walk with standard deviation sigma[j].

beta[j, t] = beta[j, t-1] + N(0, sigma[j, 1])^2 gamma[j, t] = gamma[j, t-1] + N(0, sigma[j, 2])^2

The direct method is generally inferior to the harmonic method. It may be removed in the future.


Returns a list with the elements necessary to specify a seasonal state model.


Steven L. Scott


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. SdPrior MvnPrior


  y <- log(AirPassengers)
  ss <- AddLocalLinearTrend(list(), y)
  ss <- AddTrig(ss, y, period = 12, frequencies = 1:3)
  model <- bsts(y, state.specification = ss, niter = 200)

  ## The "harmonic" method is much more stable than the "direct" method.
  ss <- AddLocalLinearTrend(list(), y)
  ss <- AddTrig(ss, y, period = 12, frequencies = 1:3, method = "direct")
  model2 <- bsts(y, state.specification = ss, niter = 200)

[Package bsts version 0.9.6 Index]