boiwsa (version 1.1.4)

boiwsa: Seasonal adjustment of weekly data

Description

Performs seasonal adjustment and forecasting of weekly time series using a regression-based decomposition framework estimated by discounted least squares. Seasonality is modeled using trigonometric regressors, while holiday, trading-day, and calendar effects are incorporated through additional covariates. Additive outliers can be detected automatically using an optional outlier search procedure. The function supports both additive and multiplicative decompositions and produces seasonally adjusted series together with the associated model components. Worked examples and additional usage illustrations are available in the package repository on GitHub. See Ginker (2024), boiwsa: An R Package for Seasonal Adjustment of Weekly Data, The R Journal, 16(3), 186--197.

Usage

boiwsa(
  x,
  dates,
  r = 0.8,
  auto.ao.search = TRUE,
  out.threshold = 3.8,
  ao.list = NULL,
  my.k_l = NULL,
  H = NULL,
  ic = "aicc",
  method = "additive"
)

Value

A list with the following components:

sa

Seasonally adjusted series.

my.k_l

Number of trigonometric regressors used to model seasonality.

sf

Estimated seasonal component.

hol.factors

Estimated holiday and trading-day effects.

out.factors

Estimated additive outlier effects.

beta

Regression coefficients estimated for the last year of data.

m

Unweighted lm object estimated on the full sample.

Arguments

x

Numeric vector containing the observed weekly time series.

dates

A vector of class "Date" corresponding to the observation dates.

r

Numeric scalar in (0, 1] defining the rate of decay of the observation weights. Defaults to 0.8.

auto.ao.search

Logical. If TRUE, additive outliers are detected automatically.

out.threshold

Numeric. t-statistic threshold used in the additive outlier search. Defaults to 3.8.

ao.list

Optional vector of class "Date" specifying user-defined additive outlier dates.

my.k_l

Optional numeric vector of length two specifying the number of yearly and monthly trigonometric variables. If NULL, these are selected automatically using the information criteria. The search range is 0:36 and 0:12 with the step size of 6 for the yearly and monthly variables, respectively.

H

Optional matrix of holiday and trading-day regressors with the same number of rows as x.

ic

Character string specifying the information criterion used in the automatic selection of trigonometric regressors. One of "aic", "aicc", or "bic". Defaults to "aicc".

method

Character string specifying the decomposition type. Either "additive" or "multiplicative".

Author

Tim Ginker

Details

The methodological framework implemented in this function is described in Ginker (2024), boiwsa: An R Package for Seasonal Adjustment of Weekly Data, The R Journal, 16(3), 186--197.

Examples

 # Not run
 # Seasonal adjustment of weekly US gasoline production
 # \donttest{
 data("gasoline.data")
 res=boiwsa(x=gasoline.data$y,dates=gasoline.data$date)# }