Documentation for the RUNSPEC CLI

The detailed myirun --help documentation (which includes the summary --usage documentation) is shown in the first section below. For information on the run specification language understood by the RUNSPEC CLI, see the second section below.

RUNSPEC CLI Help

The screen output generated by the myirun --help command is as follows:

usage: myirun FILE [--help] [--test] [--dryrun] [--version] [--usage]

Executes MYI-Tax-Analyzer model run defined in run specification file named
FILE.

positional arguments:
  FILE        name of file containing run specification language instructions.
              FILE must end in ".run".

optional arguments:
  -h, --help  show this help message and exit
  --test      optional flag that conducts installation test, writes test
              result to screen, writes the language-words and language-rules
              files, writes the test.run file that documents the run
              specification language, and then exits.
  --dryrun    optional flag that does calculations but does not write output
              files (useful for testing)
  --version   optional flag that writes myirun release version and exits.
  --usage     optional flag that writes short command-line usage reminder and
              exits.

RUNSPEC Language Documentation

The run specification language documentation included in the test.run file generated by the myirun --test command is as follows:

INFORMATION ABOUT THE RUN SPECIFICATION LANGUAGE
------------------------------------------------
The USE INPUT, USE TAXYEAR, and USE REFORM instructions are required,
all other instructions are optional.  There can be at most one USE
instruction of each type.  The key words shown in all-caps below may
be spelled using any combination of upper or lower case letters.
Every instruction must end with a semicolon.

USE INPUT <filename.csv>;
  -- in place of <filename.csv>, specify EITHER
  --   the name of an existing CSV-formatted model-input file
  -- OR
  --   tax.csv to access the built-in input data and weights

USE TAXYEAR <year1>;
  -- specify single-year model run by replacing <year1> with four digit year
USE TAXYEAR <year1> TO <year2>;
  -- specify multiple-year model run for years <year1> through <year2>

USE REFORM {};
  -- above specify no reform provisions, which implies current-law policy
  -- below specify reform provision(s)
USE REFORM {
 SET <pname> TO <value> IN <year>;
 SET <pname> TO <value> IN <year> FOR <element>;
   -- a SET TO instruction can be used with any parameter marked 'pr' in
   --   the language-words file
   -- <value> is a number for real and integer parameters and is composed
   --   of just characters for boolean and string parameters
   -- <year> is the year in which the <value> for <pname> is set
   -- the optional FOR <element> phrase specifies which element of vector
   --   parameter <pname> is having its <value> set
   -- each SET TO instruction must end with a semicolon
 CHANGE <pname> BY <number> IN <year>;
 CHANGE <pname> BY <number> IN <year> FOR <element>;
   -- a CHANGE BY instruction can be used only for a subset of 'pr' parameters:
   -- ones that are marked real and notindexable in the language-words file
   -- Note: all such parameters can be found easily using this command:
   --   tagrep -e real language-words | tagrep -e notindexable
   -- or to narrow the search to just policy reform ('pr') parameters:
   --   tagrep -e real language-words | tagrep -e notindexable | tagrep -e pr
};

USE RESPONSE {};
  -- specify no behavior response to reform (that is, static tax analysis)
  -- best practice is to omit instruction if not specifying behavior response
USE RESPONSE {
  -- use same SET TO or CHANGE BY instructions as used in the USE REFORM
  -- instruction above, except <pname> is replaced by parameters that
  -- are marked 'br' in the language-words file
};
-- Setting the substitution elasticity for a variable to a tiny value,
-- say 1e-99, causes the dump output to include the marginal tax rate
-- for that variable, while the overall run results are essentially the
-- same as assuming no behavior response because the elasticity is tiny.

USE GROWDIFF {};
  -- specify no differences between assumed and default growth factors
  -- best practice is to omit instruction if not specifying any differences
USE GROWDIFF {
  -- use same SET TO or CHANGE BY instructions as used in the USE REFORM
  -- instruction above, except <pname> is replaced by parameters that
  -- are marked 'gd' in the language-words file
};

USE DUMPVARS {
 <var1> <var2>
 <var3> ... <varN>
};
  -- specify any number of space-delimited variable names that are marked
  -- either 'vr' (read variable) or 'vc' (calculated variable) in the
  -- language-words file; if no additional dump output variables are needed,
  -- omit the USE DUMPVARS instruction
USE DUMPVARS ALL;
  -- include all (read and calculated) variables in dump output file, which
  -- will use large amounts of memory and disk space for a large INPUT file
  -- especially when writing a database dump output file

USE FLAGS {
 TSTAX   -- include to get time-series tax output for plotting
         --   with the myiplot tool that can generate SVG, PDF, or EPS graphs
 XSTAX   -- include to get cross-section tax output for plotting
         --   with the myiplot tool that can generate SVG, PDF, or EPS graphs
 XSATI   -- include to get cross-section after-tax-income output for plotting
         --   with the myiplot tool that can generate SVG, PDF, or EPS graphs
 XSETR   -- include to get cross-section effective-tax-rate output for plotting
         --   with the myiplot tool that can generate SVG, PDF, or EPS graphs
 DBDUMP  -- include to have dump output file be an SQLite3 database file
 NODUMP  -- include to suppress writing of the dump output file
 NOTABLE -- include to suppress writing of the table output file
 NOPARAM -- include to suppress writing of the parameter output files
 SILENT  -- include to suppress screen output saying what model is doing
};
  -- space-delimited flags that control model output; if none of the above
  -- special output settings are needed, omit the USE FLAGS instruction

Note that a dash-dash (--) signifies the beginning of a comment that extends until the end of that line, while a slash-star (/*) signifies the beginning of a comment that extends until a star-slash (*/) is encountered, which could be on the same line or many lines below.