R Interface to X-13-ARIMA-SEATS

Easy-to-use interface to X-13-ARIMA-SEATS, the seasonal adjustment software by the US Census Bureau. It offers full access to almost all options and outputs of X-13, including X-11 and SEATS, automatic ARIMA model search, outlier detection and support for user defined holiday variables, such as Chinese New Year or Indian Diwali. A graphical user interface can be used through the 'seasonalview' package. Uses the X-13-binaries from the 'x13binary' package.

R interface to X-13ARIMA-SEATS

Build Status Build status Downloads

seasonal is an easy-to-use and full-featured R-interface to X-13ARIMA-SEATS, the newest seasonal adjustment software developed by the United States Census Bureau. X-13ARIMA-SEATS combines and extends the capabilities of the older X-12ARIMA (developed by the Census Bureau) and TRAMO-SEATS (developed by the Bank of Spain).

seasonal depends on the x13binary package (by Dirk Eddelbuettel and Christoph Sax) to access pre-built binaries of X-13ARIMA-SEATS for all platforms and does not require any manual installation.

If you are new to seasonal adjustment or X-13ARIMA-SEATS, the automated procedures of seasonal allow you to quickly produce good seasonal adjustments of time series. Start with the Installation and Getting started section and skip the rest. Alternatively, demo(seas) gives an overview of the package functionality.

If you are familiar with X-13ARIMA-SEATS, you may benefit from the flexible input and output structure of seasonal. The package allows you to use (almost) all commands of X-13ARIMA-SEATS, and it can import (almost) all output generated by X-13ARIMA-SEATS. The only exception is the 'composite' spec, which is easy to replicate in basic R. Read the Input and Output sections and have a look at the website of seasonal, where the examples from the official X-13ARIMA-SEATS manual are reproduced in R.

seasonal includes a graphical user interface that facitlitates the use of X-13 both for beginners and advanced users. The final sections of this vignette cover additional topics: User defined holidays, such as Chinese New Year, the use of seasonal for production, and the import of existing X-13 model specs to R.


seasonal relies on the x13binary package to access prebuilt binaries of X-13ARIMA-SEATS. To install both packages, type to the R console:


See the documentation of ?seasonal if you want to set the path to X-13 manually.

Getting started

seas is the 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:

m <- seas(AirPassengers)

The first argument of seas has to be a time series of class "ts". The function returns an object of class "seas" that contains all necessary information on the adjustment.

There are several functions and methods for "seas" objects: The final function returns the adjusted series, the plot method shows a plot with the unadjusted and the adjusted series. The summary method allows you to display an overview of the model:


By default, seas calls the SEATS adjustment procedure. If you prefer the X11 adjustment procedure, use the following option (see the Input section for details on how to use arbitrary options with X-13):

seas(AirPassengers, x11 = "")

A default call to seas also invokes the following automatic procedures of X -13ARIMA-SEATS:

  • Transformation selection (log / no log)
  • Detection of trading day and Easter effects
  • Outlier detection
  • ARIMA model search

Alternatively, all inputs may be entered manually, as in the following example:

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

The static command returns the manual call of a model. The call above can be easily generated from the automatic model:

static(m, coef = TRUE)  # also fixes the coefficients

If you have seasonalview installed, the view command offers an easy way to analyze and modify a seasonal adjustment procedure (see the section below for details):



In seasonal, it is possible to use almost the complete syntax of X-13ARIMA- SEATS. This is done via the ... argument in the seas function. The X -13ARIMA-SEATS syntax uses specs and arguments, with each spec optionally containing some arguments. These spec-argument combinations can be added to seas by separating the spec and the argument by a dot (.). For example, in order to set the 'variables' argument of the 'regression' spec equal to td and ao1999.jan, the input to seas looks like this:

m <- seas(AirPassengers, regression.variables = c("td", "ao1955.jan"))

Note that R vectors may be used as an input. If a spec is added without any arguments, the spec should be set equal to an empty string (or, alternatively, to an empty list, as in early versions). Several defaults of seas are empty strings, such as the default seats = "". See the help page (?seas) for more details on the defaults. Note the difference between "" (meaning the spec is enabled but has no arguments) and NULL (meaning the spec is disabled).

