seas

0th

Percentile

Seasonal Adjustment with X-13ARIMA-SEATS

Main function of the seasonal package. With the default options, seas calls the automatic procedures of X-13ARIMA-SEATS to perform a seasonal adjustment that works well in most circumstances. Via the ... argument, it is possible to invoke almost all options that are available in X-13ARIMA-SEATS (see details). The default options of seas are listed as explicit arguments and are discussed in the arguments section. A full-featured graphical user interface can be accessed by the view function.

Usage
seas(x, xreg = NULL, xtrans = NULL, seats.noadmiss = "yes",
  transform.function = "auto", regression.aictest = c("td", "easter"),
  outlier = "", automdl = "", na.action = na.omit, out = FALSE,
  dir = NULL, ..., list = 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 message is returned). If noadmiss = "no", no approximation is done. If the seats spec is removed (seats = NULL), no seasonal adjustment is performed.
transform.function
spec transform with argument function = "auto" (default). Automatic log transformation detection. Set equal to "none", "log" or any value that is allowed by X-13 to turn it 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 it off.
outlier
spec outlier without arguments (default). Automatic oulier detection. Set equal to NULL to turn it off.
automdl
spec automdl without arguments (default). Automatic model search with the automdl spec. Set equal to NULL to turn it off.
na.action
a function which indicates what should happen when the data contain NAs. na.omit (default), na.exclude or na.fail. If na.action = na.x13, NA handling is done by X-13, i.e. NA values are substituted by -99999.
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 function instead.)
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).
list
a named list with additional spec-arguments options. This is an alternative to the ... argument. It is useful for programming.
Details

It is possible to use the almost complete syntax of X-13ARIMA-SEAT via the ... argument. The syntax of X-13ARIMA-SEATS 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). Alternatvily, spec-argument combinations can be supplied as a named list, which is useful for programming.

Similarily, the series function can be used to read almost all series from X-13ARIMA-SEATS. The udg function provides access to a large number of diagnostical statistics.

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.

Value

returns an object of class "seas", essentially a list with the following components:

series
a list containing the output tables of X-13. To be accessed by the series function.
data
seasonally adjusted data, the raw data, the trend component, the irregular component and the seasonal component (deprecated).
err
warning messages from X-13ARIMA-SEATS
udg
content of the .udg output file
est
content of the .est output file
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.
fivebestmdl
Best Five ARIMA Models (unparsed)
x
input series
spc
object of class "spclist", a list containing the content of the .spc file that is used by X-13ARIMA-SEATS. Each spec is on the first level, each argument is on the second level.
call
function call
wdir
temporary directory in which X-13ARIMA-SEATS has been run

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. The udg function returns diagnostical statistics.

References

Vignette with a more detailed description: http://www.seasonal.website/seasonal.html

Comprehensive list of R examples from the X-13ARIMA-SEATS manual: http://www.seasonal.website/examples.html

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

See Also

view, for accessing the graphical user interface.

update.seas, to update an existing "seas" model.

static, to return the 'static' call, with automated procedures substituted by their choices.

series, for universal X-13 table series import.

out, to view the full X-13 diagnostical output.

Aliases
  • seas
Examples
## Not run: ------------------------------------
# Basic call
# m <- seas(AirPassengers) 
# summary(m)
# 
# # Graphical user interface
# view(m)
# 
# # invoke X-13ARIMA-SEATS options as 'spec.argument' through the ... argument
# # (consult the X-13ARIMA-SEATS manual for many more options and the list of
# # R examples 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 = "")  # use x11, overrides the 'seats' spec
# 
# # 'spec.argument' combinations can also be supplied as a named list, which is
# # useful for programming
# seas(AirPassengers, list = list(regression.aictest = c("td"), outlier = NULL))
# # constructing the list step by step
# ll <- list()
# ll[["x"]] <- AirPassengers
# ll[["regression.aictest"]] <- "td"
# ll["outlier"] <- list(NULL)  # assigning NULL to a list using single brackets
# seas(list = ll)
# 
# # options can be entered as vectors
# seas(AirPassengers, regression.variables = c("td1coef", "easter[1]"))
# seas(AirPassengers, arima.model = c(0, 1, 1, 0, 1, 1))
# seas(AirPassengers, arima.model = "(0 1 1)(0 1 1)")     # equivalent
# 
# # 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 'm <- seas(AirPassengers)'
# static(m)  # this also tests the equivalence of the static call
# static(m, test = FALSE)  # no testing (much faster)
# static(m, coef = TRUE)  # also fixes the coefficients
# 
# # updating an existing model
# update(m, x11 = "")
# 
# # specific extractor functions
# final(m) 
# predict(m)   # equivalent
# original(m) 
# resid(m) 
# coef(m)
# fivebestmdl(m)
# out(m)                  # the X-13 .out file (see ?out, for details)
# spc(m)                  # the .spc input file to X-13 (for debugging)
# 
# # universal extractor function for any X-13ARIMA-SEATS output (see ?series)
# series(m, "forecast.forecasts")
# 
# # copying the output of X-13 to a user defined directory
# seas(AirPassengers, dir = "~/mydir")
# 
# # user defined regressors (see ?genhol for more examples)
# # 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)
# 
# # forecasting an annual series without seasonal adjustment
# m <- seas(airmiles, seats = NULL, regression.aictest = NULL)
# series(m, "forecast.forecasts")
# 
# # 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
# 
# # NA handling by X-13 (works with internal NAs)
# AirPassengersNA[20] <- NA 
# final(seas(AirPassengersNA, na.action = na.x13))
# 
# ## performing 'composite' adjustment
# m.direct <- seas(ldeaths, x11 = "")
# final.direct <- final(m.direct)
# m.indirect <- lapply(list(mdeaths, fdeaths), seas, x11 = "")
# 
#  # not very efficient, but keeps time series properties
# final.indirect <- Reduce(`+`, lapply(m.indirect, final)) 
# 
# ts.plot(cbind(final.indirect, final(m.direct)), col = 1:2)
# legend("topright", legend = c("disagregated", "aggregated"), lty = 1, col = 1:2)
# 
## ---------------------------------------------

Documentation reproduced from package seasonal, version 1.6.1, License: GPL-3

Community examples

Looks like there are no examples yet.