- Concepts
- X-12-ARIMA
- SEATS
- Diagnostics
- Troubleshooting

Do you have questions not answered here? Please send suggestions for other questions to "faq" at catherinechhood.net.

Please also see the Seasonal Adjustment Glossary.

- What is X-12-ARIMA?
- How do I get a copy of X-12-ARIMA?
- How do I run X-12-ARIMA?
- How do I find what I need from the output file?
- How do I save output into Excel?
- How does X-12-ARIMA estimate the trend and seasonal components?
- How does X-12-ARIMA estimate the trading day and moving holiday components?
- What seasonal filters are available in X-12-ARIMA?
- What trend filters are available in X-12-ARIMA?
- How does X-12-ARIMA handle extreme values?
- What if I have a holiday not included in X-12-ARIMA?
- How do I process a large number of series?
- How do I get X-12-ARIMA to calculate an adjustment for the total of my series?
- How do I get updates and/or more information on X-12-ARIMA?
- Is there training available?
- How do I get started? How do I write all the input files I need? How do I find out about the diagnostics?
- Can I run X-12-ARIMA from Excel?
- When will X-13 be available and what will it be like?

X-12-ARIMA is a seasonal adjustment program developed at the U.S. Census Bureau. The program is based on the Bureau's earlier X-11 program and the X-11-ARIMA program developed at Statistics Canada.

Improvements in X-12-ARIMA as compared to X-11 are:

- Use of regARIMA models to
- forecast the series allowing us to use better, symmetric moving average filters that give us generally smaller revisions to the seasonal factors and
- prior-adjust for outliers, TD, and holidays

- New diagnostic tools
- Wider variety of moving average options
- A new input syntax and new output files

X-12-ARIMA is available to download for free from the US Census Bureau at the X-12-ARIMA Page.

Before running X-12-ARIMA, you need to write an input specification file. The input specification file is a text file used to specify various program options. The file must end with a file extension ".spc". An example input specification file:

series{ period = 12 title = 'Example for the FAQ' file = 'test.dat' format = 'datevalue' savelog = peaks }transform{function=log}arima{model = (0 1 1)(0 1 1)}regression{variables =(td)}outlier{ }check{ }forecast{maxlead = 24}X11{ }slidingspans{ }history{estimates=(fcst sadj sadjchng)}

X-12-ARIMA is a DOS program, but there is a Windows version available so that you don't have to go to a DOS prompt. The Windows interface will also write the input specifications files for you.

For more information on input specification files and on running X-12-ARIMA in Windows, it is very helpful to read the paper "Getting Started with X-12-ARIMA Input Files on Your PC (Windows)".

Usually X-12-ARIMA generates many files in a single run. Some of the files it can generate:

- output file
- error file
- log file
- diagnostic files
- graphics output files

The output file can be easily 50-100 pages. To help you look for some of the most important tables, we've listed some below.

- The seasonally adjusted series is in Table D 11.
- The trend-cycle is in Table D 12.
- The combined (seasonal/trading day/holiday) factors are in Table D 16.
- The seasonal factors alone are in Table D 10.

You can also save specific tables to separate files that can be read easily into other software, such as spreadsheet programs. For more details on saving files, please see the paper "Getting Started with X-12-ARIMA Input Files on Your PC (Windows)". More information on the output can be found in the paper "Getting Started with X-12-ARIMA Output".

Tables in the output file and not easy to read into other programs, such as Excel. However, the tables that X-12 saves are very easy to read into Excel and other spreadsheet/database programs.

The first step is to use the save command so X-12 will save the tables you need. The save argument's function is to cause X-12 to write the specified tables to individual files. Saved tables are stored in files in the same directory as the program output, with the same filename as the program output but with a different extension. The extension is a distinct extension of up to three characters, which also serves as the table abbreviation.

For example, if you are running the file test.spc, and you would like to
save the seasonally adjusted series, you would add the command "save=d11"
in the x11 spec. This will save the seasonally adjusted series (Table D 11)
in the file test.d11.

series{ file = "test.dat" start = 1987.jan } x11{ save = d11 }

Most save files have two columns. The columns are delimited by a tab character. Dates are in the format yyyymm (199102 is February 1991, for example). The corresponding series values are given in scientific notation. Every save file also has a two line header. An example save file for the seasonally adjusted series (Table D 11):

date test.d11 ------ ----------------------- 199101 +0.976058552530535E+01 199102 +0.124163158177601E+02 199103 +0.135365869460595E+02 199104 +0.141431150222681E+02 199105 +0.143699654679910E+02 . . .

Once these two columns are imported into a program such as Excel, it is possible to split the first column into year and month. It is also possible, of course, to have Excel display the second column in something different from scientific notation.