It is possible to manipulate almost all inputs to X-13ARIMA-SEATS in this way. The best way to learn about the relationship between the syntax of X-13ARIMA- SEATS and seasonal is to study the comprehensive list of examples. For instance, example 1 in section 7.1 from the manual,

series { title  =  "Quarterly Grape Harvest" start = 1950.1
       period =  4
       data  = (8997 9401 ... 11346) }
arima { model = (0 1 1) }
estimate { }

translates to R in the following way:

     x11 = "",
     arima.model = "(0 1 1)"

seas takes care of the 'series' spec, and no input beside the time series has to be provided. As seas uses the SEATS procedure by default, the use of X11 has to be specified manually. When the 'x11' spec is added as an input (like above), the mutually exclusive and default 'seats' spec is automatically disabled. With arima.model, an additional spec-argument is added to the input of X-13ARIMA-SEATS. As the spec cannot be used in the same call as the 'automdl' spec, the latter is automatically disabled.

There are some mutually exclusive specs in X-13ARIMA-SEATS. If more than one mutually exclusive spec is included in seas, specs are overwritten according the following priority rules:

  • Model selection

    1. arima
    2. pickmdl
    3. automdl (default)
  • Adjustment procedure

    1. x11
    2. seats (default)

As an alternative to the ... argument, spec-arguments can also be supplied as a named list. This is useful for programming:

seas(list = list(x = AirPassengers, x11 = ""))

Additionally, "seas" objects can be altered using the update method. It uses the same syntax as the seas function. The following example turns off trading day adjustment and switches the adjustment method to X-11:

update(m, regression.variables = "td", x11 = "")

A common use of update involves the recomputing with an x argument containing new data:

update(m, x = sqrt(AirPassengers))

Lastly, a predict method can be used to extract the final series from an updated call, using the familar newdata argument:

predict(m, newdata = sqrt(AirPassengers))


seasonal has a flexible mechanism to read data from X-13ARIMA-SEATS. With the series function, it is possible to import almost all output that can be generated by X-13ARIMA-SEATS. For example, the following command returns the forecasts of the ARIMA model as a "ts" time series:

m <- seas(AirPassengers)
series(m, "forecast.forecasts")

Because the forecast.save = "forecasts" argument has not been specified in the model call, series re-evaluates the call with the 'forecast' spec enabled. It is also possible to return more than one output table at the same time:

series(m, c("forecast.forecasts", "s12"))

You can use either the unique short names of X-13 (such as d1), or the long names (such as forecasts). Because the long table names are not unique, they need to be combined with the spec name (forecast). See ?series for a complete list of options.

Note that re-evaluation doubles the overall computation time. If you want to speed it up, you have to be explicit about the output in the model call:

m <- seas(AirPassengers, forecast.save = "forecasts")
series(m, "forecast.forecasts")

Some specs, like 'slidingspans' and 'history', are time consuming. Re-evaluation allows you to separate these specs from the basic model call:

m <- seas(AirPassengers)
series(m, "history.saestimates")
series(m, "slidingspans.sfspans")

The udg function provides access to a large number of diagnostical statistics:

udg(m, "x13mdl")

If you are using the HTML version of X-13, the out function shows the content of the main output in the browser:



There are several graphical tools to analyze a seas model. The main plot function draws the seasonally adjusted and unadjusted series, as well as the outliers. Optionally, it also draws the trend of the seasonal decomposition:

m <- seas(AirPassengers, regression.aictest = c("td", "easter"))

The monthplot function allows for a monthwise plot (or quarterwise, with the same function name) of the seasonal and the SI component:

monthplot(m, choice = "irregular")

Also, many standard R function can be used to analyze a "seas" model:


The identify method can be used to select or deselect outliers by point and click. Click several times to loop through different outlier types.


Graphical User Interface

The view function is a graphical tool for choosing a seasonal adjustment model, using the new seasonalview package, with the same structure as the demo website of seasonal. To install seasonalview, type:


The goal of view is to summarize all relevant options, plots and statistics that should be usually considered. view uses a "seas" object as its main argument:


