Skip Header

The 2020 Census, Next Steps and a Heartfelt Thanks. Read More.

Version 1.1
Demetra Lytras
Component ID: #ti2103247886

1. Introduction

X-13ARIMA-SEATS input specification files (spec files) are text files; editing them one at a time is simple and can be done with any text editor. However, making changes to multiple spec files can be time-consuming. X-13-SAM lets you quickly make changes to many spec files at one time.

With X-13-SAM you can remove specs (named functional units within a spec file), add specs, and add or change arguments (named values that control program settings). It also includes commenting and reformatting options. All the changes that can be made with X-13-SAM are detailed in Section 4.

Changes to Version 1.1 include:

  • the ability to delete all outliers before or after a specified date;
  • the ability to change only the start or end date of a span argument;
  • the ability to edit arguments not included in the argument list drop-down box;
  • a fix to how output options (directories/suffixes) work when reading the spec files from a metafile;
  • and various bug fixes.

Component ID: #ti1724551872
Component ID: #ti1328996722

2. Requirements and Installation

X-13-SAM has been tested on Windows 8 and 10; it may be compatible with previous versions of Windows. To run X-13-SAM, you must have .NET Framework Version 3.5 on your computer. This is available at https://www.microsoft.com/en-us/download/details.aspx?id=21.

To install the X-13-SAM program, follow the instructions below:

  1. Copy the X-13-SAM zip file (x13sam_V1.1.zip) to your computer.
  2. Uncompress the file. X-13-SAM will be stored in a x13sam subdirectory.

To start the program, open (double click on) the file X13SAM.exe.

Component ID: #ti248274460
Component ID: #ti1841874001

3. Instructions

To edit spec files with X-13-SAM, first select the spec files to edit. Then add the edit actions, which tell X-13-SAM exactly how to edit the spec files. Next select the output options for saving the new spec files, and finally run the program.

Component ID: #ti471559159

Select the spec files to edit

In the Spec file directory text box, type in the directory containing the spec files to edit, or use the Browse button to find it. The spec files will be listed in the list box. Select the spec files to edit.

If the spec files to edit are listed in a metafile (a file with extension .mta listing spec files), choose the Edit Specs in Selected Metafile tab and select the metafile. All the listed spec files will be edited. Metafiles used in X-13ARIMA-SEATS can provide alternate output destinations and names, but X-13-SAM will ignore this output information. Only the output options discussed below can direct the file names and directory for the edited specs.

Component ID: #ti607965955

Select the edit actions

The drop-down box Select type of spec editing action contains the edit action categories described in Section 4. These are the instructions on exactly how to edit the spec files. Once you have selected the action according to the instructions below, press Add actionto add it to the list of actions to be performed.

View this list by pressing View actions. In the window that appears, actions can be removed or reordered. Actions are listed in the order they will be implemented in editing the spec file.

Edit actions can also be added to a shortcut list. This list is saved when the program is exited and automatically loads when the program is restarted. If there are actions you anticipate using often, it can be convenient to add them to your shortcut list so you can quickly add the action to your edit action list. Section 5 discusses shortcuts in more detail.

Component ID: #ti317250632

Select the output options

It's best not to overwrite your current spec files in case the program does not perform as anticipated or if you need the original spec files for other purposes. X-13-SAM provides two options for saving the edited spec files. You can provide a Directory for new spec files and a Suffix to append to spec file names.

The edits to the spec file "Shoe Stores.spc", found in C:\data\retail\, will be saved as

  • C:\data\retail\shoe stores.spc by default (if no alternate output information is given).
  • C:\data\retail\newspecs\shoe stores.spc if the output directory is C:\data\retail\newspecs.
  • C:\data\retail\shoe stores_edit.spc if _edit is given as the suffix.
  • C:\data\retail\newspecs\shoe stores_edit.spc if both the output directory and the suffix _edit are given.

Component ID: #ti1767450461
Component ID: #ti1698177913

Run the program

Press Edit specs to start the editing. Once the program has edited all the spec files, a log of the changes will appear. (This log can be saved as a text file by pressing Save log.) To return to the main X-13-SAM screen from the log, choose either Close: Retain Action List or Close: Clear Action List.

The following sections describe each of the edit actions available in the drop-down box.

Component ID: #ti1192466978
Component ID: #ti839002311

4. Edit Action Details

The following sections describe each of the edit actions available in the drop-down box.

Component ID: #ti444271619

4.1 Edit arguments in a spec

When Edit arguments in a spec is selected, two more drop down boxes will appear. Select the spec from the first box and the argument to edit from the second. All arguments can be removed, commented out, added, or changed. Some arguments have additional edit actions available, which will be described later in this section.

For all arguments, you'll see these options appear:

Component ID: #ti65474331

Remove the argument from all spec files will remove the argument and its value.

