Windows Interface to X-12-ARIMA

Table of Contents

1. Basics
2. System Requirements
3. Installation Instructions – Setup, Initialization, and Documentation Files
4. Running Existing Spec Files/Metafiles
   • Running Instructions
   • Options
   • View
5. Creating Spec Files
6. Creating Metafiles
7. References

1. Basics

This interface allows you to run X-12-ARIMA without using the DOS prompt. It also creates basic input specification files (spec files) and metafiles for you.

Problems installing or running this program? Please contact Roxanne.Feldpausch@census.gov.

2. System Requirements

The Windows interface requires: Windows 2000 (or higher) and the X-12-ARIMA executable file.

3. Installation Instructions – Setup, Initialization, and Documentation Files

The following files should be placed in the directory from which you would like to run X-12-ARIMA

• X12a.exe, the X-12-ARIMA executable
• RunX12.exe, the executable needed to run the Windows Interface to X-12-ARIMA
• RunX12.ini, a file with information on your system's setup
• cnvOut2html.exe, an optional program used to convert X-12-ARIMA output into html
• test.spc, a sample spec file

Note: If you already have X-12-ARIMA installed, put the two RunX12 files in the same directory as X-12-ARIMA.

RunX12.ini contains the following information.

	[x12 runtime]
	Install Path=C:\x12a
	Executable=X12a
	Data Path=C:\x12a
	GraphicPath=C:\x12a\graphics
	View Output files=*.log;*.out;*.udg;*.err;*.html
	Edit Command=notepad
	html output=yes
	Converter=c:\x12a\cnvOut2html
	html dir=C:\x12a\html\
	

Edit the RunX12.ini file to match your settings. WARNING: The program will not run if directories in the runx12.ini file do not already exist.

• Install Path: list the directory where X-12-ARIMA is installed.
• Executable: list the executable name of the version of X-12-ARIMA you are running. In most cases, the executable will be x12a. If you are running version 0.2.10, then the executable is named x12a or x12axp.
• Data Path: list the directory where most of your spec files are located. This will be the starting directory.
• GraphicPath: list the name of the folder where you send most of your graphics files. The directory name provided should be different from the directory used for the output files and spec files to avoid filename conflicts. It also should be a complete path name for the operating system (for example, C:\x12a\graphics not \graphics).
• View Output files: list the types of files you would like to see in the output window.
• Edit Command: list the text editor you wish to use. The default editor is Notepad. For all other text editors, use the complete path and executable name.
• html output: type "yes" if you would like the output in html (you need the html converter), type "no" if you prefer text output.
• Converter: If you would like html output, list the complete path and name of the executable of the converter program. You need this program to create html output.
• html dir: if you would like the html output to go to a specific directory, list the directory here. If you do not list a directory, the html output will go into the same directory as the spec file.

Now you are ready to run the program. Open (double click on) the file RunX12.exe to start the program.

4. Running Existing Spec Files/Metafiles

Running Instructions

1. Open the RunX12 program by double-clicking on RunX12.exe.
   
   
2. Use the boxes on the left to change to the drive and directory where you've saved the spec file.
   
   
3. To run a spec file or a metafile, select the name of the file from the middle box labeled Input Files and click on the "Run" button, or double click on the name of the file.
   
   Once X-12-ARIMA is finished running, a message will appear stating that the processing is complete. Output files produced by X-12-ARIMA will be listed in the box on the right. The output files will have the same name as the spec files, but with a different extension. Select the file and click on the "Open Output" button to open it in the editor, or double click on the filename.
   
   
4. To edit or view the spec file or the metafile, select the spec file and click on the "Open Spec File" button.
   
   

Options

• To run in graphics mode, check the "Graphics" box under Options. The name of the graphics directory (where X-12-ARIMA outputs graphics files) will pop up. You can change the directory if you wish. Running X-12-ARIMA in graphics mode will allow you to use X-12-Graph to graph the series.
  
  The directory name provided should
  • already exist
  • be a complete path for the operating system (for example, c:\x12a\graphics, not \graphics)
  • be different from the directory used for the output file to avoid filename conflicts.
  
  The graphics files generated include
  • the graphics metafile (extension .gmt) which contains the series codes and filenames for all files generated by X-12-ARIMA in the graphics directory
  • the diagnostics file (extension .udg) which contains information about the series and the modeling and seasonal adjustment options used
  • the series to be graphed. The specific series that are included depend on the options specified in the spec file.
  
  
