# seas

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

function.`.udg`

output file`.est`

output file`"spc"`

. It typically contains `"regression"`

, which
contains the regressors and parameter estimates, and `"arima"`

, which
contains the ARIMA specification and the parameter estimates.`"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.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.

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