add.trig {bsts}  R Documentation 
Add a trigonometric seasonal model to a state specification.
AddTrig( state.specification = NULL, y, period, frequencies, sigma.prior = NULL, initial.state.prior = NULL, sdy = sd(y, na.rm = TRUE), method = c("harmonic", "direct"))
state.specification 
A list of state components that you wish to add to. If omitted, an empty list will be assumed. 
y 
The time series to be modeled, as a numeric vector. 
period 
A positive scalar giving the number of time steps required for the longest cycle to repeat. 
frequencies 
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. 
sigma.prior 
An object created by 
initial.state.prior 
An object created using

sdy 
The standard deviation of the series to be modeled. This
will be ignored if 
method 
The method of including the sinusoids. The "harmonic" method is strongly preferred, with "direct" offered mainly for teaching purposes. 
Each frequency 2 * pi * j / S where S is the period (number of time points in a full cycle) is associated with two timevarying 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 realvalued 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.
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, t1] + N(0, sigma[j, 1])^2 gamma[j, t] = gamma[j, t1] + 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 steve.the.bayesian@gmail.com
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.
data(AirPassengers) y < log(AirPassengers) ss < AddLocalLinearTrend(list(), y) ss < AddTrig(ss, y, period = 12, frequencies = 1:3) model < bsts(y, state.specification = ss, niter = 200) plot(model) ## 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) plot(model2)