Frequently used options can be modified using the drop-down selectors in the upper left panel. Each change will result in a re-estimation of the seasonal adjustment model. The R-call, the output and the summary are updated accordingly.

Alternatively, the R-Call can be modified manually in the lower left panel. Press 'Run Call' to re-estimate the model and to adjust the options selectors, the output, and the summary. With the 'To Console' button, view is closed and an updated model returned to the R console. The 'Static' button substitutes automatic procedures by their corresponding static spec-argument options, in the same way as the static function.

The views in the upper right panel can be selected from the drop-down menu.

The lower right panel shows the summary, including the same information as the summary method. The 'X-13 output' button opens the complete output of X-13 in a separate tab or window.

Chinese New Year, Indian Diwali and other customized holidays

seasonal includes genhol, a function that makes it easy to model user-defined holiday regression effects. genhol is an R replacement for the equally named software by the Census Office; no additional installation is required. The function uses an object of class "Date" as its first argument, which specifies the occurrence of the holiday.

In order to adjust Indian industrial production for Diwali effects, use, e.g.,:

# variables included in seasonal
# iip: Indian industrial production
# cny, diwali, easter: dates of Chinese New Year, Indian Diwali and Easter

     x11 = "",
     xreg = genhol(diwali, start = 0, end = 0, center = "calendar"), 
     regression.usertype = "holiday")

For more examples, including Chinese New Year and complex pre- and post-holiday adjustments, see ?genhol.

Production use

While seasonal offers a quick way to adjust a time series in R, it is equally suited for the recurring processing of potentially large numbers of time series. There are two kind of seasonal adjustments in production use:

  1. a periodic application of an adjustment model to a time series
  2. an automated adjustment to a large number of time series

This section shows how both tasks can be accomplished with seasonal and basic R.

Storing models and batch processing

Seasonal adjustment models can be stored (using save) and re-evaluated at a later date when new data becomes available.

ap.short <- window(AirPassengers, end = c(1959, 12))
m <- seas(ap.short)

The static function comes particularly handy to save the specifics of a model (e.g., outliers, ARIMA model) for future use. Often, it is desirable to store the following 'static' version of the model where the default automatic procedures in the model call are substituted by the choices they made. For example, in the model above, the automated procedures decided to perform a logarithmic pre- transformation of the data, to use an (0 1 1)(0 1 1) ARIMA model, to use trading day correction and to add an additive outlier in May, 1951. The static function 'hard-codes' these findings into the model call, so that these decisions would not be re-evaluated at a later date:

m.static <- static(m, evaluate = TRUE) 

Either the static or the automated model can be re-evaluated when new data becomes available:

update(m, x = AirPassengers)
update(m.static, x = AirPassengers)

Automated adjustment of large numbers of series

X-13 can also be applied to a large number of series, using automated adjustment methods. This can be accomplished with a loop or an apply function. It is useful to wrap the call to seas in a try statement; that way, an error will not break the execution. You need to develop an error handling strategy for these cases: You can either drop them, use them without adjustment or switch to a different automated routine.

# collect data 
dta <- list(fdeaths = fdeaths, mdeaths = mdeaths)

# loop over dta
l1 <- lapply(dta, function(e) try(seas(e, x11 = "")))

# list failing models
is.err <- sapply(l1, class) == "try-error"

# return final series of successful evaluations
do.call(cbind, lapply(l1[!is.err], final))

If you have several cores and want to speed things up, the process is well suited for parallelization:

# a list with 100 time series
l2 <- rep(list(AirPassengers), 100)

library(parallel)  # this is part of a standard R installation

If you are on Windows or want to use cluster parallelization, use parLapply:

# set up cluster
cl <- makeCluster(detectCores())

# load 'seasonal' for each node
clusterEvalQ(cl, library(seasonal))

# export data to each node
clusterExport(cl, varlist = "l2")

# run in parallel (2.2s on a 4-core / 8-thread Macbook, vs 9.6s with standard lapply)
parLapply(cl, l2, function(e) try(seas(e, x11 = "")))

# finally, stop the cluster

On Linux or OS-X, 'forking' parallelization allows you to do the same in a single line:

mclapply(l2, function(e) try(seas(e, x11 = "")), mc.cores = detectCores())

Import X-13 models and series

Two experimental utility functions allow you to import .spc files and X-13 data files from any X-13 set-up. Simply locate the path of your X-13 .spc file, and the import.spc function will construct the corresponding call to seas as well as the calls for importing the data.

# importing the orginal X-13 example file
import.spc(system.file("tests", "Testairline.spc", package="seasonal"))

If data is stored outside the .spc file (as it usually will be), the calls will make use of the import.ts function, which imports arbitrary X-13 data files as R time series. See ?import.ts for examples.

License and Credits

seasonal is free and open source, licensed under GPL-3. It requires the X -13ARIMA-SEATS software by the U.S. Census Bureau, which is open source and freely available under the terms of its own license.

seasonal has been originally developed for the use at the Swiss State Secretariat of Economic Affairs. It has been greatly improved over time thanks to suggestions and support from Matthias Bannert, Freya Beamish, Vidur Dhanda, Alain Galli, Ronald Indergand, Preetha Kalambaden, Stefan Leist, James Livsey, Brian Monsell, Pinaki Mukherjee, Bruno Parnisari, and many others. I am especially grateful to Dirk Eddelbuettel for the fantastic work on the x13binary package.

Please report bugs and suggestions on Github or send me an e-mail. Thank you!


