Skip to content

X-13-SAM (Spec-file Automated Modifications) Version 1.0

Version 1.0
Demetra Lytras
Component ID: #ti317143026

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.

Licensing information for this and other software distributed from this site can be found here:

Component ID: #ti784310564
Component ID: #ti1179865714

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.0.zip) to any drive of your computer.
  2. Uncompress the file. X-13-SAM will be stored in a x13sam subdirectory.

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

Component ID: #ti2034379320
Component ID: #ti55769141

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: #ti2092140523
Component ID: #ti1410487205

3.1 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 your spec files are listed in a metafile (a file with extension .mta listing spec files), choose the Edit Specs in Selected Metafile tab and select the metafiles. Then all the listed spec files will be edited. While metafiles used in X-13ARIMA-SEATS can have spec files in different directories and can provide alternate output destinations and names, for X-13-SAM a metafile can only list spec files in the same directory as the metafile, and output information will be ignored.

Component ID: #ti1919645168
Component ID: #ti1804954977

3.2 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 action to 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: #ti2136401199
Component ID: #ti1564795732

3.3 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: #ti741411975
Component ID: #ti810684523

3.4 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: #ti689579386
Component ID: #ti1669860125

4. Edit Action Details

Component ID: #ti2064590817

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: #ti1851579191

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.

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
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: #ti1594817783

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: #ti1172818832

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.

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: #ti1145512358
Component ID: #ti1906729728

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: #ti726246632

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: #ti573521600
Component ID: #ti172680960

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: #ti695481086

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: #ti1843272020
Component ID: #ti1488757067

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: #ti2118496957

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: #ti1709306634
Component ID: #ti2007165497

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: #ti1676390378

4.6 Comment in coded comments

Component ID: #ti679076124

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: #ti358243639
Component ID: #ti1780490595

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: #ti830188327
Component ID: #ti1467785840

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: #ti383637498
Component ID: #ti413406111

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: #ti719968146
Component ID: #ti1892890373

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: #ti1836012754
Component ID: #ti973643732

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: #ti1651759483
Component ID: #ti314929601

6. Support

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

Component ID: #ti474485162
X
  Is this page helpful?
Thumbs Up Image Yes    Thumbs Down Image No
X
No, thanks
255 characters remaining
X
Thank you for your feedback.
Comments or suggestions?