Add Harmonics to an Existing Formula

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")

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

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.

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.

Author

M. Paul, with contributions by S. Meyer

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)