U.S. Department of Commerce

X-13ARIMA-SEATS Seasonal Adjustment Program

You are here: Census.govSubjects A to ZX-13ARIMA-SEATSWin X-13 & X-13-Data › Win X-13 Documentation
Skip top of page navigation

Win X-13 Version 2.2: A Windows Interface for X-13ARIMA-SEATS

Demetra Lytras
U.S. Census Bureau
June 28, 2013

1. Introduction

Win X-13 is a Windows interface for X-13ARIMA-SEATS (U.S. Census Bureau 2013).

This interface will:

  • Create the input files necessary for seasonally adjusting a series with X-13ARIMA-SEATS.
  • Run X-13ARIMA-SEATS and display the output files.
  • Create a data table with model information and diagnostics from series run in X-13ARIMA-SEATS.
  • Create graphs from X-13ARIMA-SEATS output.

Licensing information for this software can be found at http://www.census.gov/srd/www/disclaimer.html.


Return to index.


2. Requirements

Win X-13 has been tested on Windows XP, Windows Vista, and Windows 7. The program requires that the .NET Framework 2.0 be installed on the computer. It can be downloaded at http://www.microsoft.com/en-us/download/details.aspx?id=1639. Link to a non-federal Web site

Win X-13 was designed to run X-13ARIMA-SEATS and X-12-ARIMA Version 0.3. Not all features will work if using previous versions of X-12-ARIMA. Win X-13 does not support the HTML converter used to convert output files to HTML in the X-12-ARIMA program.

The interface can produce graphs in Java and in SAS. To produce the Java graphs, Java 1.6 or higher must be installed on your computer. You can download the latest version of Java at java.sun.com. Link to a non-federal Web site To create graphs in SAS you must have SAS Version 8 or higher and the program X-13-Graph Batch Version 2.0, which is available at http://www.census.gov/srd/www/x13graph/ (U.S. Census Bureau 2012).


Return to index.


3. Setup

Settings Window

Double click on WinX13.exe to start the Windows interface. The first time this program is run, a Settings window will appear. The X-13ARIMA-SEATS Executable must be set before the interface is run; all other settings are optional.

Win X-13 Settings

X-13ARIMA-SEATS executable: Enter the full path and filename, including the .exe extension, of the X-13ARIMA-SEATS executable. This is usually called x13as.exe or x13ashtml.exe; the first produces text output files and the latter produces HTML output. If you've downloaded a version of Win X-13 which comes bundled with X-13ARIMA-SEATS, both programs will be found in the program's /x13as subdirectory.

Initial directory: Enter the directory containing your X-13ARIMA-SEATS input files. When Win X-13 is started, the folder browser on the main screen will point to this directory. By default, this control points to the Desktop.

Type of graph to create when run in graphics mode: When a spec file is run with X-13ARIMA-SEATS in graphics mode, Win X-13 can create graphs from the series. If "Win X-13 Java graphs" is selected, these graphs will be created using Java. This requires Java 1.6 or higher. Select "X-13-Graph SAS graphs" to create these graphs using the X-13-Graph SAS program. This requires that both SAS Version 8 or higher and the X-13-Graph Batch program, Version 2.0, are installed on your computer. Enter the path of the latter program in the X-13-Graph program directory text box. If "None" is selected, no graphs will be created when a spec file is run in graphics mode. However, the graphics files will still be saved, so you can create graphs later.

Default graphics path: Enter the directory to which graphics files should be saved when X-13ARIMA-SEATS is run in graphics mode.

Program for opening text files: Check the Use default viewer box to open input and text output files within Win X-13. Note that when using the default viewer all open files will be closed when Win X-13 is closed. To open and edit text files in an alternate text editor, deselect the Use default viewer box and enter the full path and filename of the program's executable in the text box. (For example, the program Notepad can be found in C:\Windows\notepad.exe.)

Select the output files to view when X-13ARIMA-SEATS is run: If you use the default viewer and the text output version of X-13ARIMA-SEATS, all four output files will open. If you use an alternate text editor or the HTML version of X-13A-S, then check the boxes of the output files you want to see. Output file types are described in Section 4 and Section 5 of this document.

Add time to X-13 run to compensate for network drive time discrepancies: You will likely not have to use this. If your data is on a network drive and the output files or the diagnostics window is not showing up after you run a spec file, it might be because the timestamp on files written to the network drive is not in sync with that of the C drive. In this case, checking the box and selecting a number greater than the number of seconds of discrepancy can fix the problem.

Press Save to save the settings and return to the main screen. To access this window again, go to File -> Settings.


Return to index.


4. Win X-13 Main Screen

Win X13 main screen

Use the Win X-13 main screen to open and run X-13ARIMA-SEATS input files and open the output files, set the options for running X-13ARIMA-SEATS, and select the output to view when a spec file is run.

Input Files: Running X-13ARIMA-SEATS

The three types of X-13ARIMA-SEATS input files are spec files, metafiles, and data metafiles. A spec file contains the instructions for adjusting a series. These files, which have a .spc extension, are described in Section 6. You can adjust more than one series during one X-13ARIMA-SEATS run using a metafile, which is a list of spec files, or a data metafile, which is a list of data files to be run using one spec file. These files have extensions .mta and .dta respectively, and are described in Section 7.

To run X-13ARIMA-SEATS, use the folder browser in the top left to locate the folder containing the spec file or metafile. All X-13ARIMA-SEATS input files will be shown in the input list box. Use the drop-down box to filter the input files. To open the file FileName.ext for viewing or editing before running it, select the file and press Ctrl+O, or select View -> View FileName.ext from the menu. To run X-13ARIMA-SEATS, select the spec file, metafile, or data metafile, and press the Run button or Ctrl+R. If you are running a data metafile, a new screen will appear prompting you to choose the spec file corresponding to the data files listed in the metafile.

X-13ARIMA-SEATS Output Files