Comment out argument with code ___ will add a "#" before the argument. (X-13ARIMA-SEATS ignores all text following a "#" when it runs.) If you would later like to uncomment the argument with X-13-SAM, you'll need to enter a comment code in the text box. X-13-SAM will add this code immediately after the "#" when it comments out the argument. For example, if you comment out the span argument in the outlier{} spec using the code ~ospan~, the spec

outlier{ span = (2015.1, ) types = all }

will become

outlier{ #~ospan~span = (2015.1, )
   types = all }

Later, you can uncomment the argument by providing the code. (See Section 4.6.)

The final three arguments allow you to add an argument or change its value. If argument is not in spec file, add it with value ____ will add an argument to a spec if the spec itself is in the spec file but the argument is not. This action is ignored if the spec is not in the spec file. If you want to make sure your argument is added but you are not sure the spec is in every spec file being edited, include an Add a spec action in your action list.

If argument is in spec file, change value to ____ will replace the entire current value of the argument to the value provided.

For all spec files, change or add argument with value ____ will change the arguments value to the new value if it exists, and will add the argument with the given value if it does not exist AND if the argument's spec is in the spec file.

Some arguments have specialized edit actions available.

arima{} model argument

While for most arguments the entire value is changed when If argument is in spec file, change value to ___ is selected, for the ARIMA model argument you can change only one of the components of the model. An ARIMA model is often given in the form (p d q)(P D Q), where the first component is the nonseasonal and the second the seasonal component. (If only one component is given, say (0 1 1), this is taken to be nonseasonal unless followed by a 4 (for quarterly) or 12 (for monthly).) To change only one of the components, enter the new ARIMA model with (p d q) -- not case sensitive -- as the component to keep the same. For examples, see the table below. This feature works only for models up to two components.

ARIMA Model Argument Examples

Value in edit box     Current ARIMA Model     New ARIMA Model
(p d q)(0 1 1) (1 1 0)(0 0 1) (1 1 0)(0 1 1)
(P D Q)(0 1 1) (1 1 0) (1 1 0)(0 1 1)
(p d q)(0 1 1) (1 1 0)12 (0 1 1)12
(0 1 2)(p d q) (0 1 1)(0 1 1) (0 1 2)(0 1 1)
(0 1 2)(P D Q) (0 1 1) (0 1 2)
(0 1 2)(p d q) (0 1 1)12 (0 1 2)(0 1 1)
(p d q) (0 1 2)(0 1 1) (0 1 2)
(p d q)12 (0 1 2)(0 1 1) (0 1 1)12

Span arguments

All span and modelspan arguments in X-13ARIMA-SEATS have the form ( [start date] , [end date] ), with the dates given in yyyy.mm format. For example, 2019.1 represents the first month or quarter of 2019. Both the [start date] and the [end date] are optional; the program uses the data from the beginning or until the end, respectively, if one is missing. With X-13-SAM, you can change only the start or only the end date of a span or modelspan argument by entering yyyy.mm in the place of the date to leave unchanged. See the table for examples.

 

Span Argument Examples

Value in edit box Current Span New Span
(yyyy.mm, 2018.12) (2008.1, 2017.12) (2008.1, 2018.12)
(yyyy.mm, 2018.12) (, 2017.12) (, 2018.12)
(yyyy.mm, 2018.12) (2008.1,) (2008.1, 2018.12)
(2005.1, yyyy.mm) (2000.1, 2017.12) (2005.1, 2017.12)
(2005.1, yyyy.mm) (2000.1, ) (2005.1, )
(,yyyy.mm) (2008.1, 2017.12) (, 2017.12)
(2005.1, 2018.12) (2000.1, 2017.12) (2005.1, 2018.12)

 

File arguments

When a file argument is selected, a checkbox Edit directory info appears next to the argument drop down box. Check this box to see the following options appear:

Component ID: #ti191287077

Remove directories from file argument will remove any directory information but retain the file name and extension. Add/change directory to ___ will look for the file argument; if it is in the spec file, it will add the provided directory to the argument's value or change the current directory to the new one. If you want the directory changed only if it is some specific directory, use the If directory is _____ change it to _____ option. Leave the first box blank to insert the provided directory into the file argument only if there is no directory currently in the argument, and leave the second box blank to remove a directory only if it is the one provided in the first box.

In all three cases, the file name and extension will remain unchanged. To change the file name, uncheck the Edit directory info box and use the edit argument options as usual.

series{} title argument

You can customize title edits to your series using the keywords [specname], [outputname], and [title].

When writing your new title, X-13-SAM will replace [specname] with the name of the spec file and [outputname] with the name of the new spec file being written. If you are editing the spec file "Shoe Stores.spc", then adding the title "[specname]: Automatic Options" will result in the title "Shoe Stores: Automatic Models". If you are saving your new spec files with the suffix "_amd", then the title "All Auto Options - [outputname]" will result in the title "All Auto Options - Shoe Stores_amd".

