\documentclass[nojss]{jss} %\VignetteIndexEntry{Seasonal Adjustment by X-13ARIMA-SEATS} \usepackage{amsmath} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% declarations for jss.cls %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%% %% almost as usual \author{ Christoph Sax\\University of Basel \And Dirk Eddelbuettel\\University of Illinois at Urbana-Champaign } \title{Seasonal Adjustment by X-13ARIMA-SEATS in \proglang{R}} %% for pretty printing and a nice hypersummary also set: \Plainauthor{Christoph Sax, Dirk Eddelbuettel} %% comma-separated \Plaintitle{Seasonal Adjustment by X-13ARIMA-SEATS in R} %% without formatting \Shorttitle{Seasonal Adjustment by X-13} %% a short title (if necessary) %% an abstract and keywords \Abstract{ \pkg{seasonal} is a powerful interface between \proglang{R} and X-13ARIMA-SEATS, the seasonal adjustment software developed by the United States Census Bureau. It offers access to almost all features of X-13, including seasonal adjustment via the X-11 and SEATS approaches, automatic ARIMA model search, outlier detection, and support for user-defined holiday variables such as the Chinese New Year or Indian Diwali. The required X-13 binaries are provided by the \pkg{x13binary} package, which facilitates a fully-automatic installation on most platforms. A demo website (at \url{http://www.seasonal.website}) supports interactive modeling of custom data. A graphical user interface in the \pkg{seasonalview} package offers the same functionality locally. X-13 can handle monthly, quarterly or bi-annual time series. This is a version of our article in the \emph{Journal of Statistical Software} \citep{jss}. } \Keywords{seasonal adjustment, time series, X-13ARIMA-SEATS, \proglang{R}} \Plainkeywords{seasonal adjustment, time series, X-13ARIMA-SEATS, R} %% without formatting %% at least one keyword must be supplied %% publication information %% NOTE: Typically, this can be left commented and will be filled out by the technical editor %% \Volume{50} %% \Issue{9} %% \Month{June} %% \Year{2012} %% \Submitdate{2012-06-04} %% \Acceptdate{2012-06-04} %% The address of (at least) one author should be given %% in the following format: \Address{ Christoph Sax\\ University of Basel\\ Peter Merian-Weg 6, Basel, Switzerland\\ ORCID: \href{https://orcid.org/0000-0002-7192-7044}{0000-0002-7192-7044}\\ E-mail: \email{christoph.sax@gmail.com}\\ URL: \url{http://www.christophsax.com}\\~\\ Dirk Eddelbuettel\\ University of Illinois at Urbana-Champaign\\ 725 S Wright St, Chicago, USA\\ ORCID: \href{https://orcid.org/0000-0001-6419-907X}{0000-0001-6419-907X}\\ E-mail: \email{edd@debian.org}\\ URL: \url{http://dirk.eddelbuettel.com}\\~\\ } %% It is also possible to add a telephone and fax number %% before the e-mail in the following format: %% Telephone: +43/512/507-7103 %% Fax: +43/512/507-2851 %% for those who use Sweave please include the following line (with % symbols): %% need no \usepackage{Sweave.sty} %% end of declarations %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% \begin{document} %% include your article here, just as usual %% Note that you should use the \pkg{}, \proglang{} and \code{} commands. % \section[About Java]{About \proglang{Java}} %% Note: If there is markup in \(sub)section, then it has to be escape as above. \section{Introduction}\label{introduction} Many time series exhibit a regular seasonal pattern over the year. US unemployment, for example, is usually higher from January to March, and again in June and July. Similarly, retail sales tend to peak with the Christmas season. To model the underlying structure of these series, any regular (seasonal) patterns are estimated and removed from the data. For example, to see if the economy is moving out of a recession during certain months, one wants the labor market data be free from such seasonal effects. Seasonal adjustment decomposes a time series into a trend, a seasonal and an irregular component and removes the seasonal component from the data. In official statistics, seasonal adjustment has a long tradition. The original X-11 software was developed by the US Census Bureau in the 1960s, and later improved by Statistics Canada \citep{dagum80}. Subsequent software packages by the US Census Bureau were called X-12-ARIMA \citep{findley98} and X-13ARIMA-SEATS (or X-13, for short) \citep{monsell07}. Today, X-11 is still used as a name for filter-based seasonal adjustment methods within X\nobreakdash-13. Meanwhile, TRAMO-SEATS, developed by the Bank of Spain \citep{caporello01}, offers an alternative model-based approach to seasonal adjustment. \begin{figure} \begin{center} \includegraphics{Figures/website.jpg} \caption{The website \url{http://www.seasonal.website} gives a full-featured preview of the modeling facilities of \pkg{seasonal}, including the possibility to upload and adjust time series. \label{fig:website}} \end{center} \end{figure} In its most recent version, X-13 offers these two seasonal adjustment methods in a single command-line tool, written in \proglang{Fortran}. The National Bank of Belgium has created an alternative \proglang{Java}-based implementation called JDemetra+ \citep{eurostat17} which is also widely deployed by statistical agencies. One of either the TRAMO-SEATS or X-11 method of seasonal adjustment is used by almost all (government) statistical offices throughout the world. \proglang{R} \citep{rcore16} offers several possibilities to perform seasonal adjustment in the \pkg{stats} package included with \proglang{R}. The \code{decompose} function uses filtering to split a time series into a trend, a seasonal and an irregular component. An alternative method is \code{stl}, which uses local regressions (and has some extensions offered by the \pkg{stlplus} package by \citet{hafen16}). While both methods allow a multiplicative or an additive decomposition, these methods are somewhat limited in modeling actual data series. The programs used by statistical offices provide an extensive toolbox to deal with many advanced (and more irregular) aspects of seasonality, such as trading day adjustments, moving holiday adjustments or automated outlier detection. To access these features, the \pkg{x12} package \citep{kowarik14} interfaces to the older X-12-ARIMA binaries, and can also be used with parts of X-13. Like \pkg{seasonal} \citep{seasonal}, it now depends on \pkg{x13binary} \citep{x13binary} to provide the binaries. \pkg{x12} hard-codes its available options, which offers limited to no extensibility beyond these pre-programmed options. The \pkg{seasonal} package addresses these shortcomings. Options are translated dynamically into X-13 spec files, which allows the interface to easily evolve with future developments of X\nobreakdash-13. \pkg{seasonal} depends on the \pkg{x13binary} package which provides the binaries of X-13, and removes the need for any manual installation or local compilation from the \proglang{Fortran} sources. This makes it easy for other CRAN packages such as \pkg{ggseas} \citep{ellis16} or \pkg{gunsales} \citep{aisch16} to depend on it. Finally, the syntax of \pkg{seasonal} is as \proglang{R}-like as possible; using it should not feel different from using \proglang{R}'s built-in functions. Users new to seasonal adjustment or X-13 should benefit from the automated procedures of \pkg{seasonal}, which enables them to quickly produce reasonably good seasonal adjustments of time series. On the other hand, users already familiar with X-13 may benefit from the flexible input and output structure of the package. It permits use of (almost) all of the several hundred of possible arguments to X-13, and can import (almost) all of the nearly two hundred output series that can be generated by X-13. The package contains several tools to make seasonal adjustment easier as for example a function for easy construction of moving holiday regressors such as Chinese New Year or Indian Diwali. It also offers the capability to import existing X-13 model specs from the command-line tool to \proglang{R}. The \pkg{seasonalview} \citep{seasonalview} package, a powerful graphical user interface based on \pkg{shiny} \citep{shiny16}, facilitates the use of X-13 both for beginners and advanced users. This article does not provide a general overview of seasonal adjustment as there are many good introductions to the topic; e.g., \citet{findley05} or \citet{ladiray12} for X\nobreakdash-11, or \citet{dagum16} for SEATS (signal extraction in ARIMA time series). A very good introduction from a practitioner's viewpoint is provided by \citet{ONS07}. The canonical reference for X-13 is the official manual by the \citet{census17}, which describes all available options and outputs in detail, and which will be referenced frequently in this article and in the documentation of the package. Last but not least, to try out X-13 and \pkg{seasonal} without installing any software locally, a full-featured website (at \url{http://www.seasonal.website}) allows uploading and modeling of time-series interactively, making use of the complete feature set of \pkg{seasonal}. Figure~\ref{fig:website} shows a screenshot of the website. The rest of the paper is organized as follows. An introductory example provides overall motivation in the following section. Input and Output formats are discussed in Sections~\ref{input} and \ref{output}. Section \ref{graphs} gives an overview of the different graphics choices, before Section~\ref{graphical-user-interface} introduces the graphical user interface. The creation of customized holiday variables, the use of X-13 and \pkg{seasonal} in larger-scale production settings, and the (scripted) import of X-13 model and series specifications are discussed in Sections~\ref{customized-holidays} to \ref{import-x-13-models-and-series}. Section \ref{deployment-via-x13binary} reviews the automated deployment by the \pkg{x13binary} package. Section~\ref{conclusions} concludes. \section{An introductory example}\label{an-introductory-example} As \pkg{seasonal} relies (and depends) on the \pkg{x13binary} package to access prebuilt binaries of X-13, installing it from CRAN is as easy as installing any other \proglang{R} package: \begin{CodeInput} R> install.packages("seasonal") \end{CodeInput} A discussion of the aspects related to automated deployment of the X-13 binary is provided in Section \ref{deployment-via-x13binary}. The \code{seas} function provides the core functionality of the package. By default, \code{seas} calls the automatic procedures of X-13 to perform a seasonal adjustment that works well in most circumstances: \begin{CodeInput} R> library("seasonal") R> m <- seas(unemp) \end{CodeInput} The first argument of \code{seas} is a time series of class \code{"ts"}. The \code{unemp} example series measures US unemployment and is included in \pkg{seasonal}. The function returns an object of class \code{"seas"} that contains the necessary information on the adjustment performed on this time series. \begin{figure} {\centering \includegraphics{Figures/plot} } \caption{Seasonal adjustment of US unemployment, using the defaults of \pkg{seasonal}. The result is close but not identical to the official seasonally adjusted series. \label{fig:plot}} \end{figure} There are several functions and methods for \code{"seas"} objects. The \code{final} function returns the adjusted series. The \code{plot} method shows a plot with the unadjusted and the adjusted series (see Figure~\ref{fig:plot} for an example). The \code{summary} method displays an overview of the model, very similar to the one produced by \proglang{R}'s \code{lm} function: \begin{CodeOutput} Call: seas(x = unemp) Coefficients: Estimate Std. Error z value Pr(>|z|) AR-Nonseasonal-01 0.9436 0.0344 27.4 <2e-16 *** MA-Nonseasonal-01 0.8254 0.0565 14.6 <2e-16 *** MA-Seasonal-12 0.8507 0.0336 25.3 <2e-16 *** --- Signif. codes: 0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1 SEATS adj. ARIMA: (1 1 1)(0 1 1) Obs.: 323 Transform: none AICc: 4.32e+03, BIC: 4.34e+03 QS (no seasonality in final): 0 Box-Ljung (no autocorr.): 22 Shapiro (normality): 0.995 \end{CodeOutput} By default, a call to \code{seas} also invokes the following automatic procedures of X-13: \begin{itemize} \item Transformation selection (log / no log); \item Detection of trading day and Easter effects; \item Outlier detection; \item ARIMA model search. \end{itemize} In the example above, X-13 opts to perform no pre-transformation, does not adjust for weekday or Easter effects, detects no outliers and models the series by a \code{(1\ 1\ 1)(0\ 1\ 1)} seasonal ARIMA (autoregressive integrated moving average) model. This can be seen from the summary output: There are no coefficients for Easter or outliers, and the ARIMA specification and the transformation are shown at the bottom. By default, \code{seas} calls the SEATS adjustment procedure (which decomposes the ARIMA model). To perform the alternative X-11 adjustment procedure\footnote{The X-11 method is also used by the US Bureau of Labor Statistics (BLS), in order to calculate official seasonally adjusted unemployment numbers. The numbers obtained in the examples above will not match the BLS numbers, for various reasons. One reason is that the BLS is adjusting unemployment by industry, before aggregating them. The BLS also applies a more sophisticated modeling of trading days and outliers. For details, see \citet{bls16}.}, the following option can be used (see the next section for details on how to use arbitrary options with X-13): \begin{CodeInput} R> seas(unemp, x11 = "") \end{CodeInput} Instead of relying on automated X-13 procedures, inputs may be entered `statically', as in this example: \begin{CodeInput} R> seas(x = unemp, + arima.model = "(1 1 1)(0 1 1)", + regression.aictest = NULL, + outlier = NULL, + transform.function = "none" + ) \end{CodeInput} Here, the specification of the `arima.model` overrides and turns off the automated model selection. AIC testing of the regressors, outlier detection and transformation are disabled. The next section describes the handling of mutually exclusive inputs in more detail. The \code{static} function substitutes all automated procedures by their static equivalents. The call above can be generated easily from our initial, fully automated model: \begin{CodeInput} R> static(m) \end{CodeInput} With the \pkg{seasonalview} package installed, the \code{view} command offers an easy way to analyze and modify a seasonal adjustment procedure, in the same way as it is possible on the website at \url{http://www.seasonal.website}: \begin{CodeInput} R> view(m) \end{CodeInput} and is discussed further below. \section{Input}\label{input} The X-13 software has several hundred options, and is capable of producing almost two hundred different output series. In order to keep the program code concise and to prepare for future developments of X-13, \pkg{seasonal} passes these arguments directly to X-13, rather than hard-coding them as \proglang{R} arguments. As for the input, it is possible to use almost\footnote{The only exception is the `composite' spec, which is at odds with the univariate syntax of \code{seas} but is straightforward to replicate in basic R. For an example, see \code{help("seas")}.} the complete syntax of X-13 via the \code{...} argument in the \code{seas} function. The input of X-13 is organized in \emph{specs} and \emph{arguments}, with each spec optionally containing some arguments (in the X-13 sense). These spec-argument combinations can be added to \code{seas} by separating the spec and the argument by a dot (\code{.}). For example, in order to set the `variables' argument of the `regression' spec equal to \code{td} and \code{ls2009.11}, and turn off the default `aictest' argument, the input to \code{seas} can be specified as follows: \begin{CodeInput} R> seas(unemp, + regression.variables = c("td", "ls2009.11"), + regression.aictest = NULL + ) \end{CodeInput} Note that \proglang{R} vectors may be used as an input. If a spec is added without any arguments (in the X-13 sense), the spec should be set equal to an empty string. Several defaults of \code{seas} are empty strings, such as the default \code{seats\ =\ ""} (see \code{help(seas)} for details). Note the difference between \code{""} (meaning the spec is enabled but has no arguments, in the X-13 sense) and \code{NULL} (meaning the spec is disabled). It is possible to manipulate almost all inputs to X-13 in that way. Chapter 7 of the X\nobreakdash-13 manual (US Census Bureau 2016) describes all available spec-argument combinations in detail. The comprehensive list of examples available at \url{http://www.seasonal.website/examples.html} offers numerous illustrations about the mapping of both functionality and syntax between X-13 and \pkg{seasonal}. For instance, the first example in Section 7.2 from the X-13 manual \citep{census17}, \begin{CodeInput} series { title = "Monthly sales" start = 1976.jan file = "ussales.dat" } regression { variables = (td seasonal) } automdl { } estimate { } x11 { } \end{CodeInput} can be computed in R as follows (using a dataset from \proglang{R} for simplicity): \begin{CodeInput} R> seas(AirPassengers, + x11 = "", + regression.variables = c("td", "seasonal"), + regression.aictest = NULL + ) \end{CodeInput} \code{seas} takes care of the `series' spec, and no input beside the time series has to be provided. As \code{seas} uses the SEATS procedure by default, the use of X-11 has to be specified explicitly. When the `x11' spec is added as an input (as above), the mutually exclusive default `seats' spec is automatically disabled. \code{automdl} and \code{estimate} are used by default. With \code{regression.variables}, an additional spec-argument is added to the input, which includes trading day and stable seasonal regression effects. Because \code{seas} performs an AIC test on the regression variables by default, it is disabled by setting \code{regression.aictest = NULL}. There are some mutually exclusive specs in X-13. If more than one mutually exclusive spec is included in \code{seas}, specs are overwritten according the following priority rules: \begin{itemize} \item Model selection: \begin{enumerate} \item \code{arima}, \item \code{pickmdl}, \item \code{automdl} (default). \end{enumerate} \item Adjustment procedure: \begin{enumerate} \item \code{x11}, \item \code{seats} (default). \end{enumerate} \end{itemize} This is why the default SEATS procedure in the introductory example was overwritten by the specification of \code{x11\ =\ ""}. For details on the differences between these methods, consider the manual of X-13 \citep{census17}. \code{seas} also accepts additional time series as external regressors or transformation variables via the \code{xreg} and \code{xtrans} arguments. The following example includes an external regressor for a level shift outlier from November 2009 to end of the series: \begin{CodeInput} R> lshift <- ts(-1, start = c(1990, 1), end = c(2019, 11), freq = 12) R> window(lshift, start = c(2009, 11)) <- 0 R> seas(unemp, xreg = lshift, outlier = NULL) \end{CodeInput} This can be used to replicate the built-in outlier adjustment of X-13: \begin{CodeInput} R> seas(unemp, regression.variables = "ls2009.11", outlier = NULL) \end{CodeInput} As an alternative to the \code{...} argument, spec-arguments can also be supplied as a named list which is particularly useful for non-interactive / programming use: \begin{CodeInput} R> seas(list = list(x = unemp, x11 = "")) \end{CodeInput} Additionally, \code{"seas"} objects can be altered using the \code{update} function method. It uses the same syntax as the \code{seas} function. The following example changes the ARIMA model and switches the adjustment method to X-11: \begin{CodeInput} R> update(m, arima.model = "(0 1 1)(0 1 1)", x11 = "") \end{CodeInput} A common use of \code{update} involves recomputing with new data. Using new data with an existing specification can be done using the update function:: \begin{CodeInput} R> update(m, x = unemp) \end{CodeInput} Alternatively, if only the final seasonally adjusted series is required, the \code{predict} function method can be used with the familiar \code{newdata} argument: \begin{CodeInput} R> predict(m, newdata = unemp) \end{CodeInput} \section{Output}\label{output} Comparable to the processing of input arguments, \pkg{seasonal} has a flexible, non hard-coded mechanism to extract data from X-13. With the \code{series} function, it is possible to import almost all output that can be generated. For example, the following command returns the forecasts of the ARIMA model as a \code{"ts"} time series: \begin{CodeInput} R> m <- seas(unemp) R> series(m, "forecast.forecasts") \end{CodeInput} X-13 requires the desired output to be specified in the input. Because the \code{forecast.save\ =\ "forecasts"} argument has not been specified in the model call, \code{series} \emph{re-evaluates} the call with the `forecast' spec enabled. It is also possible to return more than one output table at the same time: \begin{CodeInput} R> series(m, c("forecast.forecasts", "s12")) \end{CodeInput} The user can use either the unique short names of X-13 (such as \code{s12}, designating the final trend component from SEATS), or the long names (such as \code{forecasts}, designating the forecasts of the ARIMA model). Because the long table names are not unique, they need to be combined with the spec name (\code{forecast}). See \code{help(series)} for a list of all available options. Note that re-evaluation doubles the overall computation time, as X-13 has to run twice. To only run once and to speed it up, the model call should include the output explicitly in non-interactive use: \begin{CodeInput} R> m.save <- seas(unemp, forecast.save = "forecasts") R> series(m.save, "forecast.forecasts") \end{CodeInput} Some specs such as `slidingspans' and `history' can result in time-consuming computations. In interactive use, the re-evaluation feature is especially useful, as it allows to separate the time-consuming diagnostic computations from the fast basic model call: \begin{CodeInput} R> m <- seas(unemp) R> series(m, "history.saestimates") R> series(m, "slidingspans.sfspans") \end{CodeInput} The \code{out} function shows the content of the main X-13 output in the browser, which gives access to every detail of the estimation. \begin{CodeInput} R> out(m) \end{CodeInput} In order to process statistics in \proglang{R}, the \code{udg} function (which stands for \emph{unified diagnostic file}) gives a flexible access to all statistics from X-13: \begin{CodeInput} R> udg(m) \end{CodeInput} There are also wrappers that implement methods for the standard model diagnostics in \proglang{R}: \code{AIC}, \code{BIC}, \code{logLik}, \code{nobs}. \section{Graphs}\label{graphs} Several graphical tools are available to analyze a \code{"seas"} object. The main \code{plot} method draws the seasonally adjusted and unadjusted series (as shown in Figure~\ref{fig:plot}). If outliers were detected, these will also be indicated. The \code{monthplot} method produces a monthwise plot (or quarterwise, with the same misleading name as the generic \proglang{R} function) of the seasonal and the SI component: \begin{CodeInput} R> monthplot(m) \end{CodeInput} An example of an output from \code{monthplot} is given in Figure~\ref{fig:monthplot}. \begin{figure} {\centering \includegraphics{Figures/monthplot} } \caption{The \code{monthplot} output shows the seasonal and seasonal-irregular (SI) component of US unemployment for each month. The SI-component shows the detrended observations as the combined seasonal and irregular component. The straight line shows the average seasonal component over the whole sample period. US unemployment is usually higher from January to March, and again in June and July -- the winter peak got weaker, the summer peak got more accentuated over time. \label{fig:monthplot}} \end{figure} Also, many standard \proglang{R} functions can be used to analyze a \code{"seas"} object: \begin{CodeInput} R> pacf(resid(m)) R> spectrum(resid(m)) R> plot(density(resid(m))) R> qqnorm(resid(m)) \end{CodeInput} The \code{identify} method can be used to interactively select (or unselect) outliers by pointing and clicking; clicking several times on an outlier permits to loop through different outlier types: \begin{CodeInput} R> identify(m) \end{CodeInput} \section{Graphical user interface}\label{graphical-user-interface} The \pkg{seasonalview} package provides a graphical interface for choosing a seasonal adjustment model using \pkg{shiny} \citep{shiny16}. It provides the identical look and feel as the demo website at \url{http://www.seasonal.website}. To install the latest version of \pkg{seasonalview}, use: \begin{CodeInput} R> install.packages("seasonalview") \end{CodeInput} The goal of the \code{view} function is to summarize all relevant options, plots and statistics that form part of the seasonal adjustment process. \code{view} uses a \code{"seas"} object as its main argument and returns an updated \code{"seas"} object. Figure~\ref{fig:view} depicts a screenshot of the \code{view} function in action. \begin{CodeInput} R> view(m) \end{CodeInput} \begin{figure} \begin{center} \includegraphics{Figures/seasonal.jpg} \caption{The \code{view} function calls a graphical user interface that allows an interactive manipulation of most options of X-13. \label{fig:view}} \end{center} \end{figure} 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 \proglang{R}-Call, the output and the summary are updated accordingly. Alternatively, the \proglang{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, \code{view} is closed and an updated model is returned to the \proglang{R} console. The `Static' button substitutes automatic procedures by their corresponding static spec-argument options, in the same way as the \code{static} function. Users familiar with X-13 can also inspect and modify the X-13-Call, which can be accessed by the tab next to the \proglang{R}-Call. This also serves as a learning tool for users familiar with \pkg{seasonal} but not with X-13, and vice versa. 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 \code{summary} function method applied to a \code{"seas"} object. The `X-13 output' button opens the complete output of X-13 in a separate tab or window. \section{Customized holidays}\label{customized-holidays} \pkg{seasonal} includes \code{genhol}, a function that makes it easy to model user-defined holiday regression effects, such as the Chinese New Year, Indian Diwali or complex pre- and post-holiday adjustments for Easter. \code{genhol} is an \proglang{R} replacement for the equally named software by the Census Bureau. The function uses an object of class \code{"Date"} as its first argument, which specifies the occurrence of the holiday, and returns a time series that can be used as a regressor. Dates for some major moving holidays are included in the package (\code{easter} (Easter), \code{cny} (Chinese New Year), \code{diwali} (Indian Diwali)) and can be used with \code{genhol}. For example, in order to adjust Indian industrial production for Diwali effects, use: \begin{CodeInput} R> seas(iip, + x11 = "", + xreg = genhol(diwali, start = 0, end = 0, center = "calendar"), + regression.usertype = "holiday" + ) \end{CodeInput} \code{iip} is an example series and included in the package. Several examples, which cover Chinese New Year and complex pre- and post-holiday adjustments for Easter, are provided in the help page which can be accessed from \proglang{R} via \code{help("genhol")}. \section{Large-scale production use}\label{large-scale-production-use} While \pkg{seasonal} offers a fast and convenient way to adjust a single time series in \proglang{R}, it is equally well suited for processing large numbers of time series. Two kinds of seasonal adjustments are often used in a large-scale production environment: \begin{enumerate} \item a recurring application of a given adjustment model to a time series; \item an automated adjustment to a large number of time series. \end{enumerate} This section shows how both tasks can be accomplished with \pkg{seasonal} and basic \proglang{R}. \subsection{Storing calls and batch processing}\label{storing-calls-and-batch-processing} Seasonal adjustment models can be stored (using \code{save}) and re-evaluated at a later date when new data becomes available. Here, the \code{unemp} example series is shortened by one month, so that the following represents a model estimation with data available up to October 2016: \begin{CodeInput} R> unemp.oct16 <- window(unemp, end = c(2016, 10)) R> m.oct16 <- seas(unemp.oct16) \end{CodeInput} The \code{static} function has been introduced in the introductory example. It is particularly useful to save the specifics of a model (e.g., outliers, ARIMA specification) for future use. For example, in the model above, the automated procedures decided to use an (1 1 2)(0 1 1) ARIMA specification and to perform no pre-transfomation or weekday or Easter adjustments. The static function `hard-codes' these findings into the model call, so that these decisions would not be re-evaluated at a later date: \begin{CodeInput} R> m.oct16.static <- static(m.oct16, evaluate = TRUE) \end{CodeInput} With \code{evaluate = TRUE}, \code{static} returns an object of class \code{"seas"}, rather than just the call. Using data up to October 2016, the automated model, \code{m.oct16}, produces the same results as the static model, \code{m.oct16.static}. By default, evaluating the static model still re-estimates the ARIMA model parameters and the X-11 filters (if applicable). To avoid re-estimation, the arguments \code{coef} and \code{x11.filter} can be set to \code{TRUE}. Both models can be re-evaluated when new data becomes available. Here, the \code{update} function is used to update the existing models with the full \code{unemp} series, which ranges up to November 2016: \begin{CodeInput} R> update(m.oct16, x = unemp) R> update(m.oct16.static, x = unemp) \end{CodeInput} There is a crucial difference between these models at this later date: while the automated model search has opted for an (1 1 2)(0 1 1) ARIMA specification in October, it opts for an (1 1 1)(0 1 1) model in November, as has been demonstrated in the introductory example. By hard-coding the ARIMA specification into the call, it is ensured that the ARIMA model (and the other specifications of the model) do not change from month to month. Alternatively, in some production settings, it may be useful to copy the static call to a script, and re-run it when new data becomes available. \subsection{Automated adjustment of multiple series}\label{automated-adjustment-of-multiple-series} X-13 can also be applied programmatically to a large number of series using automated adjustment methods. This can be accomplished with a loop or one of the \code{*apply} functions in \proglang{R}. A good pattern of ``defensive programming'' is to wrap the call to \code{seas} in a \code{try} statement. Should an error occur, it will be trapped and not lead to a break in the execution. One needs to develop an error handling strategy for these cases. Possibilities for handling such error messages when processing one or more series are to either drop them, use them without adjustment or switch to a different automated routine. For example, time series can be collected in a \code{list} and looped over, using \code{lapply}: \begin{CodeInput} R> dta <- list(fdeaths = fdeaths, mdeaths = mdeaths) R> ll <- lapply(dta, function(e) try(seas(e, x11 = ""))) \end{CodeInput} Failing models can be listed as follows: \begin{CodeInput} R> is.err <- sapply(ll, class) == "try-error" R> ll[is.err] \end{CodeInput} The following returns final series of successful evaluations: \begin{CodeInput} R> do.call(cbind, lapply(ll[!is.err], final)) \end{CodeInput} To speed up the adjustment of multiple series, this process above is well suited for parallelization. The vignette, which can be accessed via \code{vignette("seasonal")}, provides an example. In many production settings, it is preferable to store the static model and re-evaluate with new data at a later point. This can be achieved as follows: \begin{CodeInput} R> ll.static <- lapply(ll, static, evaluate = TRUE) R> Map(predict, ll.static, newdata = dta) \end{CodeInput} \section{Import X-13 models and series}\label{import-x-13-models-and-series} Users of the X-13 command-line tool have two utility functions to import existing \code{.spc} files and data. The \code{import.spc} function will construct the corresponding call to \code{seas} and the calls for importing the data from an existing X-13 \code{.spc} file. For example, the following example imports the \code{Testairline.spc} file that is shipped with X-13 (and also included in \pkg{seasonal}): \begin{CodeInput} R> import.spc(system.file("tests", "Testairline.spc", package="seasonal")) \end{CodeInput} If data is stored outside the \code{.spc} file (as it usually will be), the calls will make use of the \code{import.ts} function to import the data referenced in the \code{.spc} file as \proglang{R} time series. An example is given in the documentation (see \code{help("import.ts")}). \section[Deployment via x13binary]{Deployment via \pkg{x13binary}}\label{deployment-via-x13binary} X-13 has a long and proud history of use and deployment by countless users, including many governmental statistical agencies as discussed above. During most of the several decades of widespread use, analysts deploying X-13 had to \emph{manually} download the corresponding program from the Census website. (Or rely on their IT department to do it for them.) The rise of \proglang{R} to pre-eminence as a statistical environment has highlighted how useful and important automated deployment via package repositories is. Thousands of packages are available, and can be installed via a simple command, function call or click of a button. This triggers either a download of a prebuilt binary version in the case of the Windows and macOS operating systems, or the download and automated installation from source for machines running Unix or Linux. Early use of \pkg{seasonal}, however, relied on the standard installation procedure devised by US Census for X-13. Users either had to download a binary pre-built for a number of operating systems, or build a binary from the supplied \proglang{Fortran} source code. After that first manual step, a second step was required to communicate the presence, and location, of the binary to the package using it, in this case \pkg{seasonal}. This process was both overly manual, error-prone and platform-dependent. But it was not for lack of a suitable license. Works by the US Government are generally in the public domain and can be re-distributed. So a better solution was always conceivable. The \pkg{x13binary} package \citep{x13binary} addresses this need by utilizing the tried-and-tested CRAN package mechanism. By being set-up as a package, two entry points for customizations are available: build-time, and run-time. At package build-time, the script \code{configure} determines the type of operating system it is being used on, and acts accordingly to provide either a binary, or creates one via compilations. At run-time when the package is loaded, it provides several convenience functions to assess the validity of its X-13 installation, or to communicate the path of the binary to other packages requiring it---as for example \pkg{seasonal}. The \pkg{x13binary} relies on another external resource to provide it with ``always accessible'' sources or binaries in a structured form. The \pkg{x13prebuilt} repository \citep{x13prebuilt} provides this in the form of statically compiled binaries for Linux and macOS, as well as a zip archive with a Windows binary. \pkg{x13binary} is set up to utilize these files and automatically place them in the expected location for the respective operating system and variant. Taken together, packages \pkg{x13binary} and \pkg{x13prebuilt} ensure that users executing the step recommended in the introductory section \begin{CodeInput} R> install.packages("seasonal") \end{CodeInput} will be provided with a fully functional installation including X-13 without any manual invention. Thanks to the \proglang{R} package system, \pkg{seasonal} can depend on \pkg{x13binary} which by utilizing \pkg{x13prebuilt} will ensure a correct and complete installation ready to be deployed for seasonal adjustment. If the binaries cannot be downloaded (e.g., because of a firewall), it is still possible to manually download the binaries and tell \pkg{seasonal} where to find them. \code{help("seasonal")} provides additional details on this. Updating \pkg{x13binary} follows the schedule of the US Census Bureau, which usually updates once a year. Version numbers of \pkg{x13binary} are aligned with version numbers of the Census Bureau, and older versions can be easily installed from the CRAN archives. \section{Conclusions}\label{conclusions} X-13ARIMA-SEATS is a very powerful tool for seasonal adjustment. It is used by numerous statistical offices around the world. \pkg{seasonal} brings the full functionality of X-13 to \proglang{R}. This considerably lowers the barrier to increased use of these powerful seasonal adjustment methods given the widespread and ever increasing popularity of \proglang{R}. The \pkg{seasonal} package is designed so that the use of its principal function \code{seas} feels very similar to key modeling functions of \proglang{R} such as the ubiquitous \code{lm} method. Data structures in the \pkg{seasonal} package interact seamlessly with the built-in time series objects for \proglang{R} which makes it easy to construct custom regressors or holiday variables. The input and output facilities are flexible enough to support the full functionality of X-13 and permit easy adoption to future versions. In addition, the \pkg{seasonalview} package adds a graphical user interface which simplifies the manipulation of seasonal adjustment models. The \pkg{x13binary} package automates dependency resolution and installation of the required binaries via the time-tested \proglang{R} package system, and allows other packages to extend \pkg{seasonal}. \section*{Acknowledgments}\label{acknowledgments} \pkg{seasonal} was originally developed for 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, Pinaki Mukherjee, Bruno Parnisari, five anonymous reviewers and many others. The related work on the \pkg{x13binary} package facilitated (automated) deployment thanks to the \proglang{R} package system, CRAN as well as GitHub for the \pkg{x13prebuilt} repository. Help and support by Brian Monsell and the United States Census Bureau is gratefully acknowledged as is, of course, their seasonal adjustment software. % \bibliographystyle{jss} \bibliography{jss3006} \end{document}