3 The fundamentals of X-13

X-13ARIMA-SEATS is organized by specs. Specs are software modules that deal with a particular task needed in the seasonal adjustment process. For example, the transform spec deals with the initial transformations of the time series. This spec will take care of if a series should be adjusted in logarithms.

3.1 Main specs

Some specs, like the transform and the regression spec, are used in most seasonal adjustment processes. Others fulfill a particular function and are used only occasionally. For example, the history spec allows an analysis of the revision history and is only called for diagnostical purposes. Other specs are mutually exclusive. You can choose x11 or seats to decompose a time series, but not both. Table 3.1 lists the main specs of X-13 and describes what they do.

Table 3.1: Important specs that are used in most seasonal adjustment models
Spec name	What it does	Chapter
`estimate`	Estimates the regARIMA model specified by the `regression` and `arima` specs.	Chapter 5
`arima`	Specifies the ARIMA part of the regARIMA model.	Chapter 5
`regression`	Specification for including regression variables in a regARIMA model.	Chapter 5, Chapter 8, Chapter 9
`automdl`	Specifies the ARIMA part of the regARIMA model using an automatic procedure.	Chapter 5
`outlier`	Specification to perform automatic detection of additive (point) outliers.	Chapter 10
`seats`	Invoke the production of model-based signal extraction using SEATS. Default in the R seasonal package.	Chapter 7
`x11`	An optional spec for invoking seasonal adjustment by the X-11 methodology.	Chapter 6
`forecast`	Specification to forecast and/or backcast the time series given in the series spec using the estimated model.	Chapter 5

3.2 Interactions between specs

X-13 specs interact with each other. For example, once a series is transformed, it is usually passed to the regression and arima specs, which estimate a regARIMA model. To come up with a good model, it uses the automdl spec to determine a good ARIMA model automatically. To correct outlier values, it collaborates with the outlier spec. Once the series is modeled, it is decomposed either by the seats or the x11 spec. Figure 6.1 shows the interaction between the main specs in a typical seasonal adjustment run.

flowchart LR
    A(  transform  )-->regARIMA
    subgraph regARIMA
    direction LR
    B(estimate)<-->D(regression)
    B<-->C(automdl)
    B<-->E(arima)
    end
    regARIMA --> F(seats)
    regARIMA --> G(x11)

Figure 3.1: Interactions between X-13 specs.

3.3 Specs Arguments

Within specs, there are arguments. Spec arguments guide the behavior of the spec. For example, the function argument in the transform spec can be set to "auto", "none", "log", "sqrt", "inverse" or "logistic“. The default is set to "auto", which causes an automated model evaluation between "log" and "none". There are many other arguments, and the X-13 Manual (US Census Bureau 2017) is the canonical reference. This book will list and explain the frequently used arguments while skipping some of the more exotic ones.

US Census Bureau. 2017. X-13ARIMA-SEATS Reference Manual. Version 1.1. Washington, DC, USA: Time Series Research Staff, Center for Statistical Research; Methodology, US Census Bureau. https://www2.census.gov/software/x-13arima-seats/x-13-data/documentation/docx13as.pdf.

3.4 Addressing specs from R

In the R package seasonal, spec argument combinations can be directly fed to the seas() function. For example, to turn off the log transformation in the AirPassengers example from Section 2.2, we can specify the following:

m_no_log <- seas(AirPassengers, transform.function = "none")
summary(m_no_log)
#> 
#> Call:
#> seas(x = AirPassengers, transform.function = "none")
#> 
#> Coefficients:
#>                   Estimate Std. Error z value Pr(>|z|)    
#> Constant          30.62077    4.60956   6.643 3.08e-11 ***
#> Leap Year         11.32104    3.43088   3.300 0.000968 ***
#> Weekday           -0.90361    0.17787  -5.080 3.77e-07 ***
#> Easter[1]          6.89372    1.80972   3.809 0.000139 ***
#> AR-Nonseasonal-01  0.81929    0.04903  16.709  < 2e-16 ***
#> ---
#> Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
#> 
#> SEATS adj.  ARIMA: (1 0 0)(0 1 0)  Obs.: 144  Transform: none
#> AICc: 993.4, BIC:  1010  QS (no seasonality in final):    0  
#> Box-Ljung (no autocorr.):  29.2   Shapiro (normality): 0.984

As you can see from the lower part of the summary, transform is now set equal to none. Note that the change in the transform argument has also affected the other specs. The ARIMA model is different now, and a leap-year adjustment is performed. We will discuss the working of the transform spec in more detail in the next chapter.

3.5 Less frequently used specs

While the main specs appear in most seasonal adjustment processes, other specs are less often used. Some of them have a diagnostic purpose. The spectrum spec, for example, draws and analyses the spectrum of a time series, similar to the R base function spectrum(). Other specs are more elaborate. For example, the history spec produces a sequence of runs from a sequence of truncated versions of the time series and allows the analysis of potential revisions. The slidingspans spec models various parts of the time series and has a similar purpose as history. All diagnostics specs are listed in Table 3.3.

Table 3.2: Diagnostic specs
Spec name	What it does	Chapter
`history`	Requesting a sequence of runs from a sequence of truncated versions of the time series for the purpose of creating historical records.	Chapter 16
`slidingspans`	Providing sliding spans stability analysis.	Chapter 16
`identify`	Produce tables and line printer plots of sample ACFs and PACFs.
`spectrum`	Provides a choice between two spectrum diagnostics to detect seasonality or trading day effects.
`check`	Produce statistics for diagnostic checking of residuals from the estimated model.

