Documentation for the RUNSPEC CLI
The detailed uswrun --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 uswrun --help command is as follows:
usage: uswrun FILE [--help] [--test] [--dryrun] [--version] [--usage]
Executes USW-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 uswrun 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 uswrun --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 CALCOPTS {};
-- specify default values of calculator-options parameters
-- best practice is to omit instruction if using default parameter values
USE CALCOPTS {
-- 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 'co' 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 uswplot 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.