• If you want to run X-12-ARIMA and not overwrite previous output, you can direct the output to another file by checking the "Output Name" box under Options. Then enter the name of the alternate output filename in the box. This option is available only for spec files.
  
  
• To run in diagnostics mode (the -s flag), check the "summary file" box under Options. The "summary file" option in X-12-ARIMA produces an additional diagnostics file with extension .udg which contains information about the series and the modeling and seasonal adjustment options used. (This file is also produced when you run X-12-ARIMA in graphics mode.) The diagnostics file is used by X-12-Graph and by some of the other programs written to accompany X-12-ARIMA.
  
  
• To run in quiet mode, check the "quiet" box under Options. Quiet mode turns off the warning message that would be sent to the "Screen Output" file. You will still see error messages.
  
  
• To run in no tables mode, check the "no tables" box under Options. No tables mode produces an output file that contains only the tables specifically requested in the input specification file.
  
  
• To run in reduced output mode, check the "reduced output" box under Options. In reduced output mode, the tables and headers are condensed.
  
  
• To produce an output file without pagination, check the "no pagination" box under Options.
  
  
• To produce an output file in wide format (132 characters), check the "wide output" box under Options.
  
  
• To sum the components of a composite adjustment but only perform modeling or seasonal adjustment on the total, check the "sum component" box under Options.
  
  
• To check the input file for error, check the "verify spec" box under Options. No other processing will be done.
  
  

View

• To see the output from X-12-ARIMA automatically, you can check the boxes for "Output File" and "Log" under View.
• To see the DOS output, check the "Screen Output" box under view (the default is to view this file). The screen output is saved to a file called WindowsX12ScreenOutput.out which is stored in the same directory as the spec file or metafile. This file is overwritten every time you run a file in that directory.
• To view output files after the procedure has finished, select the name of the output file in the box on the right and click on the Open Output box, or double click on the name of the file.

5. Creating Spec Files

1. Click the "New Spec File" button.
   
   
2. Use the boxes on the left to change to the drive and directory where you've saved the data file.
   
   
3. Select the data file in the box on the right.
   
   
4. Enter the filename for the spec file you would like to create. The default filename is the same as the data filename (with a .spc extension).
   
   
5. Select the periodicity of the data.
   
   
6. Select the format of the data. See Hood and Monsell (2002) for more details on the possible formats.
   
   • If you selected a data format with the potential for data records from multiple series in one file, type the name to use for the series. Note: the name should match exactly what is in the data file. Name recognition is case sensitive.
     
   • If you selected free format, enter the start date for the series.
     
     
7. By default, the span and model span are the whole series. To change the start and end dates, enter new dates on the form. The dates should be entered in yyyy.mm or yyyy.q format where yyyy is the four-digit year, mm is the two-digit month (for monthly series) and q is the quarter (for quarterly series).
   
   
8. To create a spec file, you have two options:
   • Create Basic Spec creates a spec file using program defaults
   • Spec Wizard allows you to customize the spec file
     
     

Create Basic Spec

	Example of an initial spec file

		series{
		    title= 'MW1FAM.spc'
		    file= 'EXAMPLE2.DAT'
		    format= '2L'
		    period=12
		    name=MW1FAM
		    savelog=peaks
		}
		transform{function=auto}
		regression{
		    variables=()
		    aictest=(TD Easter) savelog=aictest
		}
		outlier{
		    types=all
		    lsrun=3
		}
		automdl{}
		forecast{maxlead=42}
		estimate{print=(roots regcmatrix) savelog=aicc}
		check{print=all savelog=lbq}
		x11{savelog=(M1 M7 M8 M9 M10 M11 Q Q2)}


	Example of a final spec file

		#MW1FAM.spc was created automatically using X-12 Spec Wizard
		series{
		    title= 'MW1FAM.spc'
		    file= 'EXAMPLE2.DAT'
		    format= '2L'
		    period=12
		    name=MW1FAM
		    savelog=peaks
		}
		transform{function=none}
		regression{
		    variables=(TD )
		    #aictest=(TD Easter) savelog=aictest
		}
		outlier{
		    types=all
		    lsrun=3
		}
		arima{model= (3 1 1)(0 1 1)}
		forecast{maxlead=42}
		estimate{print=(roots regcmatrix) savelog=aicc}
		check{print=all savelog=lbq}
		x11{
		    seasonalma=s3x5
		    savelog=(M1 M7 M8 M9 M10 M11 Q Q2)
		}
		slidingspans{savelog=percent}
		history{estimates=(fcst aic sadj sadjchng trend trendchng)}

Spec Wizard

Click the "Spec Wizard" button. This will take you through the following series of screens that will allow you to customize the spec file.

1. Prior Adjustment of the data
   • Prior Adjustment File
2. ARIMA Model
3. Seasonal Adjustment
4. Stability Diagnostics

Prior Adjustment of the Data