1.6.1 2017-05-02


  • A second, more verbose run after a non-zero exit, to detect Fortran run time errors (https://github.com/christophsax/seasonal/issues/194)

bug fix

  • deal with new file in build 1.1.39 (macOS)
  • outlier(): workaround for problem with byte compiler in R 3.4.0 https://github.com/christophsax/seasonal/issues/209
  • import.spc(): fixed parsing of explicitly specified NULL entries E.g., regression{aictest=()} results in now regression.aictest = NULL (https://github.com/christophsax/seasonal/issues/202)
  • series(), out(): fix if model was updated using update() (https://github.com/christophsax/seasonal/issues/191)
  • some X-13 notes were not shown in summary (https://github.com/christophsax/seasonal/issues/200)
  • static parsing error with change of regime (https://github.com/christophsax/seasonal/issues/205)

1.5.1 2017-02-12

bug fix

  • removing 'udg' classification and as.data.frame() method from udg() output, because it messes up with several other functions.

1.5.0 2017-02-12


  • inspect() is defunct, use view() instead. Shiny application code removed from package.


  • as.data.frame() methods to coerce output of seas, summary.seas() and udg() to a data.frame. Useful for further processing (experimental). Replaces the experimental 'data.frame' argument in summary.seas() and udg() from the last version.

1.4.0 2016-12-23

new features

  • seasonal now uses the graphical user interface from the new seaonalview package. To install from CRAN, use: install.packages('seasonalview') Use the 'view()' function instead of 'inspect', which is deprecated and will be defunct soon.


  • new update() method, updates a "seas" object, works with R generic.
  • new predict() method, returns the final series of an (updated) "seas" object, works with R generic.
  • static() function has new argument 'x11.static'. If TRUE, moving averages of X-11 are fixed as well. (Thanks to Brian Monsell)
  • static() function has new argument 'evaluate'. If TRUE, it returns an evaluated call, an object of class "seas".
  • import.spc() function has new argument 'text', to accept the content of an X-13 .spc file as a character vector.
  • udg() and summary.seas() gain an optional 'data.frame' argument, which returns their info as a data.frame. Useful for further processing. (experimental)

bug fixes

  • import.spc imports arima models with commas. E.g., (0, 1, 1). (Thanks to Brian Monsell)
  • substitute colons in series name to avoid reading error.
  • shorten long series names to avoid X-13 error. (Both thanks to Bill Dunlap)
  • missing udg element in summary no longer leads to an error.
  • xreg specification ensures regression spec is used. (Thanks to Jose Pavia)
  • outlier plotted correctly for bi-annual data (SEATS only).

minor changes

  • U.S. unemployment as example series (experimental).
  • 'plot', 'residplot' and 'monthplot' are easier to customize.
  • import.spc() and import.ts() no longer experimental. They are here to stay.


  • reflect switch from inspect() to view()
  • documentation for update.seas() and predict.seas()
  • updated vignette
  • example on 'composite' in ?seas

1.3.0 2016-08-07

new features

  • udg(): utility function to extract type converted udg statistics e.g., M quality statistics of X-11
  • summary() can be customized, e.g, to include M quality statistics
  • methods for R generics: AIC(), BIC(), nobs(), logLik()


  • non-html binaries: startup message to announce drop of support
  • arimamodel(): use the more general 'udg(x, "x13mdl")'

under the hood

  • statistics used by other functions (e.g., summary) are imported by udg()
  • 'lks' output of X-13 is not used and produced anymore, as the content can be accessed by udg()


  • updated documentation to include udg()
  • various minor adjustments

bug fixes

  • estimate.armacmatrix can now be imported (https://github.com/christophsax/seasonal/issues/160)
  • minor fixes in inspect() (https://github.com/christophsax/seasonal/issues/162)
  • range outliers (e.g. TL) show up in plot.seas() with start date, rather than causing an error. (https://github.com/christophsax/seasonal/issues/163)

1.2.1 2016-02-11

bug fixes

  • If the startup check of x13binary has failed, this prevented seasonal from
    beeing loaded and installed. Now the startup check tells you what to do in such a case. This affects, e.g., Windows computers with library location set to an UNC path. (https://github.com/x13org/x13binary/issues/30)
  • temporarily change working directory on Windows, as X-13 (sometimes) writes to it. (https://github.com/x13org/x13binary/issues/28)

1.2.0 2016-01-22

major changes

  • No separate binary download required anymore! seasonal now depends on the x13binary package to access pre-built binaries of X-13ARIMA-SEATS for all platforms. Many thanks to Dirk Eddelbuettel for the fantastic work on x13binary!

    Installing seasonal and the binaries is now as easy as:



  • basic X-13 tests on all CRAN platforms (except Solaris)
  • The return value of the (experimental) import.spc function has a better name for the main compontent ('$seas', instead of '$call').


  • updated documentation to reflect the new installation process
  • new example in ?genhol: replicate X-13 Arima model in R
  • improved description of examples in ?import.spc

bug fixes

  • fix for rare convergence error messages
  • annual series are now recognized
  • 'inspect' call evaluated in global env. This solves an issue with series that had the same name as primitive functions (e.g., 'prod')
  • seas can be imported and used without loading the namespace (e.g. seasonal::seas())
  • plot.seas: fixed wrong sign in transfom = "PC" and "PCY"


  • slidingspans, revisions, regressioneffects have been defunct for a while and were removed from the package

1.1.0 2015-10-08

bug fixes

  • single series are dimension-less ts objects, rather than n times 1 matrices
  • more precise error msg in parse_spc


  • updated links to vignette and examples
  • new example in series

1.0.0 2015-08-14

new features

  • experimental import.spc, to read existing .spc files into R. Thanks, Brian Monsell.
  • experimental import.ts, to read existing X-13 data files into R.
  • with 'seats = NULL', seasonal adjustment can be completly turned of, to use X-13 for other purposes than seasonal adjustment.


  • within-session parallelization: the temporary location name of the X13 run now changes each time, which makes the function suitable for within-session parallelization (e.g., with mclapply). Cluster parallelization using parlApply works as before and is recommended on Windows machines. Thanks, Vidur Dhanda.
  • automated testing of all wiki examples on travis
  • error messages in inspect are html formatted

under the hood

  • rewritten parsing for spc and mdl files

bug fixes

  • some X13 warnings were not fully shown in summary
  • binary name now also shown in checkX13 on windows
  • fixes for error message parsing in non-html version

0.90.0 2015-05-08


  • completely redesigned inspect() graphical user interface, with the look and feel of the demo website: www.seasonal.website
  • support for the new X13 version 1.1 build 19 (released April 2, 2015)

under the hood

  • temporary files are cleaned up after execution


  • extended documentation for inspect()
  • list argument: no longer experimental

bug fixes

  • fixed parsing problem with build 19 in qs() that affected summary()
  • fixed parsing problem with exogenous regressors when using the list arg
  • input longer than 133 char is broken into multiple lines to avoid X-13 error
  • names of ARMA coefficients contain lag rather than period
  • X13 warnings are shown in summary (again)
  • better parsing breaking errors

0.80.0 2015-02-05


  • improved parsing and intergration of X-13 error messages
  • checkX13 performs more tests and returns an error report.
  • spec-arguments can also be entered as a named list (experimental)

under the hood

  • automated tests for all calls in the wiki


  • new vignette sections on user defined holidays and production use
  • new example on Indian Diwali in ?genhol
  • dates of Indian Diwali and Indian industrial production
  • more detailed documentation for ?summary.seas explaining output details

bug fixes

  • genhol() can be used inside a seas() call
  • arimamodel() shows model as expected


  • slidingspans, revisions, regressioneffects changed from deprecated to defunct

0.70.1 2014-10-02

new features

  • support for the HTML version of X-13. The 'out' function displays the output of X-13 in the browser.
  • The 'inspect' function is based on Shiny and can be used without RStudio. It offers access to all series that can be produced by X-13, as well as access to the HTML output of X-13.


  • empty specs can be specified as empty strings. This is more intuitive than the previously employed empty lists (which are still working). Empty strings are also used as defaults and in the documentation.
  • improved parsing of X-13 messages.
  • documentation improvements.

under the hood

  • flags are used when calling X-13. This makes some early g77 compilations for OS-X unusable.
  • use of the .udg file to extract summary statistics.
  • support for HTML and non-HTML versions of X-13.

bug fixes

  • numerical specification of arima.model led to wrong seasonal part.
  • restrict start year > 999, to avoid some millenium bugs.
  • si-ratio was wrongly extracted if no trend was estimated
  • 'series' drops an error if the requested series is not compatible with the adjustment method, rather than adjusting the method. E.g., if x11.trend is requested from a seats model, an error will be returned, rather than switching the adjustment to x11. The old behavior was confusing.

0.60.0 2014-05-09

new features

  • views of 'inspect' are now customizable
  • 'identify' method for outlier selection by point and click
  • demo(seas) for a demonstration of basic functionality

0.50.0 2014-03-27

new features

  • 'series' function, which allows the import of all tables produced by X-13 (except composite spec)


  • new na.action function: NA handling by X-13 (including interpolation)
  • 'out' function also reads '.log' and '.err' files
  • improved help pages
  • all examples from the X-13 manual are now in the wiki (except composite)
  • 'static' replicates a wider set of calls
  • summary shows decomposition method (X11, SEATS)
  • more flexible arima model specification (numeric vectors also allowed)


  • the functionality of 'slidingspans', 'revisions' and 'regressioneffects' is now part of the new 'series' function. The old functions are deprecated.

code improvements

  • code takes advantage of the series function, simplified import from X-13

0.40.0 2014-02-12

new features

  • support for 'slidingspans' and 'history' spec
  • genhol, a function to generate holiday regression variables
  • user defined variable for 'transform' spec
  • NA handling like in standard R
  • inspect function with model and transform selection, new views


  • new diagnostical statistics
  • summary shows some useful statistics
  • monthplot also shows SI ratios
  • easier access to X-13 .out content
  • regression effects can be extracted
  • checkX13 performs a test run
  • 'regression' and 'x11regression' specs can be combined
  • fewer, more structured help pages
  • comprehensive list of examples from the official manual

bug fixes

  • quotes in series name are now allowed
  • support for unorthodox frequencies (e.g. 2, 'seats' only)
  • spaces in folder names on windows are now allowed

code improvements

  • uses only standard R functions, no dependency on 'stringr'
  • clearer code structure

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.


1.6.1 by Christoph Sax, a year ago


Report a bug at https://github.com/christophsax/seasonal

Browse source code at https://github.com/cran/seasonal

Authors: Christoph Sax

Documentation:   PDF Manual  

Task views: Official Statistics & Survey Methodology, Time Series Analysis

GPL-3 license

Imports x13binary

Suggests seasonalview

Imported by BETS, Inflation, gunsales.

Depended on by ggseas, seasonalview.

Suggested by fpp2, stR, tsbox.

See at CRAN