Use [title] to insert the current title into the new title. If "Shoe Stores.spc" has the title "Retail Sales at Shoe Stores", then editing the title to "[title]: Shortened Model Span" would result in "Retail Sales at Shoe Stores: Shortened Model Span".

Use [title:] to retain the title up to and including the first colon. If the current title is "Shoe Stores: Automatic Options", then "[title:] Airline Model" would result in "Shoe Stores: Airline Model". If there is no colon, the entire title will be used and a colon inserted after the original title. If the [title:] is at the end of the new title, the colon will be removed.

If you use [title] or [title:] and there is no title argument in the series{} spec, the spec file's name will be used instead.

regression{} variables argument

When you select the variables argument in the regression{} spec, check the box Edit list values to edit individual items in the list of regression variables. You can either add items to the list or remove specific items from the list.

Component ID: #ti1336043604

An item will be added to the list only if the variables argument exists in the spec file. If you're not sure that it exists in all the spec files being edited, first include an action to add the variables statement to the regression{} spec.

X-13-SAM will check whether the exact item you're adding is in the variables list before it adds it; however, it will not check for variations of items. For example, if your variables statement includes easter[8] and you add an action to insert easter[8] into the spec files, it will not add a second easter[8] regressor. However, it you ask X-13-SAM to add easter[1], it will add this even though easter[8] is already there. If you want only easter[1] in your spec files, first add an action to remove easter[w] regressors from the list, and then add the action to insert easter[1].