For a list of all the tables with their names and codes, please see the X-12-ARIMA Quick Reference (US Census Bureau, 2003). For more details on saving files, please see the paper "Getting Started with X-12-ARIMA Input Files on Your PC (Windows)".

X-12-ARIMA is an iterative procedure. For a monthly series with a multiplicative decomposition, X-12-ARIMA, very generally, uses the steps below to estimate the trend and seasonal components. (For definitions of the components, see question 6 under Definitions and Concepts.)

- X-12-ARIMA estimates a rough trend-cycle.
- It then estimates the detrended series by dividing the original series by the trend estimate.
- Using the detrended data, it estimates the seasonal component using moving average filters for each month.
- It estimates the irregular component by dividing the seasonal component into the detrended series. X-12-ARIMA uses this irregular component to detect the extreme values.
- It then estimates the preliminary seasonally adjusted series by dividing the seasonal component, corrected for extreme values, from the original series.

X-12-ARIMA repeats this process many times, getting more and more refined estimates of the trend and the seasonal factors.

Details of the procedure can be found in the book "Seasonal Adjustment with the X-11 Method" by Ladiray and Quenneville (2001).

X-12-ARIMA estimates trading day and moving holiday components as regression effects in regARIMA models. (See question 8 under Definitions and Concepts for a brief description of regARIMA models.) X-12-ARIMA adjusts the effects, if any, out of the series before it begins estimating trend and seasonal components.

The seasonal filters available in X-12-ARIMA consist of weighted averages of consecutive values within a given month or quarter. An n x m moving average is an m-term simple average taken over n consecutive sequential spans.

An example of a 3x3 filter for January 1999 (or Quarter 1, 1991) is:

1997.1 + 1998.1 + 1999.1 + 1998.1 + 1999.1 + 2000.1 + 1999.1 + 2000.1 + 2001.1 ___________________________________________ 9

An example of a 3x5 filter for January 1999 (or Quarter 1, 1999) is:

1996.1 + 1997.1 + 1998.1 + 1999.1 + 2000.1 + 1997.1 + 1998.1 + 1999.1 + 2000.1 + 2001.1 + 1998.1 + 1999.1 + 2000.1 + 2001.1 + 2002.1 _____________________________________________________________ 15

X-12-ARIMA provides the following seasonal filter options: 3x1, 3x3, 3x5, 3x9, 3x15 and stable. (A stable seasonal filter uses all the values for the particular month or quarter.) You can specify a particular seasonal filter for every month or quarter or possibly different filters in different months, or you can let X-12-ARIMA choose the filter for you.

X-12-ARIMA has built-in procedures to choose the filter length for you based on the Global Moving Seasonality Ratio (MSR) which is a measure of the average change in the irregular divided by the average change in the seasonal for the entire series. The most common choice for the seasonal filter is 3x5.

If the MSR is small, then that indicates, generally speaking, that either the irregular is small or the seasonal pattern is changing (or perhaps both). In a situation like this, X-12-ARIMA will choose a short filter (3x3) to pick up the changes in the seasonal pattern. If the MSR is large, that indicates that either the irregular is large or that the seasonal pattern is stable, or perhaps both. For a large MSR, X-12-ARIMA will choose a longer filter (3x9) to fit the more stable seasonal pattern and to be more stable in the presence of extreme values.

For more on seasonal filters, see X-12-ARIMA Reference Manual.

In X-12-ARIMA a simple 2x12 (or 2x4 for quarterly series) trend filter is used for the first rough estimate of the trend. The other trend-cycle estimates come from very complex filters known as Henderson filters. Henderson filters are designed to be able to estimate curves.

For monthly series X-12-ARIMA will choose either a 9-, a 13-, or a 23-term Henderson filter automatically, based on the I/C ratio. X-12-ARIMA chooses a 9-term Henderson filter when the I/C ratio is small to pick up the changes in the trend-cycle and chooses a 23-term filter when the I/C ratio is large so that the filter is less susceptible to extreme values. For quarterly series, X-12-ARIMA will choose either a 5-term or a 7-term Henderson filter. If you prefer, you can specify the Henderson moving average of any odd number greater than one and less than or equal to 101.

For more on trend filters, see X-12-ARIMA Reference Manual.

X-12-ARIMA has two separate procedures to handle extreme values.

If a point is a very large point outlier or a shift in the level of the series, the effect is estimated as a regression effect in the regARIMA model and prior-adjusted out of the series before the iterative procedures begin.

