bsts (version 0.7.1)

add.holiday: Holiday state models

Description

Add a random-walk holiday model to a state specification.

This model allows each active day in a holiday window to move according to a random walk relative to the day's value the last time the holiday occurred.

Usage

AddFixedDateHoliday(state.specification = NULL,
                    holiday.name,
                    month,
                    day,
                    y,
                    sigma.prior = NULL,
                    initial.state.prior = NULL,
                    sdy = sd(as.numeric(y), na.rm = TRUE),
                    time0 = NULL,
                    days.before = 1,
                    days.after = 1)
AddNthWeekdayInMonthHoliday(state.specification = NULL,
                            holiday.name,
                            month,
                            day.of.week,
                            which.week,
                            y,
                            sigma.prior = NULL,
                            initial.state.prior = NULL,
                            sdy = sd(as.numeric(y), na.rm = TRUE),
                            time0 = NULL,
                            days.before = 1,
                            days.after = 1)
AddLastWeekdayInMonthHoliday(state.specification = NULL,
                             holiday.name,
                             month,
                             day.of.week,
                             y,
                             sigma.prior = NULL,
                             initial.state.prior = NULL,
                             sdy = sd(as.numeric(y), na.rm = TRUE),
                             time0 = NULL,
                             days.before = 1,
                             days.after = 1)
NamedHolidays(except = NULL)
AddNamedHolidays(state.specification = NULL,
                 named.holidays = NamedHolidays(),
                 y,
                 sigma.prior = NULL,
                 initial.state.prior = NULL,
                 sdy = sd(as.numeric(y), na.rm = TRUE),
                 time0 = NULL,
                 days.before = 1,
                 days.after = 1)

Arguments

state.specification

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

holiday.name

A string that can be used to label the holiday in output.

named.holidays

A character vector containing one or more recognized holiday names.

y

The time series to be modeled, as a numeric vector convertible to xts. This state model assumes y contains daily data.

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.

time0

An object convertible to POSIXt containing the date of the initial observation in the training data. If omitted and y is a zoo or xts object, then time0 will be obtained from the index of y[1].

days.before

An integer giving the number of days the influence of the holiday extends prior to the actual holiday.

days.after

An integer giving the number of days the influence of the holiday extends after the actual holiday.

month

A string naming the month in which the holiday occurs. Unambiguous partial matches are acceptable. Capitalize the first letter.

day

An integer specifying the day of the month on which the FixedDateHoliday occurs.

day.of.week

A string giving the weekday on which the NthWeekdayInMonthHoliday occurs.

which.week

An integer specifying the week of the month on which the NthWeekdayInMonthHoliday occurs. If which.week <= 0 then the holiday is assumed to occur on the last day.of.week in month.

except

If NULL then all named holidays are returned. If except is a character vector containing partial matches to holiday names, the matched names will be omitted from the returned list.

Value

NamedHolidays returns a character vector with the names of the recognized holiday.

The other functions return state.specification, after adding the requested state components.

AddNthWeekdayInMonthHoliday, AddLastWeekdayInMonthHoliday, and AddFixedDateHoliday can each add one holiday at a time. AddNamedHolidays will add several holidays at once, if named.holidays is a vector.

References

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 NormalPrior

Examples

# NOT RUN {
## TODO(stevescott):  add examples
# }