seasonal (version 0.40.0)

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. Through the ... argument, it is possible to invoke almost all options that are available in X-13ARIMA-SEATS (see details). The default options are specified as explicit arguments and are discussed in the arguments section.

Usage

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

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, can be used both with regression or x11regression.

xtrans

(optional) object of class "ts": one or two user defined exogenous variables for the transform spec. Can be specifed together with xreg.

seats.noadmiss

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

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 automdl spec. 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? (this increases object size substantially, it is recommended to re-evaluate the model using the out functi

dir

character string with a user defined file path. If specified, the X-13ARIMA-SEATS output files are copied to this folder. Useful for debugging.

...

additional spec-arguments options sent to X-13ARIMA-SEATS (see details).

Value

• returns an object of class "seas", essentially a list with the following elements:
• err
  warning messages from X-13ARIMA-SEATS
• data
  seasonally adjusted data, the raw data, the trend component, the irregular component and the seasonal component
• regressioneffects
  regression variables multiplied by the vector of estimated regression coefficients
• model
  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.
• estimates
  detailed information on the estimation
• lkstats
  summary statistics
• sfspans
  (optional) data from sliding spans analysis
• transform.function
  character string, applied transformation
• fivebestmdl
  five best models according to BIC criterion
• qs
  QS statistics
• x
  input series
• spc
  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.
• call
  function call
• The final function returns the final adjusted series, the plot method shows a plot with the unadjusted and the adjusted series. summary gives an overview of the regARIMA model.

Details

seasonal uses a very similar syntax than the official X-13ARIMA-SEATS. The X-13ARIMA-SEATS syntax uses specs and arguments, and each spec optionally contains some arguments. In seas, an additional spec-argument can be added by separating spec and argument by a dot (.) (see examples).

For a more extensive description, consider the vignette or the wiki page, which contains replications of almost all examples from the official X-13ARIMA-SEATS manual.

References

Vignette with a more detailed description: http://cran.r-project.org/web/packages/seasonal/vignettes/seas.pdf

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

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

See Also

static, to return the static call that is needed to replicate an automatic model

inspect, to interactively inspect a seasonal adjustment model.

plot.seas, for diagnostical plots.

qs, for diagnostical statistics.

out, for diagnostical re-evaluation.

Examples

m <- seas(AirPassengers)
summary(m)

# 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 the automatic procedures
seas(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(m)  # this also tests the equivalence of the static call
static(m, test = FALSE)  # no testing (useful for debugging)
static(m, coef = TRUE)  # also fixes the coefficients

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

# five best models
fivebestmdl(m)

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

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

# input and output from and to X-13ARIMA-SEATS
spc(m)  # analyzing the .spc file (for debugging)
out(m)  # display the .out file (see ?out, for details)

# NA handling
AirPassengersNA <- window(AirPassengers, end = 1962, extend = TRUE)
final(seas(AirPassengersNA, na.action = na.omit))    # no NA in final series
final(seas(AirPassengersNA, na.action = na.exclude)) # NA in final series
# final(seas(AirPassengersNA, na.action = na.fail))    # fails

# inspect tool
inspect(m)