As part of the iterative procedure, there is another estimation of points that are
unusual and may cause problems. These points are identified by comparing the standard
deviation of the irregular to individual points of the irregular component. Any points that
are too far away from the identity (1 for multiplicative adjustments or 0 for additive adjustments)
are down-weighted. These points are called *extreme values* in the X-12-ARIMA output
(found in Table D9). This procedure would only identify point outliers, not shifts
in the level of the series as we could define with the regARIMA model.

Outliers and extreme values are adjusted out of the series when estimating the seasonal component so that they don't affect the estimate of the seasonal component. However, they are not adjusted out of the seasonally adjusted series. Point outliers and extreme values are included with the irregular component. Level shifts are included with the trend component. Because the seasonally adjusted series is the trend and irregular components together, all outliers and extreme values are included in the seasonally adjusted series.

X-12-ARIMA includes built-in regressors for Easter, Labor Day, and Thanksgiving. You can estimate other holiday effects by defining them as user-defined regressors in the regARIMA model.

There is a utility program available to help users generate user-defined regressors for holidays. A DOS version is available from the US Census Bureau, and a Windows version will be available here soon.

X-12-ARIMA allows for running a large number of series in two "batch" modes:

- multi-spec mode, where there is an input specification file for every series, and
- single-spec mod, where every series will run with the options from a single input specification file.

For production purposes, it is best to use multi-spec mode. (Single-spec mode can be useful for research purposes in particular.)

To run X-12-ARIMA on more than one series, you first have to create a file with a list of all the series you need to run. For multi-spec mode, the file is called a metafile and simply lists the input specification files to run without the .spc extension on the file names. A metafile must have the extension .mta.

The Windows Interface to X-12-ARIMA can create metafiles as well as spec files.

More information on running X-12-ARIMA in batch mode is available in the paper "Getting Started with X-12-ARIMA Input Files on Your PC (Windows)".

X-12-ARIMA is able to compute both direct and indirect adjustments of the aggregate or composite series from a set of component series. (A direct adjustment is when we combine the component series first and then adjust. An indirect adjustment is when the component series are seasonally adjusted first and then combined to get an adjustment for the total.)

There are four steps when asking X-12 to calculate a seasonal adjustment for an aggregate series:

- Create spec files for component series.
- Create a spec file for composite series.
- Create a metafile that lists the component and composite series. The spec file for the composite series is listed last in the metafile.
- Run X-12-ARIMA in batch mode.

In the spec files for the component series, we need to tell X-12 how we want the series combined with the argument "comptype". Usually we want to add the series, so we use the argument comptype=add. The comptype argument is the only change that we need to make from a usual spec file for the series.

In the spec file for the aggregate or composite series, the series spec is replaced by the composite spec. The direct seasonal adjustment of the series is controlled by the x11 spec.

composite{ title = 'Composite Example for the FAQ' }transform{function=log}arima{model = (0 1 1)(0 1 1)}regression{variables =(td)}outlier{ }check{ }forecast{maxlead = 24}X11{ }slidingspans{ }history{estimates=(fcst sadj sadjchng)}

More information on running X-12-ARIMA to get an indirect adjustment is available in the paper "Getting Started with X-12-ARIMA Input Files on Your PC (Windows)".

Brian Monsell, SRD, makes announcements of program updates through a moderated mailing list called x12a-announce. To subscribe, follow the instructions at: x12a-announce.

The US Census Bureau teaches a limited number of courses, mostly to government and nonprofit organizations.

Catherine has taught many courses over the past 8 years. A complete list of the courses available from Catherine is found on the Course List Page.

Once you've read the FAQ and the Getting Started papers (and registered for a class), you should try to run X-12-ARIMA on your own. There are several resources that can help.

The first step is to get your data in a form that X-12-ARIMA can read. If your data is in Excel files, then X-12-Data can help. For more information on X-12-ARIMA formats, please see the Getting Started paper.

The Windows Interface to X-12-ARIMA will write input specification files and metafiles for you. If you are a new user, this program will help you tremendously.

Once you've run the program, the latest version of the interface program will help you manage the diagnostics.

No. Currently there is no DLL for X-12-ARIMA to run it from Excel. However, it is possible to write Excel macros that will call X-12. If you would like more information on this, please send Catherine an email.

There is no definite word on when X-13 will be released on the Census Bureau web site, but a testing version of X-13 already exists. X-13 combines the current filters used in X-12-ARIMA with model-based adjustment similar to the program SEATS. In SEATS, the seasonal and trend filters are based on the ARIMA model. The new program will still provide access to all of X-12-ARIMA's seasonal and trend filters and diagnostics.

Page design by David Joyce at Exit 42 Design

FAQ written by Catherine C.H. Hood

with help from Lynn Imel, Kathy McDonald-Johnson, David Findley, Brian Monsell, and James Ashley

Copyright 2006-2012

Last modified: 5 Jan 2012