1. Select the transformation type. If the data need a log transformation, select "Log." If the data do not require a transformation, select "None." If you do not know whether or not the data need a transformation, select "Automatic." This will put "function=auto" into the spec file, and the program will determine whether or not the data need a transformation. If you would like to hard-code the automatic model transformation into the spec file (recommended for repeated runs), check the "Hard-code" box.
   
   
2. Select the regression variables. For a regression variable, you can either ask X-12-ARIMA to use an AICC test to determine whether or not to include a variable in the regression or if you know the data, you can specify which variables to include in the regression.
   • In the Regression AIC Test frame, check any variable for which you would like to use the AICC test to determine whether or not to include in the regression. If you would like to hard-code the results of the AICC test into the regression model (recommended for repeated runs), check the "Hard-code" box.
   • In the Regression Variables frame, check any variables you would like to include in the regression. Stock trading day requires you to input the date when inventories are done. Select "31" if inventories are done on the last day of the month. Choosing the Easter regression requires you to input the number of days before Easter that you expect to see an effect on the data. To include another variable, such as a known outlier, in the regression spec, type the name of the outlier in the "Other" box.
     
     
   Note: If you would like to specify trading day (Easter) as a regression variable and include an AICC test for it, you will have to manually edit the spec file after it is created to include both options.
   
   
3. Select outlier detection options.
   • Select the types of outliers you would like X-12-ARIMA to identify. Check the "AO" box for additive outliers, check the "LS" box for level shifts and check the "TC" box for temporary changes. If you would like to hard-code the outliers identified by X-12-ARIMA into the spec file check the "Hard-code" box.
   • To have X-12-ARIMA check for canceling level shifts, select the number of level shifts to test in the LS run field. Note that this will not affect the outliers hard-coded in the previous step. You will have to look in the output file and determine if the level shifts cancel out and manually make any changes to the spec file.
   • By default, the span of data where X-12-ARIMA looks for outliers is the whole series. To change the start and end dates, enter new dates on the form. The dates should be entered in yyyy.mm or yyyy.q format where yyyy is the four-digit year, mm is the two-digit month (for monthly series) and q is the quarter (for quarterly series).
     
     
4. If you have a prior adjustment file, check the "Prior Adjustment File" box. This will take you to the Prior Adjustment File screen. If you do not check this box, you will go to the Step 2 ARIMA Model screen.

Prior Adjustment File

1. Use the boxes on the left to change the drive and directory where the prior adjustment file is saved.
   
   
2. Select the prior adjustment file in the box on the right.
   
   
3. Select the format of the prior adjustment file.
   
   

ARIMA Model

1. There are two options for the ARIMA model. You can use X-12-ARIMA's automatic modeling procedure or you can specify the ARIMA model.
   • Automatic modeling: click on the "automodel" radio button if you would like to use X-12-ARIMA's automatic modeling procedure to select an ARIMA model. If you would like to hard-code the results of the automatic modeling procedure (recommended for repeated runs), check the "Hard-code" box.
   • Specify the ARIMA model: click on the "ARIMA" radio button if you would like to specify an ARIMA model. Next type in the ARIMA model.
     
     
2. Select the number of years you would like to forecast with the regARIMA model.

Seasonal Adjustment

To perform an X11 type of seasonal adjustment, check the "Xll" box. To perform a trading day and holiday adjustment only and not estimate a seasonal component, check the "Trading day and holiday adjustment only" box. This option is best used for nonseasonal data that have other calendar effects. If you do not wish to perform any seasonal, trading day or holiday adjustment, do not select either of the boxes.

If you selected an X11 type of seasonal adjustment, select the type of filter that you would like to apply to all of the month (quarters) of data.

Stability Diagnostics

Check the "Sliding Spans" and "History" boxes if you would like these stability diagnostics.

6. Creating Metafiles

1. Click the "New Metafile" button.
   
   
2. Use the box on the left to change to the directory where you would like to create the metafile.
   
   
3. Use the drop down list to select what types of files you would like to see.
   
   
4. Select the series you would like in the metafile. If you do not select any series, all of the series in the box will go into the metafile.
   
   
5. Enter the filename for the metafile you would like to create. The default filename is temp.
   
   
6. To create a spec file, you have two options:
   
   
   • Click the "Create Basic Metafile" button to create a basic metafile.
     
     
   • Click the "Hierarchical Metafile" button to create a metafile for a composite run. For example, having X-12-ARIMA sum the four regions of the U.S. to calculate the U.S. total. The "Hierarchical Metafile" button will take you to a new screen. Either select one of the series to be the parent or type the name of the parent file. Select the series to be the children. If you do not select any series to be children, the program automatically will choose the remaining series as children. In the example, the U.S. total would be the parent series and the four regions would be the children.
     
     
   Note: If you already have a metafile with that name, the new metafile will overwrite it.

7. References

For information on X-12-ARIMA data formats and metafiles, please see the X-12-ARIMA Reference Manual (U.S. Census Bureau 2002) or "Getting Started With X-12-ARIMA Input Files on Your PC" by Hood and Monsell (2002).

Last Document Update: Thursday, May 3, 2007