Skip to content

Commit

Permalink
Merge pull request #2296 from martinholmer/testing
Browse files Browse the repository at this point in the history
Add instructions on upgrading to Tax-Calculator 2.0
  • Loading branch information
martinholmer authored Apr 15, 2019
2 parents 4e30417 + 57c6b95 commit 8e0b733
Show file tree
Hide file tree
Showing 10 changed files with 134 additions and 43 deletions.
94 changes: 94 additions & 0 deletions UPGRADING.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
Upgrading to Tax-Calculator 2.0
===============================

Tax-Calculator version 2.0 (and higher) is incompatible with earlier
versions. The tax logic is unchanged, but 2.0 introduces a simplified
and standardized way of specifying tax reforms (or economic assumption
changes). This note explains what you have to do in order to use
Tax-Calculator version 2.0 and higher.

What you need to do is change the way you specify tax policy reforms.
Obviously, you need to do this only for reforms you want to analyze
using Tax-Calculator 2.0 and higher.

The details of what to do depend on whether you are in the habit of
specifying reforms in JSON files (as demonstrated in the [user
guide](https://PSLmodels.github.io/Tax-Calculator/index.html) and
[cookbook](https://PSLmodels.github.io/Tax-Calculator/cookbook.html))
or whether you take a low-level approach and specify reforms as Python
dictionaries directly in your Python scripts (as done in hundreds of
Tax-Calculator tests).

In both cases you need to do the following:

1. Remove the leading underscore character from each parameter name.

2. Remove the brackets around the value of scalar parameters (i.e.,
those that do not vary by filing-unit type, number of EITC eligible
children, or type of itemized deduction, and therefore, are just a
single value in any year).

3. Remove **one** of the double set of brackets around the values of
vector parameters(i.e., those that are not scalar parameters).
This will leave vector parameter values enclosed in just one pair
of brackets.

4. Only if you are changing whether a parameter is (wage or price)
indexed for inflation, you need to change the trailing `_cpi`
characters to be `-indexed` (making sure to use a dash and not an
underscore).

5. Only if you are changing CPI offset policy, you need to change the
old parameter name `_cpi_offset` to `CPI_offset`.

That is all that needs to be done to convert JSON reform (or
assumption) files so that they work with Tax-Calculator 2.0 and
higher. (If you have many JSON reform files that you want to convert,
the first three steps may be able to be automated using the
`Tax-Calculator/new_json.py` script, but be sure to read the short
script before using it. If your JSON reform files are not formatted
in the way extected by the `new_json.py` script, then make the changes
in the above steps by hand editing each JSON file.)

If you have specified reforms (or changes in economic assumption
parameters) directly in your Python scripts using dictionaries, then
there is another set of changes you need to make to each of those
dictionaries. In older versions of Tax-Calcualtor, each reform
dictionary was structured using a `year : param : value` format.
Here is an example of the old format after making the changes
listed above:

```
reform = {
2020: {
'SS_Earnings_c': 200000,
2021: {
'SS_Earnings_c': 300000,
'SS_Earnings_c-indexed': False
},
2022: {
'STD': [14000, 28000, 14000, 21000, 28000]
}
}
```

Notice that the primary keys in the above dictionary are years and the
secondary keys are parameter names. Beginning with Tax-Calculator
2.0, that order is reversed making the new `param : year : value`
format consistent with the format of the JSON reform files.

So, the above dictionary needs to be converted (by hand editing) to
the following:

```
reform = {
'SS_Earnings_c': {2020: 200000,
2021: 300000},
'SS_Earnings_c-indexed': {2021: False},
'STD': {2022: [14000, 28000, 14000, 21000, 28000]}
}
```

If you have any problems or questions converting your reforms for
use with Tax-Calculator 2.0, please raise an issue
[here](https://github.com/PSLmodels/Tax-Calculator/issues).
22 changes: 10 additions & 12 deletions docs/cookbook/recipe00.res
Original file line number Diff line number Diff line change
@@ -1,46 +1,44 @@
You loaded data for 2014.
Tax-Calculator startup automatically extrapolated your data to 2014.
You loaded data for 2014.
Tax-Calculator startup automatically extrapolated your data to 2014.

REFORM DOCUMENTATION
Baseline Growth-Difference Assumption Values by Year:
none: using default baseline growth assumptions
none: using default growth assumptions
Response Growth-Difference Assumption Values by Year:
none: using default growth assumptions
Policy Reform Parameter Values by Year:
2020:
_II_em : 1000
II_em : 1000.0
name: Personal and dependent exemption amount
desc: Subtracted from AGI in the calculation of taxable income, per taxpayer
and dependent.
baseline_value: 0.0
_II_rt5 : 0.36
II_rt5 : 0.36
name: Personal income (regular/non-AMT/non-pass-through) tax rate 5
desc: The third highest tax rate, applied to the portion of taxable income
below tax bracket 5 and above tax bracket 4.
baseline_value: 0.32
_II_rt6 : 0.39
II_rt6 : 0.39
name: Personal income (regular/non-AMT/non-pass-through) tax rate 6
desc: The second higher tax rate, applied to the portion of taxable income
below tax bracket 6 and above tax bracket 5.
baseline_value: 0.35
_II_rt7 : 0.41
II_rt7 : 0.41
name: Personal income (regular/non-AMT/non-pass-through) tax rate 7
desc: The tax rate applied to the portion of taxable income below tax
bracket 7 and above tax bracket 6.
baseline_value: 0.37
_PT_rt5 : 0.36
PT_rt5 : 0.36
name: Pass-through income tax rate 5
desc: The third highest tax rate, applied to the portion of income from sole
proprietorships, partnerships and S-corporations below tax bracket 5
and above tax bracket 4.
baseline_value: 0.32
_PT_rt6 : 0.39
PT_rt6 : 0.39
name: Pass-through income tax rate 6
desc: The second higher tax rate, applied to the portion of income from sole
proprietorships, partnerships and S-corporations below tax bracket 6
and above tax bracket 5.
baseline_value: 0.35
_PT_rt7 : 0.41
PT_rt7 : 0.41
name: Pass-through income tax rate 7
desc: The highest tax rate, applied to the portion of income from sole
proprietorships, partnerships and S-corporations below tax bracket 7
Expand Down
2 changes: 0 additions & 2 deletions docs/cookbook/recipe03.res
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
You loaded data for 2014.
Tax-Calculator startup automatically extrapolated your data to 2014.
Filing Units Receiving EITC and Average Positive EITC by AGI Category
AGI Category Num(#M) Avg($K)
[-9e+99, 1) 0.047 1.244
Expand Down
22 changes: 11 additions & 11 deletions docs/cookbook/reformA.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,16 +2,16 @@
// from (0.32, 0.35, 0.37) to (0.36, 0.39, 0.41) beginning in 2020.
{
"policy": {
// raise personal exemption amount and index in subsequent years
"_II_em": {"2020": [1000]},
// raise tax rates in the top three brackets
// ... raise non-AMT rates on non-pass-through income
"_II_rt5": {"2020": [0.36]},
"_II_rt6": {"2020": [0.39]},
"_II_rt7": {"2020": [0.41]},
// ... raise non-AMT rates on pass-through income
"_PT_rt5": {"2020": [0.36]},
"_PT_rt6": {"2020": [0.39]},
"_PT_rt7": {"2020": [0.41]}
// raise personal exemption amount and index in subsequent years
"II_em": {"2020": 1000},
// raise tax rates in the top three brackets
// ... raise non-AMT rates on non-pass-through income
"II_rt5": {"2020": 0.36},
"II_rt6": {"2020": 0.39},
"II_rt7": {"2020": 0.41},
// ... raise non-AMT rates on pass-through income
"PT_rt5": {"2020": 0.36},
"PT_rt6": {"2020": 0.39},
"PT_rt7": {"2020": 0.41}
}
}
4 changes: 2 additions & 2 deletions docs/cookbook/reformB.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
// Raise personal exemption and lower standard deduction beginning in 2020.
{
"policy": {
"_II_em": {"2020": [2000]},
"_STD": {"2020": [[6000, 12000, 6000, 9000, 12000]]}
"II_em": {"2020": 2000},
"STD": {"2020": [6000, 12000, 6000, 9000, 12000]}
}
}
2 changes: 1 addition & 1 deletion docs/index.htmx
Original file line number Diff line number Diff line change
Expand Up @@ -640,7 +640,7 @@ the <kbd>ref3.json</kbd> file, the content of which is:
// after which it continues to be indexed to price inflation.
{
"policy": {
"_II_em": {"2022": [8000]}
"II_em": {"2022": 8000}
}
}
</pre></p>
Expand Down
25 changes: 13 additions & 12 deletions docs/make_index.py
Original file line number Diff line number Diff line change
Expand Up @@ -90,25 +90,25 @@ def policy_param_text(pname, param):
else:
txt += 'False'
txt += '<br><i>Can Be Inflation Indexed:</i> '
if param['cpi_inflatable']:
if param['indexable']:
txt += 'True'
else:
txt += 'False'
txt += '&nbsp;&nbsp;&nbsp;&nbsp; <i>Is Inflation Indexed:</i> '
if param['cpi_inflated']:
if param['indexed']:
txt += 'True'
else:
txt += 'False'
txt += '<br><i>Value Type:</i> {}'.format(param['value_type'])
txt += '<br><i>Known Values:</i>'
if len(param['col_label']) > 0:
cols = ', '.join(param['col_label'])
if len(param.get('vi_vals', [])) > 0:
cols = ', '.join(param['vi_name'])
txt += '<br>&nbsp;&nbsp; for: [{}]'.format(cols)
for cyr, val in zip(param['row_label'], param['value']):
for cyr, val in zip(param['value_yrs'], param['value']):
final_cyr = cyr
final_val = val
txt += '<br>{}: {}'.format(cyr, val)
if not param['cpi_inflated']:
if not param['indexed']:
fcyr = int(final_cyr)
if fcyr < Policy.LAST_KNOWN_YEAR:
# extrapolate final_val thru Policy.LAST_KNOWN_YEAR if not indexed
Expand Down Expand Up @@ -212,9 +212,10 @@ def assumption_param_text(pname, ptype, param):
Extract info from param for pname of ptype and return as HTML string.
"""
# pylint: disable=len-as-condition
sec1 = param['section_1']
sec1 = param.get('section_1', '')
if len(sec1) > 0:
txt = '<p><b>{} &mdash; {}</b>'.format(sec1, param['section_2'])
txt = '<p><b>{} &mdash; {}</b>'.format(sec1,
param.get('section_2', ''))
else:
txt = '<p><b>{} &mdash; {}</b>'.format('Assumption Parameter',
ptype.capitalize())
Expand All @@ -224,13 +225,13 @@ def assumption_param_text(pname, ptype, param):
else:
txt += '<br><i>Long Name:</i> {}'.format(param['long_name'])
txt += '<br><i>Description:</i> {}'.format(param['description'])
if len(param['notes']) > 0:
if len(param.get('notes', '')) > 0:
txt += '<br><i>Notes:</i> {}'.format(param['notes'])
txt += '<br><i>Default Value:</i>'
if len(param['col_label']) > 0:
cols = ', '.join(param['col_label'])
if len(param.get('vi_vals', [])) > 0:
cols = ', '.join(param['vi_vals'])
txt += '<br>&nbsp;&nbsp; for: [{}]'.format(cols)
for cyr, val in zip(param['row_label'], param['value']):
for cyr, val in zip(param['value_yrs'], param['value']):
txt += '<br>{}: {}'.format(cyr, val)
txt += '<br><i>Valid Range:</i>'
minval = param['valid_values']['min']
Expand Down
2 changes: 1 addition & 1 deletion docs/ref3.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,6 @@
// after which it continues to be indexed to price inflation.
{
"policy": {
"_II_em": {"2022": [8000]}
"II_em": {"2022": 8000}
}
}
2 changes: 1 addition & 1 deletion new_json.py
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
"""
Command-line tool that converts Tax-Calculator JSON reform/assumption file
from the old (1.x) format to the new (2.0) format.
from the old (1.x) format to the new (2.0+) format.
------------------------------------------------------------------------
WARNING: This program make certain assumptions about how the JSON file
is formatted, so it will not work correctly on a JSON file
Expand Down
2 changes: 1 addition & 1 deletion taxcalc/tests/test_policy.py
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ def test_policy_json_content_consistency():
# check entries in vi_vals list
vivals = data['vi_vals']
if vivals:
assert set(vivals) == set(expected_vi_vals[data['vi_name']])
assert vivals == expected_vi_vals[data['vi_name']]


# pylint: disable=protected-access,no-member
Expand Down

0 comments on commit 8e0b733

Please sign in to comment.