The force and the composite spec are special-purpose specs. The former enforces the yearly totals of the seasonally adjusted series to be equal to those of the original series. The latter allows a comparison of indirect and direct seasonal adjustments. Table 3.3 gives an overview of the special-purpose specs.

Table 3.3: Special purpose specs
Spec name	What it does
`force`	Allow users to force yearly totals of the seasonally adjusted series to equal those of the original series for convenience.	Chapter 13
`composite`	Obtaining both indirect and direct adjustments of a composite series.	Chapter 14

Finally, a few specs are not covered in this book. Some of them are vintage specs that were important in earlier versions of X-13 but were superseded by other specs. It is generally recommended to use regression instead of x11regression and automdl instead of pickmdl. Other specs have a purely technical purpose. For example, the series spec provides X-13 with the data, starting date, and frequency. In R, this is handled by seasonal and will not be covered.

Table 3.4: Vintage and technical specs that won’t be covered in this book)
Spec name	What it does
`x11regression`	Alternative to `regression`. Can only be used with X11.
`pickmdl`	Alternative to `automdl`. Can only be used with X11.
`series`	Provides X-13 with the data, the starting date and the frequency. In R, this is handled by seasonal and will not be covered.
`metadata`	Specification that allows users to insert metadata into the diagnostic summary file. In R, this is handled by seasonal and will not be covered.

3.6 Main user choices

While we will cover each spec in more detail, this section provides a few examples of frequent user choices. As we saw in the previous chapter, by default, seasonal uses defaults that work well in many circumstances. The following is a non-exhaustive list of deviations from the defaults. The default options of seas() are listed as explicit arguments and are discussed in the arguments section of the help page of

3.6.1 Using X11

While seas() calls SEATS by default, X11 is often easier to use. To perform a seasonal adjustment on AirPassengers with X11, we need to activate the x11 spec.

m_x11 <- seas(AirPassengers, x11 = list())

An empty list list() tells seas() to use the spec without an argument. Alternatively, you can also use an empty string, "". If more than one mutually exclusive spec is included in seas(), specs are overwritten according to the priority rules shown in Table 3.5

Table 3.5: If more than one mutually exclusive spec is included, specs are overwritten according to priority rules.
Procedure	Priority rules
Model selection	`arima` `pickmdl` `automdl`
Adjustment procedure	`x11` `seats`

This is why the default SEATS procedure in the introductory example was overwritten by the specification of x11 = "".

3.6.2 Turning off automatic ARIMA modeling

By default, the automdl spec finds a good ARIMA model. By specifying the model argument of the arima spec, the automated modeling is deactivated. Instead of the automatically chosen (0 1 1)0 1 1) ARIMA model, the following estimates an (1 1 0)1 1 0) model.

m_arima <- seas(AirPassengers, arima.model = c(1, 1, 0, 1, 1, 0))
summary(m_arima)
#> 
#> Call:
#> seas(x = AirPassengers, arima.model = c(1, 1, 0, 1, 1, 0))
#> 
#> Coefficients:
#>                     Estimate Std. Error z value Pr(>|z|)    
#> Weekday           -0.0029124  0.0004794  -6.076 1.23e-09 ***
#> Easter[1]          0.0167907  0.0067080   2.503   0.0123 *  
#> AO1951.May         0.0950587  0.0194363   4.891 1.00e-06 ***
#> AR-Nonseasonal-01 -0.1078564  0.0871940  -1.237   0.2161    
#> AR-Seasonal-12    -0.4588948  0.0790634  -5.804 6.47e-09 ***
#> ---
#> Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
#> 
#> SEATS adj.  ARIMA: (1 1 0)(1 1 0)  Obs.: 144  Transform: log
#> AICc: 951.6, BIC: 968.1  QS (no seasonality in final):    0  
#> Box-Ljung (no autocorr.): 35.88 . Shapiro (normality): 0.9937

3.6.3 Turning off AIC testing for outlier detection and regressors

By default, seas() evaluates the presence of weekday and Easter effects and checks for outliers in the data. Both can be turned off:

m_no_auto <- seas(AirPassengers, regression.aictest = NULL, outlier = NULL)
summary(m_no_auto)
#> 
#> Call:
#> seas(x = AirPassengers, regression.aictest = NULL, outlier = NULL)
#> 
#> Coefficients:
#>                   Estimate Std. Error z value Pr(>|z|)    
#> MA-Nonseasonal-01  0.40181    0.07887   5.095  3.5e-07 ***
#> MA-Seasonal-12     0.55695    0.07626   7.304  2.8e-13 ***
#> ---
#> Signif. codes:  0 '***' 0.001 '**' 0.01 '*' 0.05 '.' 0.1 ' ' 1
#> 
#> SEATS adj.  ARIMA: (0 1 1)(0 1 1)  Obs.: 144  Transform: log
#> AICc: 987.4, BIC: 995.8  QS (no seasonality in final):    0  
#> Box-Ljung (no autocorr.): 28.04   Shapiro (normality): 0.9886  
#> Messages generated by X-13:
#> Warnings:
#> - At least one visually significant trading day peak has been
#>   found in one or more of the estimated spectra.

In practice, many spec argument combinations can be extracted via the static() functions, which will be demonstrated in the next chapter. Alternatively, the seasonalview package offers a graphical user interface that allows you to click various spec argument combinations.

m <- seas(AirPassengers)
view(m)

Manipulating spec argument combinations in the seasonalview graphical user interface