There are two versions of X-13A-S; one produces text output and the other accessible HTML output. When X-13ARIMA-SEATS is run, a number of output files can be created. These generally have the same name (or base name) as the spec file or metafile, unless an alternate output name is specified, but have extensions (in the text output X-13A-S) or suffixes (in the HTML output X-13A-S) based on the file type. Use the View Output Files drop-down box to filter the output files by type. All files in the directory of that type will appear in the list box; double click on the file you would like to open, or select it and use the View menu to open it.

The output file types are:

  • Output file. The main output file created when X-13ARIMA-SEATS is run. The information saved to the OutputName.out or OutputName.html file can be controlled using print arguments in the spec file; see the X-13ARIMA-SEATS documentation (U.S. Census Bureau 2013) for a complete description.
  • Log file. A supplementary output file created when X-13ARIMA-SEATS is run, the log file displays the diagnostics requested in the spec file using savelog arguments. See the X-13ARIMA-SEATS documentation (U.S. Census Bureau 2013) for a complete list of savelog arguments available. Log files are named either OutputName.log or OutputName_log.html.
  • Error file. X-13ARIMA-SEATS creates an error file for every series run. When it encounters an error, it saves a description of the error to an OutputName.err or OutputName_err.html file.
  • Diagnostics file. If X-13ARIMA-SEATS is run in summary mode (by checking Create summary file with diagnostics information) or graphics mode, an OutputName.udg file is created. This is a text file in both versions of X-13A-S. See Section 8 for more details.
  • Save files. These are text files in x12save format of specific tables from the X-13A-S run. Each save file must be requested in the spec file using the save = () argument; their extension is the two or three letter code corresponding to that table. For example, save = (d16) in the x11{} spec will save the combined seasonal factors to OutputName.d16.

Runtime Options

Graphics mode: When the Run in graphics mode box is checked, X-13ARIMA-SEATS saves graphics files to the path given in the Graphics directory box.  If "Win X-13 Java graphs" or "X-13-Graph SAS graphs" is selected as the Type of graph to create when run in graphics mode in the Settings window, then the interface will produce these graphs when a spec file is run. See Sections 5D and 5E for more information on the graphs. The graphics files that are saved can also be used to create graphs later; the SAS program X-13-Graph has a large number of graphs and graphing options available for this purpose.

Alternate output name: Check the New name for spec output box to specify an alternate name for all program output. (This includes the log file, the output file, and all graphics files and saved tables.)

To save the output files to a directory other than the one to which the spec file is located, check the Output directory box and type the new directory in the text box next to it.

Save original, trend, seasonal adjustment, and seasonal factors as HTML: When this box is checked, up to four HTML files will be created when a spec or metafile is run, saving the original series, trend (D12 table), seasonally adjusted series (D11 table), and the combined seasonal factors and calendar effects (D16 table) to the output directory. See Section 5F for more details.

Summary mode: Check Create summary file with diagnostics information or run X-13ARIMA-SEATS in graphics mode to create the diagnostics file (*.udg file) when a spec or metafile is run. The diagnostics file is saved to the graphics directory if Run in graphics mode is checked, or to the output directory if it is not. If neither box is checked, the diagnostics table will not be created when the spec is run.

Verify spec: When this box is checked, the spec file is checked for errors when it is run. Any errors found are printed to the "Screen Output" tab of the Output screen. No further processing of the spec is done.

Advanced Options window

Advanced Options: Further X-13ARIMA-SEATS options are available by pressing the Advanced options button. In the window that appears, you can:
-Suppress all output except for tables specifically requested in the spec file
-Turn off pagination in the output file
-Request a wide format in the output
-Ask for reduced output
-Run X-13ARIMA-SEATS in quiet mode, suppressing warnings sent to the console and printed to the "Screen Output" tab
-Sum components of a composite adjustment but adjust only the total

Win X-13 maintains the status of the check boxes--that is, the boxes that had been checked in the previous run of the program will be checked the next time the interface is started. The exceptions are the boxes for the new output name and directory; these have to be checked anew every time you use them.

Displaying X-13ARIMA-SEATS Output

Check the Output files box to display the log, output, and/or error files when a spec or metafile is run. The actual files shown will depend on what you have selected in the Settings window. See Sections 5A and 5B for details.

Check the Diagnostics box to display summary information from the spec file(s) processed in a data table. See Section 5C for details.


Return to index.


5. Program Output

A. Text Output

output file window

When a spec file or metafile is run, the text output is, by default, shown in a window with four tabs. The first tab shows the log file, containing the information requested in the spec file with savelog arguments. The second tab shows the output file, and the third tab the screen output, which shows warning and error messages. The fourth tab lists all other text output files with the same output name that were created at the same time as the output; among these is the error file, which will list any errors X-13A-S encountered when running the spec file, and all files requested with save arguments in the spec file.

If a metafile was run, there will be only one log file, but each spec file will have its own output file. These output files can be accessed on the Output tab using the drop-down box.

If an alternate Program for opening text files was provided in the Settings window, the log file, error file, and screen output will be opened in that editor. If a spec file is run, the output file will also be opened; the output files will not be opened if a metafile is run. To limit which of these four files is opened when a spec is run, use the appropriate check boxes in the Settings window.

B. HTML Output

When a spec file with output name OutputName is run with the accessible HTML version of X-13A-S, the following HTML files are created:

  • OutputName.html: The output file
  • OutputName_log.html: The log file
  • OutputName_err.html: The error file

If a metafile (.mta) or data metafile (.dta) is run, one additional files will be produced:

  • MetafileName_mta.html or DataMetafileName_dta.html: An index linking to all output, log, and error files from the series in the run

The specific files displayed when X-13ARIMA-SEATS is run depend on what you've selected in the Settings screen. The screen output can also be shown; however, this will always be a text file and will open in either Win X-13's default viewer or the alternate text viewer selected in the Settings window.

C. Diagnostics Tables

Diagnostics window

