seasonal (version 0.20.2)

seas: Seasonal Adjustment with X-13ARIMA-SEATS

Description

Core function of the seasonal package. By default, seas calls the automatic procedures of X-13ARIMA-SEATS to perform a seasonal adjustment that works well in most circumstances.

Usage

seas(x, xreg = NULL, seats.noadmiss = "yes",
    transform.function = "auto",
    regression.aictest = c("td", "easter"),
    outlier = list(), automdl = list(),
    na.action = na.omit, out = FALSE, dir = NULL, ...)
  fivebestmdl(x)

Arguments

x

object of class "ts"": time series to seasonaly adjust.

xreg

(optional) object of class "ts"": one or several user defined exogenous variables for regARIMA modelling.

seats.noadmiss

spec 'seats' with argument noadmiss = "yes" (default). Seasonal adjustment by SEATS, if SEATS decomposition is invalid, an alternative model is used with a warning.

transform.function

spec transform with argument function = "auto" (default). Automatic log transformation detection. Set equal to "none" or "log" to turn off.

regression.aictest

spec regression with argument aictest = c("td", "easter") (default). AIC test for trading days and Easter effects. Set equal to NULL to turn off.

outlier

spec outlier without arguments (default). Automatic oulier detection. Set equal to NULL to turn off.

automdl

spec automdl without arguments (default). Automatic model search with the automodl module. Set equal to NULL to turn off.

na.action

a function which indicates what should happen when the data contain NAs. na.omit (default), na.exclude or na.fail.

out

logical, should the X-13ARIMA-SEATS standard output be saved in the "seas" object? (increases object size)

dir

character string with output path. If specified, the X-13ARIMA-SEATS output files are copied to this folder.

...

additional spec-arguments options (see details).

Value

• returns an object of class "seas", essentially a list with the following elements:
• err
  Warning messages from X-13ARIMA-SEATS.
• data
  An object of class "ts"", containing the seasonally adjusted data, the raw data, the trend component, the irregular component and the seasonal component.
• mdl
  A list with the model specification, similar to "spc"". It typically contains "regression"", which contains the regressors and parameter estimates, and "arima"", which contains the ARIMA specification and the parameter estimates.
• est
  More detailed information on the estimation.
• lks
  Summary statistics.
• coefficients
  Coefficients of the regARIMA model.
• se
  Standard errors of the regARIMA model.
• spc
  An object of class "spclist", a list containing everything that is send to X-13ARIMA-SEATS. Each spec is on the first level, each argument is on the second level. Checking "spc"" is good start for debugging.
• call
  Function call.
• The final function returns the adjusted series, the plot method shows a plot with the unadjusted and the adjusted series. summary gives an overview of the regARIMA model. static returns the static call from above that is needed to replicate an automatic seasonal adjustment procedure the model.

Details

Seasonal uses the same syntax as X-13ARIMA-SEATS. It is possible to invoke most options that are available in X-13ARIMA-SEATS. The X-13ARIMA-SEATS syntax uses specs and arguments, while each spec may contain some arguments. An additional spec-argument can be added to the seas function by separating spec and argument by a dot (.). For a more extensive description of the X-13ARIMA-SEATS in seas, consider the website on github (https://github.com/christophsax/seasonal)

References

Github page with a more detailed description. https://github.com/christophsax/seasonal

Wiki page with R examples from the X-13ARIMA-SEATS: https://github.com/christophsax/seasonal/wiki/Examples-of-X-13ARIMA-SEATS-in-R

X-13ARIMA-SEATS manual: http://www.census.gov/ts/x13as/docX13AS.pdf

Examples

x <- seas(AirPassengers)
summary(x)

# invoke X-13ARIMA-SEATS options as 'spec.argument'
# (consult the X-13ARIMA-SEATS manual for many more options and the wiki for
# for more examples)
seas(AirPassengers, regression.aictest = c("td"))  # no easter testing
seas(AirPassengers, force.type = "denton")  # force equality of annual values
seas(AirPassengers, x11 = list())  # use x11, overrides the 'seats' spec

# turn off automatic procedures:
seas(x = AirPassengers, regression.variables = c("td1coef", "easter[1]",
"ao1951.May"), arima.model = "(0 1 1)(0 1 1)", regression.aictest = NULL,
outlier = NULL, transform.function = "log")

# static replication of the first call
static(x)  # this also tests the equivalence of the static call
static(x, test = FALSE)  # no testing (for debuging)
static(x, coef = TRUE)  # also fixes the coefficients

# extractor functions
final(x)
original(x)
resid(x)
coef(x)

# five best models
fivebestmdl(x)

# replicating the default plots in Win X-13
plot(x)
plot(x, trend = TRUE)
monthplot(x)
monthplot(x, choice = "irregular")
spectrum(diff(final(x)) )
spectrum(diff(original(x)))
residplot(x)

# user defined regressors:
# a temporary level shift in R base
tls <- ts(0, start = 1949, end = 1965, freq = 12)
window(tls, start = c(1955, 1), end = c(1957, 12)) <- 1
seas(AirPassengers, xreg = tls, outlier = NULL)
# identical to a X-13ARIMA-SEATS specification of the the level shift
seas(AirPassengers, regression.variables = c("tl1955.01-1957.12"),
     outlier = NULL)

# analyzing X-13ARIMA-SEATS input and output files (for debuging)
spc(x)  # the .spc file, as generated by seas
mdl(x)  # the .mdl file, as received by seas

x3 <- seas(AirPassengers, out = TRUE)
out(x3)  # the full .out output from X-13ARIMA-SEATS (very long!)

# more components in a "seats" object
x$est$variance
x$lks

# standard NA handling with na.action
AirPassengersNA <- window(AirPassengers, start = c(1948, 6), end = c(1961, 4),
                          extend = TRUE)
final(seas(AirPassengersNA, na.action = na.omit))     # default
final(seas(AirPassengersNA, na.action = na.exclude))
# final(seas(AirPassengersNA, na.action = na.fail))   # fails

# inspection tool
inspect(AirPassengers)