surveillance (version 1.23.1)

addSeason2formula: Add Harmonics to an Existing Formula

Description

This function helps to construct a formula object that can be used in a call to hhh4 to model seasonal variation via a sum of sine and cosine terms.

Usage

addSeason2formula(f = ~1, S = 1, period = 52, timevar = "t")

Value

Returns a formula with the seasonal terms added and its environment set to .GlobalEnv. Note that to use the resulting formula in hhh4, a time variable named as specified by the argument timevar must be available.

Arguments

f

formula that the seasonal terms should be added to, defaults to an intercept ~1.

S

number of sine and cosine terms. If S is a vector, unit-specific seasonal terms are created.

period

period of the season, defaults to 52 for weekly data.

timevar

the time variable in the model. Defaults to "t".

Author

M. Paul, with contributions by S. Meyer

Details

The function adds the seasonal terms $$ \sin( s \cdot 2\pi \cdot \code{timevar}/\code{period} ),\; \cos( s \cdot 2\pi \cdot \code{timevar}/\code{period} ), $$ for \(s = 1,\dots,\code{S}\) to an existing formula f.

Note the following equivalence when interpreting the coefficients of the seasonal terms: $$ \gamma \sin(\omega t) + \delta \cos(\omega t) = A \sin(\omega t + \epsilon) $$ with amplitude \(A = \sqrt{\gamma^2 + \delta^2}\) and phase shift \(\epsilon = \arctan(\delta / \gamma)\). The amplitude and phase shift can be obtained from a fitted hhh4 model via coef(..., amplitudeShift = TRUE), see coef.hhh4.

See Also

hhh4, fe, ri

Examples

# add 2 sine/cosine terms to a model with intercept and linear trend
addSeason2formula(f = ~ 1 + t, S = 2)

# the same for monthly data
addSeason2formula(f = ~ 1 + t, S = 2, period = 12)

# different number of seasons for a bivariate time series
addSeason2formula(f = ~ 1, S = c(3, 1), period = 52)