When the Diagnostics box on the main screen is checked, Win X-13 produces a Diagnostics screen containing model information and diagnostics. The following tables describe the information contained in the six tabs of the Diagnostics screen. These tables are also available from within the Diagnostics screen by clicking on Diagnostics List from the Help menu.

"General" Data Table
Column Heading Column Description
Series Name Name of series. This is the name argument in the series spec, if given, or the name of the output files otherwise.
View Spec File Press the button to show the spec file that was used to adjust the series. Only works if the row was added automatically when the series was run.
FilenameName of the output files
Period Number of observations per year.
Transform Transformation. Includes "**" if the transformation was automatically selected.
Mode Seasonal adjustment mode. Includes "**" if the mode was automatically selected.
Span Span of data adjusted.
Outlier Span Span of data checked for outliers.
AO/LS/TC Crit Val Critical |t| values for additive outliers, level shifts, and temporary changes, separated by a slash. "*" indicates it was chosen by X-13ARIMA-SEATS; "--" indicates this type of outlier was not searched for.
# Outliers Number of hard-coded and automatically selected outliers.
# Auto Number of outliers automatically selected.
# Iter Number of iterations to reach convergence. If the maximum number of iterations was changed from the default (1500), the cell will also show an "m". If the convergence tolerance was changed from the default (0.00001), the cell will also contain a "t".
# Forecasts Number of forecasted values.
Forecast mode Indicates whether forecasts are within sample or out of sample.

"Model Info" Data Table
Column Heading Column Description
Series Name Name of series.
Model Span Span of data used to estimate regARIMA model coefficients.
ARIMA Model ARIMA model; "**" indicates the model was selected automatically by the program.
Regressors The regressors included in the model.
Trading Day Trading day regressors included, with t-values if only one regressor and p-values of the chi-squared test of groups of regressors if multiple regressors; "**" indicates trading day was included based on results of AIC test.
Holiday Easter, Thanksgiving, or Labor Day regressors (with their t-values) included; "**" indicates Easter was included based on results of AIC test.
Seasonal Seasonal or trigonometric seasonal regressors included, with the p-value of the chi-squared test.
Constant Gives the t-value of the constant, if it is included.
User Gives t-values of user defined regressors included, and p-value of the chi-squared test of the group of regressors, if there is more than one; "**" indicates user regressors are included based on results of AIC test.
Coded Outliers The outliers hard-coded in the spec file, with their t-values.
Auto Outliers The outliers automatically found, with their t-values.
Variance Innovation variance of the ARIMA model.
Phi1 Estimate of nonseasonal AR parameter at lag 1.
Sum NS AR Sum of all nonseasonal AR parameter estimates.
Theta1 Estimate of nonseasonal MA parameter at lag 1.
Sum NS MA Sum of all nonseasonal MA parameter estimates.
Sum Seas AR Sum of all seasonal AR parameter estimates.
Sum Seas MA Sum of all seasonal MA parameter estimates.

"Model Diagnostics" Data Table
Column Heading Column Description
Series Name Name of series.
AICC F-adjusted Akaike's Information Criterion (corrected for sample size).
aa FcE (3-yr) Average absolute percentage error of forecasts in the last three years. An average of the 1-step ahead to 12-step ahead (4-step ahead for quarterly series) forecasts of the data with one, two and three years removed. By default, this is calculated using within-sample forecasts, but it can be done with out-of-sample forecasts if requested.
Normal? Indicates whether residuals pass normality tests.
# LBQ Fail Number of the lags from 1 to 24 with significant Ljung-Box Q statistic.
Sig LBQ List of lags with significant LBQ.
Sig Seas LBQ Seasonal lags with significant LBQ.
# BPQ Fail Number of the lags from 1 to 24 with significant Box-Pierce Q statistic.
Sig BPQ List of lags with significant BPQ.
Sig Seas BPQ Seasonal lags with significant BPQ.
Sig ACF Lags with significant autocorrelation in the residuals.
Sig Seas ACF Seasonal lags with significant autocorrelation in the residuals.
Sig PACF Lags with significant partial autocorrelation in the residuals.
Sig Seas PACF Seasonal lags with significant partial autocorrelation in the residuals.
Resid Peaks Indicates the visually significant seasonal and trading day peaks in the spectrum of the model residuals.
QS Residuals QS statistic of the residuals.
QSS Residuals QS statistic of the residuals on the last 96 observations (8 years for a monthly series).

