Merge pull request #1304 from martinholmer/docs4

Revise user documentation in response to several suggestions

taxcalc/docs/index.htmx

@@ -18,7 +18,7 @@ If you want to participate in the development of Tax-Calculator
 — by reporting a bug, improving the documentation or making an
 enhancement to the Python source code — you should go to
 the <a href="https://github.com/open-source-economics/Tax-Calculator">
-development website</a>.</p>
+developer website</a>.</p>
 
 
 <h2>Document Contents</h2>
@@ -38,10 +38,10 @@ via the command line</p>
 <p>You can use Tax-Calculator via a graphical user interface (GUI)
 provided by the <a href="http://www.ospc.org/taxbrain/">TaxBrain web
 application</a>.  This approach requires only an Internet connection
-and web browser on your computer.  TaxBrain uses a micro dataset to
-produce for a tax reform you specify both aggregate and distributional
-reform estimates for each of ten years.  The calculations take just a
-couple of minutes and there is flexibility to show different kinds
+and web browser on your computer.  TaxBrain (TB) uses a micro dataset
+to produce both aggregate and distributional reform estimates for each
+of ten years for a tax reform you specify.  The calculations take just
+a couple of minutes and there is flexibility to show different kinds
 of distributional results.</p>
 
 
@@ -174,9 +174,10 @@ installation and file preparation work may be worth it to you.</p>
 
 <p>This section contains documentation of policy parameters in a
 format that is easy to search and print.  The policy parameters are
-grouped here as they are are on TaxBrain.  Parameters understood by
-Tax-Calculator and the tc CLI, but not available in the TaxBrain GUI,
-are placed in an Other Parameters group at the end of the section.</p>
+grouped here as they are are on TaxBrain (TB).  Parameters understood
+by Tax-Calculator and the tc CLI, but not available in the TaxBrain
+GUI, are placed in an Other Parameters group at the end of the
+section.</p>
 
 
 <h3>Section Contents</h3>
@@ -390,11 +391,15 @@ used to specify baseline differences and/or reform responses in the
 annual rate of growth in economic variables.</p>
 
 <p>All the response parameters can be used by the tc CLI, but only
-those with a <i>GUI Name</i> appear in the TaxBrain GUI.  All these
+those with a <i>TB Name</i> appear in the TaxBrain GUI.  All these
 dynamic response parameters control advanced features of
 Tax-Calculator, so understanding the
 <a href="https://github.com/open-source-economics/Tax-Calculator/tree/master/taxcalc">source
-code</a> that uses them is essential.</p>
+code</a> that uses them is essential.  Each default parameter value is
+zero and is projected into the future at that value, which implies no
+response to the reform.  Using the default no-reform-response
+assumption for all the response parameters generates a static analysis
+of the tax reform.</p>
 
 
 <h3>Section Contents</h3>

taxcalc/docs/make.py

@@ -5,10 +5,14 @@
 # pep8 --ignore=E402 make.py
 # pylint --disable=locally-disabled make.py
 
-import sys
 import os
+import sys
 import json
 from collections import OrderedDict
+CUR_PATH = os.path.abspath(os.path.dirname(__file__))
+sys.path.append(os.path.join(CUR_PATH, '..', '..'))
+# pylint: disable=wrong-import-position,import-error
+from taxcalc import Policy
 
 CUR_PATH = os.path.abspath(os.path.dirname(__file__))
 INPUT_FILENAME = 'index.htmx'
@@ -57,9 +61,9 @@ def policy_param_text(pname, param):
     else:
         txt = '<p><b>{} &mdash; {}</b>'.format('Other Parameters',
                                                'Not in TaxBrain GUI')
-    txt += '<br><i>CLI Name:</i> {}'.format(pname)
+    txt += '<br><i>tc Name:</i> {}'.format(pname)
     if len(sec1) > 0:
-        txt += '<br><i>GUI Name:</i> {}'.format(param['long_name'])
+        txt += '<br><i>TB Name:</i> {}'.format(param['long_name'])
     else:
         txt += '<br><i>Long Name:</i> {}'.format(param['long_name'])
     txt += '<br><i>Description:</i> {}'.format(param['description'])
@@ -74,7 +78,15 @@ def policy_param_text(pname, param):
         cols = ', '.join(param['col_label'])
         txt += '<br>&nbsp;&nbsp; for: [{}]'.format(cols)
     for cyr, val in zip(param['row_label'], param['value']):
+        final_cyr = cyr
+        final_val = val
         txt += '<br>{}: {}'.format(cyr, val)