To add a regressor to the list, first select the regressor from the drop down box. If the regressor needs a window length for a holiday effect of an inventory day for stock trading day, a second drop down box will appear with the possible options. If the regressor needs a date, a text box will appear for you to type the date in. If the regressor includes a change of regime, X-13-SAM assumes you want a full-change regressor (td/yyyy.mm/, for example). If instead you want a partial change (td//yyyy.mm/ or td/yyyy.mm//), you must type the appropriate slashes into the box along with the date. No checking is done to see if the date supplied is valid.

To remove items from the variables list, select the regressor from the drop down box.

For regressors that need a window length or day of inventory, a drop down box will appear with possible options. If you select a number from the list, only that particular regressor will be searched for and removed. If you select [any], all regressors of that type will be removed.

For regressors that need a date, a box will appear to type in the date. Leave this box blank to remove arguments regardless of date. For example, selecting AOyyyy.mm and leaving the Date box blank will remove all additive outliers. If you enter a date, only that specific outlier will be removed. Selecting AOyyyy.mm and entering 2008.Apr will remove AO2008.Apr, ao2008.04, Ao2008.4, ao2008.apr, etc. It will not remove AO2008.May. You can remove all outliers of a selected type (AO, LS, TC, and SO only) before or after a specified date by including <, <=, >=, or > with the date. For example, if you select LSyyyy.mm and enter the date

  • <2007.12, all LS outliers before December 2007 will be removed; LS2007.12 would remain.
  • >=2015.1, all LS outliers on or after January 2015 will be removed.

X-13-SAM can only remove all arguments that cover a date range -- ramps and AO or LS sequences. It cannot remove the outliers covering a specific range. So you can remove all ramps RPyyyy.mm-yyyy.mm, but you cannot remove only RP2008.1-2008.10.

If you select a change-of-regime regressor, a box for the change date appears. Leave this box blank to remove all change-of-regime regressors of the selected type. If you enter only a date, all change-of-regime regressors of that type at that date will be removed (regardless of whether they are full- or partial-change regressors). If you enter yyyy.mm surrounded by start and end slashes, all change-of-regime regressors with that regime pattern will be removed. For example, select td/yyyy.mm/ and type in //yyyy.mm/ to remove td//2009.1/ or td//2002.Jan/, but not td/2009.1/ or td/2002.Jan//. If you enter a date and start and end slashes, only that exact regressor will be removed.

Component ID: #ti640592502
Component ID: #ti506191204

4.2 Add a spec

Select Add a spec from the drop down box to add a spec and any arguments you request to the spec file. When you select this argument, you'll see a drop down box appear from which you can select the spec name. Then type the arguments for the spec into the text box.

Formatting: If nothing is in the argument box, X-13-SAM will include the spec with open and close braces on the same line. If arguments are included, X-13-SAM will include the spen name with the open brace on one line, followed by the arguments exactly as typed but indented four spaces on the next lines, and the closing brace on the next line.

Use the options below the argument box to select when the spec will be added to the spec file. The options are

  • If spec exists, overwrite it with these arguments; add spec if it does not exist.
  • If spec exists, do nothing; add spec only if it does not exist.
  • If spec exists, overwrite it; if it does not exist, do not add it.

For example, in the following image we request an automdl{} spec with three arguments be added:

Component ID: #ti1782615804

Since If spec exists, overwrite it; if it does not exist, do not add it is selected, the spec

    automdl{
        mixed = no
        maxorder = (3 1)
        print = all
    }

will replace all current automdl{} specs. However, if the spec file instead has an arima{} spec, this new automdl{} spec will not be added.

Component ID: #ti1308524764
Component ID: #ti1958785820

4.3 Remove a spec

After choosing Remove a spec from the edit action drop down box, select the spec to remove from the drop down box which appears. This will remove the spec and all its arguments.

Component ID: #ti1717439846

If you check the box for Remove all comments within the spec everything between the start and end braces for that spec will be removed. If you leave it unchecked, all uncommented text will be removed but any comments between the braces will remain in the spec file.

Component ID: #ti569648912
Component ID: #ti1020105369

4.4 Comment out a spec

To comment out an entire spec, select Comment out a spec and select the spec name from the drop down box. You have the option to supply a comment code, which will include this text after the “#” sign when the spec is commented out. By supplying this code, you can later return commented text to the spec file using X-13-SAM. (X-13-SAM does not have an option to read through comments to find particular specs or arguments and uncomment them; it is only able to uncomment specs and arguments by searching for particular text strings of “#” followed by a supplied comment code.)

Component ID: #ti1070829473

For example, say you want to to run the series with seats{} but your spec files have x11{} specs. If you know you'll want to change back to the current x11{} specs later, you can comment out the x11{} spec with the comment code ~x11~. After running X-13-SAM, your x11{} spec may look like:

    #~x11~x11{
    #~x11~    seasonalma = s3x3
    #~x11~    sigmalim = (1.8 2.8) #~x11~}

Component ID: #ti799555802
Component ID: #ti405755435

4.5 Remove all comments from spec file

Select Remove all comments from a spec file to locate all “#” signs in the spec files and remove them along with all text following it on the same line.

Important: X-13-SAM does not differentiate between “#” signs intended as comments and “#” within quotes, as a title. For example, if your spec file has the argument

title = “Run #1: All Automated”

this option will change this to

title = “Run

which will cause a problem when X-13A-S runs the spec file, as there are unclosed quotation marks.

Component ID: #ti832472058

4.6 Comment in coded comments

Component ID: #ti1202970240

Select Comment in coded comments and enter a comment code in the text box to locate all comments followed by the user-designated text string (the comment code) and convert them from comments to executable lines of the spec file. See Section 4.4 for more details about comment codes.

Component ID: #ti2054677293
Component ID: #ti728371841

4.7 Trim white space at end of lines

Select Trim white space at end of lines to remove all spaces and tabs at the end of lines in the spec files.

Component ID: #ti1678674109
Component ID: #ti1041076596

4.8 Remove all extraneous white space

Select Remove all extraneous white space to remove:

  • All double spaces and tabs, except at the beginning of a line
  • The spaces around the equals sign
  • The spaces before and after curly brackets
  • The spaces immediately following the start of parentheses and immediately preceding their end.

Component ID: #ti2029283434
Component ID: #ti1372698749

4.9 Compress lines

Select Compress lines to create a new spec file with fewer lines. Instead of the current line spacing, this option will put as much as possible on each line, with each line ending when:

  • There is a comment on the line
  • There is an end curly bracket on the line
  • Adding the next line will result in more than 80 characters on the line.

Component ID: #ti1066136714
Component ID: #ti615972063

4.10 Reformat specs in Win X-13 style

Select Reformat specs in Win X-13 style to change the format of the spec files to something closer to those created by Win X-13. This option will change the order of specs; indent argument and comment lines four spaces; change spec names, argument names, and all values not in quotation marks to lower case; and ensure there is one space before and one space after equal signs.

Component ID: #ti672849682
Component ID: #ti1535218704

5. Shortcuts

If there are actions you repeat frequently with X-13-SAM, consider adding a shortcut to the action. To do this, select the action as you do when adding new actions, and press the Add Shortcut button. The action will be added to your list of shortcuts, and the list will be retained from session to session.

To use a shortcut, press the View Shortcuts button. In the window that appears, select the action(s) you’d like to use, press Add Action, and close the window. If you press View Actions, you’ll see your shortcut action has been added to the list of actions to perform when editing your spec files.

This can save time with the more complex edit actions you use frequently, like adding a spec with multiple arguments or adding/removing seasonal regressors.

Component ID: #ti230286881
Component ID: #ti2097991331

6. Support

Contact Demetra Lytras at demetra.p.lytras@census.gov or 301-763-7426 with any questions.

Component ID: #ti1522152646
Back to Header