"x11" Data Table
Column Heading Column Description
Series Name Name of series.
Sigma Lim Lower and upper sigma limits for downweighting extreme values.
Seasonal MA Seasonal moving average filter; "**" indicates the filter was chosen by X-13ARIMA-SEATS.
Trend MA Length of the final Henderson trend filter; "**" indicates the filter was chosen by X-13ARIMA-SEATS.
I/S Ratio The final irregular/seasonal Ratio from Table D10; also called the global moving seasonality ratio.
I/C Ratio The final irregular/trend ratio from Table D12.
D8F F-statistic of test for seasonality assuming stability from D8 table.
D8F p-val p-value of D8 F statistic.
D11F p-value of D11 F statistic for residual seasonality.
D11F 3 yr p-value of D11 F statistic for residual seasonality in the last three years.
M1 The relative contribution of the irregular over three months span.
M2 The relative contribution of the irregular component to the stationary portion of the variance.
M3 The amount of period-to-period change in the irregular component as compared to the amount of period-to- period change in the trend-cycle.
M4 The amount of autocorrelation in the irregular as described by the average duration of run.
M5 The number of months it takes the change in the trend-cycle to surpass the amount of change in the irregular.
M6 The amount of year-to-year change in the irregular as compared to the amount of year-to-year change in the seasonal.
M7 The amount of moving seasonality present relative to the amount of stable seasonality.
M8 The size of the fluctuations in the seasonal component throughout the whole series.
M9 The average linear movement in the seasonal component.
M10 As M8, calculated for recent years only.
M11 As M9, calculated for recent years only.
Q A weighted average of M1-M11.
Q2 A weighted average of M1-M11 without M2.
MCD Months for Cyclical Dominance
"Spectrum & QS" Data Table
Column Heading Column Description
Series Name Name of series.
SAdj Peaks Indicates the visually significant seasonal and trading day peaks in the spectrum of the seasonally adjusted series.
Irr Peaks Indicates the visually significant seasonal and trading day peaks in the spectrum of the modified irregular.
Resid Peaks Indicates the visually significant seasonal and trading day peaks in the spectrum of the model residuals.
Ori Peaks Indicates the visually significant seasonal and trading day peaks in the spectrum of the (possibly differenced, transformed, prior-adjusted) original series.
Nonsig Seasonal Peaks Indicates whether there is a nonsignificant peak at any of S1, S2, S3, or S4 in the spectrum of the seasonally adjusted series ("sadj"), irregular ("irr"), or residuals ("rsd"). Also gives the height in stars of the tallest of these peaks.
Nonsig TD Peaks Indicates whether there is a nonsignificant peak at T1 in the spectrum of the seasonally adjusted series ("sadj"), irregular ("irr"), or residuals ("rsd"). Also gives the height in stars of the tallest of these peaks.
QS Sadj QS statistic of the seasonally adjusted series.
QSS Sadj QS statistic of the seasonally adjusted series calculated using the spectrum span.
QS Sadj Adj Ext QS statistic of the seasonally adjusted series adjusted for extreme values.
QSS Sadj Adj Ext QS statistic of the seasonally adjusted series adjusted for extreme values calculated using the spectrum span.
QS Irr QS statistic of the irregular component.
QSS Irr QS statistic of the irregular component calculated using the spectrum span.
QS Irr Adj Ext QS statistic of the irregular component adjusted for extreme values.
QSS Irr Adj Ext QS statistic of the irregular component adjusted for extreme values calculated using the spectrum span.
QS Ori QS statistic of the original series.
QSS Ori QS statistic of the original series calculated using the spectrum span.
QS Ori Adj Ext QS statistic of the original series adjusted for extreme values.
QSS Ori Adj Ext QS statistic of the original series adjusted for extreme values calculated using the spectrum span.

"Stability Diagnostics" Data Table
Column Heading Column Description
Series Name Name of series.
Rev Span Span of data of revision history analysis.
SA.AAR Average absolute percent revisions of the seasonal adjustments.
MM.AAR Average absolute revision of the month-to-month percent change of the adjustments.
#Spans Number of spans for sliding spans analysis.
Span Length Length of each span.
SF Cut Threshold value for the seasonal factors.
SF75p 75th percentile of maximum percent differences across spans of seasonal factors.
SF% Percent of months (quarters) with a maximum absolute percent change of the seasonal factors greater than the threshold.
SA Cut Threshold value for the seasonal adjustment values.
SA75p 75th percentile of maximum percent differences across spans of the seasonally adjusted series.
SA% Percent of months (quarters) with a maximum absolute percent change of the seasonal adjustment values greater than the threshold.
MM Cut Threshold value for the period-to-period percent change in the seasonally adjusted series.
MM60p 60th percentile of maximum percent differences across spans of period-to-period changes in the seasonally adjusted series.
MM% Percent of months (quarters) with a maximum absolute difference of period-to-period change in the seasonally adjusted series greater than the threshold.
TD Cut Threshold value for trading day factors.
TD75p 75th percentile of maximum percent differences across spans of trading day factors.
TD% Percent of months (quarters) with a maximum absolute percent change of the trading day factors greater than the threshold.
YY Cut Threshold value for the year-to-year change in the seasonally adjusted series.
YY90p 90th percentile of maximum percent differences across spans of year-to-year changes in the seasonally adjusted series.
YY% Percent of months (quarters) with a maximum absolute difference of year-to-year change in the seasonally adjusted series greater than the threshold.

window for removing columns and changing the column order

You can change the columns displayed in the diagnostics table by selecting Select Columns to View from the File menu.

The table must have six tabs (though some can be empty). The names of these tabs are in the box to the top left. To rename a tab, select it from the list. Then type the new name in the Rename tab box, and press the Okay button directly below it.