+    if not param['cpi_inflated']:
+        fcyr = int(final_cyr)
+        if fcyr < Policy.LAST_KNOWN_YEAR:
+            # extrapolate final_val thru Policy.LAST_KNOWN_YEAR if not indexed
+            for cyr in range(fcyr + 1, Policy.LAST_KNOWN_YEAR + 1):
+                txt += '<br>{}: {}'.format(cyr, final_val)
     txt += '</p>'
     return txt
 
@@ -167,15 +179,15 @@ def response_param_text(pname, ptype, param):
     else:
         txt = '<p><b>{} &mdash; {}</b>'.format('Response Parameter',
                                                ptype.capitalize())
-    txt += '<br><i>CLI Name:</i> {}'.format(pname)
+    txt += '<br><i>tc Name:</i> {}'.format(pname)
     if len(sec1) > 0:
-        txt += '<br><i>GUI Name:</i> {}'.format(param['long_name'])
+        txt += '<br><i>TB Name:</i> {}'.format(param['long_name'])
     else:
         txt += '<br><i>Long Name:</i> {}'.format(param['long_name'])
     txt += '<br><i>Description:</i> {}'.format(param['description'])
     if len(param['notes']) > 0:
         txt += '<br><i>Notes:</i> {}'.format(param['notes'])
-    txt += '<br><i>Default Values:</i>'
+    txt += '<br><i>Default Value:</i>'
     if len(param['col_label']) > 0:
         cols = ', '.join(param['col_label'])
         txt += '<br>&nbsp;&nbsp; for: [{}]'.format(cols)

taxcalc/policy.py

@@ -44,6 +44,7 @@ class instance: Policy
 
     DEFAULTS_FILENAME = 'current_law_policy.json'
     JSON_START_YEAR = 2013  # remains the same unless earlier data added
+    LAST_KNOWN_YEAR = 2017  # last year for which indexed param vals are known
     LAST_BUDGET_YEAR = 2026  # increases by one every calendar year
     DEFAULT_NUM_YEARS = LAST_BUDGET_YEAR - JSON_START_YEAR + 1
 

taxcalc/records_variables.json

@@ -29,7 +29,7 @@
     "RECID": {
       "required": true,
       "type": "int",
-      "desc": "Unique identifier for filing unit",
+      "desc": "Unique identifier for filing unit; appears as RECID variable in tc CLI minimal output",
       "form": {"2013-2016": "private info"}
     },
     "XTOT": {
@@ -444,7 +444,7 @@
     },
     "s006": {
       "type": "float",
-      "desc": "Filing unit sampling weight",
+      "desc": "Filing unit sampling weight; appears as WEIGHT variable in tc CLI minimal output",
       "form": {"2013-2016": "not used in filing unit tax calculations"}
     }
   },
@@ -498,7 +498,7 @@
     },
     "iitax": {
       "type": "float",
-      "desc": "Total federal individual income tax liability",
+      "desc": "Total federal individual income tax liability; appears as INCTAX variable in tc CLI minimal output",
       "form": {"2013-2013": "1040, line 61 minus line 56 minus line 60a",
                "2014-2016": "1040, line 63 minus line 57 minus line 62a"}
     },
@@ -510,7 +510,7 @@
 
     "payrolltax": {
       "type": "float",
-      "desc": "Total (employee + employer) payroll tax liability",
+      "desc": "Total (employee + employer) payroll tax liability; appears as PAYTAX variable in tc CLI minimal output",
       "form": {"2013-2013": "OASDHI FICA plus 1040 lines 56 and 60a",
                "2014-2016": "OASDHI FICA plus 1040 lines 57 and 62a"}
     },
@@ -794,7 +794,7 @@
     },
     "lumpsum_tax": {
       "type": "float",
-      "desc": "Lumpsum (or head) tax",
+      "desc": "Lumpsum (or head) tax; appears as LSTAX variable in tc CLI minimal output",
       "form": {}
     },
     "personal_credit": {

taxcalc/tests/test_parameters.py

@@ -63,7 +63,7 @@ def test_json_file_contents(tests_path, fname):
                'col_var', 'col_label',
                'value']
     first_year = Policy.JSON_START_YEAR
-    last_known_year = 2017  # for indexed parameters
+    last_known_year = Policy.LAST_KNOWN_YEAR  # for indexed parameter values
     num_known_years = last_known_year - first_year + 1
     # read JSON parameter file into a dictionary
     path = os.path.join(tests_path, '..', fname)