The list box in the middle shows the columns currently in that tab. To move a column in that tab, select the column(s) and press the up and down arrow buttons at the top right. To remove column(s) so that they are not displayed at all, select them and press the Remove button. (Removed columns can be found under Columns not to display in the tab list, if you'd like to add them back into the table.) To move column(s), select them and press the Move to... button; a menu of the available tabs will appear, and you can select the tab to which the columns should be moved.

Alternately, you can move columns up or down, move columns to another tab, or remove columns by selecting the columns and pressing the right click button on your mouse; the available options for those columns will appear.

In the first tab, named General by default, the View Spec column can be displayed. This column is a list of buttons; pressing the button displays a copy of the spec that was run to get the displayed diagnostics. This column cannot be moved; if it is in the diagnostics table, it must be the first column in the first tab. It can, however, be removed by deselecting the Include the 'View Spec' column check box.

Once you've reordered the columns, Win X-13 will always remember the new order and display your diagnostics table using this order. To return to the original column order, press the Return to Default Order button.

window for changing diagnostic table colors and fonts

Win X-13 can flag rows which fail certain diagnostics. To choose the appearance of these flagged series, select Table Styles from the File menu. From the window which appears, you can choose the background color and text color of the row containing a failed or warned diagnostic. Fonts can be set seperately for cells containing failed diagnostics, cells containing warnings, and all other cells.

When saving a table as HTML, the colors marking the failed and warned rows will also be saved if you choose Save Table With Formatting from the File menu. Customized cell styles will not be saved; all failed cells will be bold and all warned cells will be italicized. To save the table without any flags, select Save Table - Values Only from the File menu.

window for choosing diagnostic warning threshholds

Selecting Failure/Warning Threshholds from the File menu will open a window which allows you to choose the diagnostics warned against. Note that only the diagnostics currently displayed will be used to determine whether a row fails or needs warning. For example, if a series has significant spectral peaks but the columns reporting spectrum information have been removed from the diagnostics table, the row will not be failed. For more information on X-13ARIMA-SEATS's diagnostics, see the X-13ARIMA-SEATS Reference Manual (U.S. Census Bureau 2013).

Win X-13 remembers the selections made for Table Styles and Diagnostic Threshholds. Once the selections are made, they will always be used when Win X-13 is run.

D. Java Graphs

If "Win X-13 Java graphs" is selected in the Settings window as the Type of graph to create when run in graphics mode, and the box for running in graphics mode is checked on the main screen, then a new graph window will appear whenever a spec file is run. This window will contain up to 10 graphs, depending on the options requested in the spec file. These graphs are:

  • Original Series
  • Logs of the Original Series
  • Overlay Graph of the Original Series, Seasonally Adjusted Series, and Trend
  • Spectrum of the Original Series
  • Spectrum of the RegARIMA Residuals
  • Spectrum of the Seasonally Adjusted Series
  • Spectrum of the Irregular
  • Seasonal Factors by Period
  • Seasonal Factors and SI Ratios by Period
  • ACF and PACF of the Residuals

If you right-click on any individual graph, a menu will appear allowing you to save the graph as a .png file, print the graph, or adjust certain graph properties, such as changing some of the graph colors or the title. For most graphs, the menu will also offer you zooming options. An alternative method to zoom in on a portion of the graph is to move the mouse to the upper left-hand point of the region you would like to view, press the left mouse button, and, while keeping the button pressed, move the mouse to the lower right-hand point of the region. When you release the mouse button, the graph should zoom in to that region. Zoom back out by repeating the procedure, but rather than moving the mouse down and to the right while the button is depressed, move it in any other direction.

If a metafile is run, a new window will appear containing a list of the series contained in the metafile. Select one or more series from the list and press Graph to create these graphs for the series. (Note that a new window will appear for each series.)

E. SAS Graphs

If "X-13-Graph SAS graphs" is selected in the Settings window as the Type of graph to create when run in graphics mode, and the box for running in graphics mode is checked on the main screen, then when a spec file is run, Win X-13 will attempt to start SAS and run the X-13-Graph program to create the ten graphs listed above. If a metafile is run, a new window will appear containing a list of the series contained in the metafile. Select one or more series from the list and press Graph to create these graphs for the series.

If the interface encounters a problem starting SAS, it will instead open the SAS program, which is saved as x13graph.sas in the /appl subdirectory of the X-13-Graph program directory. Run this program manually to create the graphs.

F. HTML Tables of Original Series, Trend, Seasonally Adjusted Series, and Seasonal Factors

If the box requesting the original series, trend, seasonally adjusted series, and seasonal factors be saved as HTML is checked, then up to four HTML files will be created when a spec or metafile is run. These files, called OutputName_Original.html, OutputName_Trend.html, OutputName_SeasAdjSeries.html, and OutputName_SeasonalFactors.html, where OutputName is the output name of the spec file or metafile, will be saved in the same directory as the output file. The original series file will always be created; the other three will be created if seasonal adjustment is successfully completed. The files correspond to output tables A1, D12, D11, and D16, respectively, of an X11 seasonal adjustment or tables A1, S12, S11, and S16 of a SEATS adjustment.


Return to index.


6. Creating New Spec Files

window for creating new spec files

To create a new spec file for your data file, select Create -> Spec file from the menu. In the window that appears, the only options that need to be specified are the data file, the data file format, and the period. Pressing Create Spec will then write a spec file customized to your data with:

  • The span and model span encompassing all the data in the file
  • The data checked for a log transformation and the result hard-coded
  • The series checked for flow trading day and Easter and the results hard-coded
  • The entire series checked for additive outliers and level shifts and the results hard-coded
  • An ARIMA model selected automatically and hard-coded
  • One year of forecasts
  • An X-11 seasonal adjustment with the seasonal filter hard-coded based on the global moving seasonality ratio from the initial run
  • Sliding spans and history diagnostics with default settings

Alternately, you can customize these options, specify a prior adjustment file or user regressor, and add metadata to your diagnostics file using the seven tabs in this window.

Customizing Spec Options

Customize Spec Arguments Window

X-13A-S spec files have many more options available than those displayed on the seven tabs of this interface. For some of these options (mostly pertaining to diagnostics to be saved to the log file), default options were chosen; others were not set at all. All X-13A-S spec arguments can be set by going to Customize spec arguments in the File menu. The two rows of tabs along the top each represent one spec. The arguments available for this spec are listed in the Argument drop down box, and are all described in Chapter 7 of the documentation for X-13ARIMA-SEATS (U.S. Census Burea 2013). Select an argument, type the value into the "Value" box, and press "Add." If the argument already has a value, you will be asked if you would like to replace it. Once you have set all the arguments you want, press "OK." Note that if an argument can be set using the controls in the seven tabs of the Create Spec window, the argument will not be listed in this Window.

The arguments you set will be used to create the spec file. If you want Win X-13 to remember these arguments, save them as a template.

Templates are a way to set your own default selections in this Create Spec process. They're simple to use. First, edit the spec arguments as described above. Then select your preferred settings in the seven tabs of the Create Spec window. Select Save Current Settings as New Template from the File menu. In the window that appears, name the template holding your new settings. If you check the box making these settings the default, then when you select Create spec from the Main screen, this window will appear with your custom settings. If you don't want your new template to be the default, you can uncheck the box. You can still create a new spec using this template by choosing Create spec from template and then selecting the appropriate template.

To return to the program's default settings, simply clear your default template by selecting Clear Saved Default Settings and Spec Arguments from the File menu. To update a template with new arguments, make the required changes and select Save Current Settings from the File menu.

Additional Spec Creation Options

Win X-13 can create a spec for for each series listed in a data metafile. To do this, specify the data metafile where the Data File or Data Metafile is requested in the Data tab. You can also specify a metafile; however, as metafiles do not supply the extension of the data file, Win X-13 looks first for a file with a .dat extension, and if one is not found, for a file with a .txt extension. If your data files have another extension, use a data metafile to create the spec files. If the data file cannot be found, a default spec file with no data file will be created.

Win X-13 can also create a parent spec file for a composite adjustment and a spec file to be run with a data metafile.

Data File Formats

You must specify the format of your data file. X-13ARIMA-SEATS reads data from text files, generally with a .dat or .txt extension. The data can be in any of the following formats:

  • Datevalue: The file contains three columns- the year, the month (as a number) or quarter, and the data value.
  • Free: The file contains just the data separated by one or more spaces or tabs or a new line. To use this format, you must also provide the date of the first data point and the period.
  • x12save: The format X-13ARIMA-SEATS uses to save data files. Use this format when using an X-13ARIMA-SEATS output file as the input file.
  • tramo: The format the programs TRAMO and SEATS use to input data.
  • 1L, 2L, 1R, 2R: Data formats originally used in X-11 and X-11-ARIMA. To use these formats, the name specified in the file must be provided.
  • Fortran: A valid Fortran format, to be specified in the Fortran text box with opening and closing parantheses.

X-13ARIMA-SEATS Dates

Dates in X-13ARIMA-SEATS spec files must be in yyyy.mmm, yyyy.mm, or yyyy.q format. The date March 2008 would thus be either 2008.mar, 2008.03, or 2008.3; first quarter 2008 would be 2008.1.

Data Tab

New Spec Window's Data Tab

Use the Data tab to choose the type of spec file to create, to specify the data file and the location to which to save the spec file, and to set some series options.

Create individual spec files for each series: Check this box if you have a data file or data metafile, and want to create a spec file customized for each data file.

In the Data file or data metafile box, enter the full path and filename of the data file, metafile, or data metafile. Once a data file is entered in the box, you can open the file by choosing View -> Data from the menu, or pressing Ctrl+D.

Enter the Name of new spec file in the specified box if you are creating a single spec file. If you are creating spec files from a data metafile, the individual specs will have the same filename as the data files, unless the Use alternate output name in metafile as the new spec name box is checked. Then the interface looks for an alternate name for the spec file, and possibly an alternate directory to which to save the spec file, in the data metafile. This name must follow the data file name and extension on the same line.

Unless an alternate directory is specified in the data metafile, the spec file(s) will be saved to the directory containing the data file. If you wish to later move the spec files to their own directory, checking the box to Include the full path of the data file in the spec is necessary so X-13ARIMA-SEATS can find the data.

Create a single spec to adjust all series in a data metafile: Check this box to create a spec that can be used to run a data metafile. This spec will not reference a data file, and will disregard all requests on subsequent tabs to hard-code results.

Enter the full path and file name of the spec file to be created in the Save new spec file as: box.

Create a parent spec for a composite adjustment: Check this box to create a spec file specifying the options for the direct adjustment of a composite run.

Enter the full path and file name of the spec file to be created in the Save new spec file as: box.

Title: Enter a title for the spec. This is optional; if specified, it will be used on each page of the program output, and as the title for any graphs created.

If you are creating multiple spec files from a metafile, you can enter a title for each individual series by pressing the Title Options button. In the window which appears, you can select to not specify a title, to use the same title for all spec files, to create an individual title for each series by incorporating the series' name into a base title, or to specify a file containing the titles for the series in the metafile.

Format: The format of the data file. See Data File Formats for more details.

Period: Choose "12" for monthly data, "4" for quarterly data, and "1" for annual data.

Span start and Span end: By default, all data in the data file will be analyzed. Use these two boxes to limit the data used. If only the span start is specified, all data from this date to the end will be used. Similarly, if only the span end is specified, all data from the beginning until this date will be used. Dates must be in yyyy.mm or yyyy.q format.

Model span start and Model span end: By default, all data in the span will be used for regARIMA model calculations. Use these two boxes to limit the data used to estimate the regARIMA model. If only the span start is specified, all data from this date to the end will be used. Similarly, if only the span end is specified, all data from the beginning until this date will be used. Dates must be in yyyy.mm or yyyy.q format.

Prior Adjustments Tab

Prior Adjustments tab

Use this tab to specify the transformation, regression variables, and outlier tests.

Transformation: Choose whether or not the data should be log transformed. Select Auto to let X-13ARIMA-SEATS decide using an AIC test. (See Section 7.16 of the X-13ARIMA-SEATS documentation for details of this test.) If the Hard-code transformation box is checked, X-13ARIMA-SEATS will run to check for this transformation and write your spec file with the result.

Regression: Trading day and Easter have different regression variables for flow series than for stock series. If your series is a stock or inventory series, check the This is a stock series box to use the stock version of these variables. Otherwise, the flow series version will be used. (Note that X-13ARIMA-SEATS Version 0.3 does not have a stock Easter variable--later versions of the program will.)

X-13ARIMA-SEATS can perform AIC Tests for trading day effects and Easter. By default, checking the TD box will test for six-coefficient trading day if the series is a flow series. For stock series, the variable tested by default is end-of-month stock trading day. If the inventory is taken on another day, check the Flow Trading Day box below and specify the day in the drop down box that appears.

To test for another trading day regressor available in X-13ARIMA-SEATS, check the TD box and specify the variable in the Other Variables box.

By default, checking the Easter AIC Test box tests for Easter with a one-, eight-, and 15- day window. To test only one of these, also check the Regression Variables Easter box, and specify the window in the drop-down box.

Checking the Hard-code AIC results box will run X-13ARIMA-SEATS with the AIC tests selected, and then write your spec file with the results.

To include flow trading day, stock trading day, a constant, or an Easter effect, check the appropriate boxes. Any other regression variable available in X-13ARIMA-SEATS can be written into the Other variables box. See Section 7.13 of the X-13ARIMA-SEATS documentation for a complete list and description of these regressors.

Outliers: X-13ARIMA-SEATS can look for additive outliers, level shifts, and temporary change outliers. Check the AO, LS, or TC box to search for each type. If Hard-code outliers is checked, X-13ARIMA-SEATS will run, and any outliers found will be written into the regression spec of your spec file.

LS run: Choosing a value greater than one from the drop-down box will request that any successive run of up to that many level shifts be tested as to whether it is a temporary level shift. A table with these results will be printed to the output file.

Span start and Span end: By default, the entire span of data specified in the model span will be searched for outliers. Use these boxes to shorten this span. Dates must be in yyyy.mm or yyyy.q format.

Prior Adj File Tab

Prior Adjustment File tab

You can use this tab to specify a file of prior adjustments.

Prior adjustment file: Enter the full path and file name of the prior adjustment file. This file can then be viewed by choosing View -> Prior Adjustment File from the menu, or pressing Ctrl+A.

Format: Specify the format of the prior adjustment file. See Data File Formats for details.

Mode: Specify whether the factors are percents or ratios, to be divided out of the series, or values to be subtracted from the original series. Ratios or percent factors can only be used with log-transformed data, and subtracted factors with no transformation. The program will choose the transformation for the series based on the Mode selected here, ignoring your transformation choice on the Prior Adjustments tab.

ARIMA Model Tab

ARIMA model tab

Use the ARIMA Model tab to set the ARIMA model or ask X-13ARIMA-SEATS to automatically find the model, to request ACF and PACF plots of the original series for model identification purposes, and to set the number of forecasts.

Select model automatically: If the Hard-code automodel selection box is checked, X-13ARIMA-SEATS will be run with the automatic modeling (automdl{}) spec with default settings, and your spec file will be written indicating the model chosen. Otherwise, the spec file will be written with the automdl{} spec. See Section 7.2 of the X-13ARIMA-SEATS documentation for details on this procedure.

Use ARIMA model specified: To specify an ARIMA model for your spec file, enter it into the ARIMA model box.

Identify model using ACF and PACF plots: Check the Identify model box and select one or more differences and seasonal differences from the list boxes to create an ACF and PACF plot of each combination of difference and seasonal difference selected.

Forecasts: Choose how many years of forecasts to create. Choosing Half filter length will forecast for half the length of the seasonal filter, if either the filter or "Hard-code Global MSR" is selected on the Seasonal Adjustment tab; otherwise, one year of forecasts will be produced.

User Regressors Tab

User Regressors tab

Use this tab to input a user-defined regressor from a data set.

Data file: Enter the data file containing the user regressors. Only one file can be specified, but it can contain up to 52 regressors. To view the file, choose View -> User Regressors from the menu, or press Ctrl+R.

Format: Specify the format of the user regressor file. See Data File Formats for details. If the file contains more than one user regressor, give the value for each regressor for a date before moving on to the next date. That is, in the "Datevalue" format, the file should contain a column for the year, one for the month, and then a column for each user regressor for that date.

How many regressors are in the file?: Choose the number of user regressors in the file.

Name and Type: Each user regressor can have a name and type specified. By default, the name is "user#", and the type "user." To change these for a regressor, select that regressor from the list box. Type the new name into the Name box, and choose the type from the drop-down box. You must press Update to save these changes.

Seasonal Adjustment Tab

seasonal adjustment tab

Use this tab to choose the type of adjustment and the seasonal filter. You can also choose to include the history and sliding spans diagnostics, and tell the program how to include the series in an aggregate, if the spec file is for a series that will be combined with others to create a composite series.

Type of adjustment: Select x11 to perform an X-11 seasonal adjustment, and SEATS to perform a SEATS adjustment. Select Trading day and holiday adjustment only to adjust the series only for calendar effects, not seasonality.

x11 filter options: Use the drop-down box to select the seasonal filter for the seasonal adjustment. Choose "3x3," "3x5," or "3x9" to use that filter for all X-11 iterations. Select "Global MSR" to let the program choose a 3x3, 3x5, or 3x9 filter for the final iteration depending on the global moving seasonality ratio. Selecting "Hard-code Global MSR" will result in X-13ARIMA-SEATS running, using the Global MSR to choose the seasonal filter, and then writing your spec file with the chosen filter hard-coded. The "x11 default" filter is the default filter from older versions of X-12-ARIMA; it uses 3x3 filters for the initial seasonal factors and 3x5 filters for the final seasonal factors in each iteration.

How should the series be combined into the aggregate? If the spec file is being created for a series that will not be combined into an aggregate, select "Series is not part of an aggregate." Otherwise, choose to add, subtract, multiply, or divide the series into the aggregate or to ignore the series when creating the aggregate.

Stability diagnostics: Specify whether to calculate sliding spans and history diagnostics. An optional box is included to specify the start date for the revisions history analysis. Dates must be in yyyy.mm or yyyy.q format.

Metadata Tab

Metadata tab

When X-13ARIMA-SEATS is run in summary mode or graphics mode, a diagnostics file with model information and diagnostics is created. To include additional information in this file, enter a description in the "Key" column, and the value in the "Value" column. For example, if you type Adjuster into the "Key" column, and "John Smith" into the "Value" column, then
    metadata.Adjuster: John Smith
will be included in the .udg file.

If you press the Save button after entering the keys and values, these columns will be saved and included every time a spec file is produced. Press the Clear Metadata button the next time you create a spec file to delete the stored metadata information.


Return to index.


7. Creating New Metafile/Data Metafile

You can process multiple specs in one run using metafiles or data metafiles. A metafile is a list of the spec files to run. A data metafile is a list of data files, which are all run using the same spec file.

Metafiles are also used to adjust composite series. In this case, the spec files of the individual series should be listed first, and the parent spec file listed last.

Creating Metafiles With Win X-13

window for creating metafiles

To create a new metafile using the interface, select Create -> Metafile from the menu on the main screen. In the window that appears, select the directory containing the spec files from the folder browser. Select the spec files to include from the list box and enter a name for the new metafile in the text box.

If you are running a composite adjustment, choose the parent file (the spec file that contains the composite{} spec) from the drop-down box. To route the program output to an alternate directory, enter this new directory in the text box provided.

Press Create metafile. The new metafile will be saved to the same directory as the spec files.

Creating Data Metafiles With Win X-13

To create a new data metafile using the interface, select Create -> Data metafile from the menu on the main screen. In the window that appears, select the directory containing the data files from the folder browser. Use the drop-down box to choose the extension of the data files. All files with that extension will be added to the list box; select the files to include in the metafile.

To route the program output to an alternate directory, enter this new directory in the text box provided.

Press Create metafile. The new data metafile will be saved to the same directory as the spec files.

Win X-13 Limitations: Creating Metafiles by Hand

The interface can be used to create a metafile when all the files to include are in the same directory, and program output has the same name as the spec or data file. If you need a metafile for spec files across different directories, or want to specify an alternate output name, you must create or edit the metafile by hand. The following is a list of things to keep in mind when doing so:

  • Metafiles have a .mta extension. Data metafiles have a .dta extension.
  • Do not include the .spc extension for the spec files. The extension of the data files listed must be included in the data metafile.
  • Only one spec file or data file can be on a line.
  • If the spec file or data file is not in the same directory as the metafile, include the full path and filename of the file.
  • To specify an alternate name for the output, include it on the same line as the spec or data file. To specify an alternate path, include the path and the output name (even if you are not renaming the output) on the same line as the spec or data file.
  • If the path or filename of the input has spaces, it must be enclosed in quotation marks. Similarly, if the path or filename of the output has spaces, it must be enclosed in quotation marks.
  • If you are running a composite adjustment, the composite spec file must be the last spec.

For more information on creating metafiles, see Section 2.4 of the X-13ARIMA-SEATS documentation (U.S. Census Bureau 2013).


Return to index.


8. Creating Diagnostics and Graphs From Previously Run Series

The diagnostics tables and graphs described in Sections 6C, 6D, and 6E can be created using previously run spec files.

To create the diagnostics table, the spec file had to be run in summary mode (with Create summary file with diagnostics information checked) or in graphics mode. If the spec file is run in graphics mode, the diagnostics file (.udg file) will be saved to the graphics directory. Otherwise, if run in summary mode, the diagnostics file will be saved to the same directory as the program output.

From the menu on the main screen, select Create -> Diagnostics. Enter the directory containing the diagnostics file in the Summary file directory box, select the .udg files to add to the diagnostics table, and press OK. Alternately, if you'd like to add all the series listed in a metafile to the diagnostics table, enter the directory of the metafile in the Summary file directory box. Choose "Metafiles" from the drop-down box, select the metafile from the list, and press OK.  If the metafile contains an alternate output directory, the program will look in that directory for the .udg file. Otherwise, it will look in the directory containing the metafile. If you ran the metafile in graphics mode, the .udg files will be in the graphics directory, which in most cases is different from the metafile's directory; copy the metafile to the graphics directory before trying to create diagnostics.

If a series was run in graphics mode, you can create Java or SAS graphs by choosing Create -> Graph from the menu of the main screen.

If Java graphs are selected from the Settings window, a new window will appear. Enter the graphics directory in the box provided. You can select the series to graph from the list box, and check the boxes for the graphs to create. A new graph window will appear for each series containing all the graphs checked, if applicable to the series.

If SAS graphs are selected from the Settings window, then choosing Create -> Graph from the menu will start the X-13-Graph interface. Creating graphs with this interface requires more effort, but there are more graphs and graph options available than with the Java graphs. See the X-13-Graph documentation (U.S. Census Bureau 2012) for complete details of the program.


Return to index.


9. Deleting X-13 Files

X-13ARIMA-SEATS can produce many output files when running a series. You can use the interface to delete them once you no longer need them.

Deleting X-13 Files Screen

To open this screen, go to File -> Delete X-13-Files in the menu. Use the folder browser to select the directory containing the files to be deleted. The interface will list the names of the X-13 files found, without the extension, in the list box on the right. All the extensions from these files will be listed in the box on the bottom. In the file name list box, check the boxes next to the files to be deleted. In the extensions list box, deselect any file extensions to keep. For example, if your data is called MyData.dat, the spec file is MyData.spc, and the output files MyData.out, MyData.log, MyData.err, and MyData.udg are in the directory, checking "MyData" in the file name box and deselecting "*.dat" in the extension list box will delete all files except the data file.

Pressing Delete opens a screen listing all the files, with the extensions, that will be deleted. Press Delete to confirm the file deletion.


Return to index.


10. Acknowledgements

This program was conceived and mainly written by Roxanne Feldpausch. Thanks also to Christopher Blakely for his help in adding the Java graphs and to David Findley, Brian Monsell, and Kathleen McDonald-Johnson for their suggestions and feedback.

The program's Java graphs are produced using the JFreeChart and JCommon libraries, (C)opyright 2000- 2013 by Object Refinery Limited and Contributors. The libraries are covered by the Lesser General Public Licence. The interface also uses the Explorer Tree Control by Jim Parsells, covered by the Code Project Open License.


Return to index.


11. References

U.S. Census Bureau (2013). X-13ARIMA-SEATS Reference ManualPDF.

U.S. Census Bureau (2012). X-13-Graph: A SAS/GRAPH Program for X-13ARIMA-SEATS OutputPDF.


Return to index.



[PDF] or PDF denotes a file in Adobe’s Portable Document Format. To view the file, you will need the Adobe® Reader® Off Site available free from Adobe.

This symbol Off Site indicates a link to a non-government web site. Our linking to these sites does not constitute an endorsement of any products, services or the information found on them. Once you link to another site you are subject to the policies of the new site.

Source: U.S. Census Bureau | OSMREP and CSRM | (301) 763-1649 (or x12@census.gov) |  Last Revised: December 18, 2013