How to Use Tax-Brain¶
The Tax-Brain package is centered around the TaxBrain
object. Any analysis
using Tax-Brain starts by importing and creating a TaxBrain
instance.
from taxbrain import TaxBrain
tb = TaxBrain(2019, 2029, use_cps=True, reform="reform.json",
assump="assumptions.json", behavior={"sub": 0.25})
TaxBrain
takes the following arguments on initialization:
start_year
: First year in the analysis.end_year
: Last year in the analysis.microdata
*: Either a path to a micro-data CSV file or a Pandas DataFrame containing micro-data suitable for use in Tax-Calculatoruse_cps
*: Boolean indicator for whether to use the CPS micro-data file included in Tax-Calculator. If this is true, do not give a value for themicrodata
argument.reform
*: Individual income tax policy reform. Can either be a string pointing to a JSON file, the contents of a JSON file, or a dictionary.behavior
*: Individual behavioral assumptions used by the Behavioral-Responses package.assump
*: Economic assumptions. Can either be a string pointing to a JSON file, the contents of a JSON file, or a dictionary.verbose
*: Boolean indicator for whether or not to print progress updates as the models run. Default value is False.
* indicates optional argument
Tax-Brain will analyze these inputs to determine which models to run and for
what years. To start the models, the users can simply use the run
method:
tb.run()
This will create two Tax-Calculator instances - one for current law (base) and another for the user specified policy (reform).
run()
also takes an optional argument, varlist
, to indicate which variables
in the micro-data the user would like saved. Pandas DataFrames containing
micro-data from the reform and base calculators are stored in the reform_data
and base_data
, respectively, attributes of the TaxBrain
instance (both
attributes are dictionaries).
The dictionaries are structured so that each year in the analysis is a key paired to the DataFrame for that particular year:
# Access the DataFrame containing data from the reform caclulator for the year 2019
tb.reform_data[2019]
# Access the DataFrame containing data from the base calculator for the year 2020
tb.base_data[2020]
This gives the user the option of performing a more detailed analysis of the data or producing custom tables and graphs. There are also multiple built in methods for producing tables:
weighted_totals(var)
: Produces a table with the weighted sum of the specified variables (var
) for each year in the analysis under the baseline policy, reform policy, and the difference between the two.`distribution_table(year, groupby, income_measure, calc): Produces a table showing the distribution of a number of variables across the income spectrum.
differences_table(year, groupby, tax_to_diff)
: Produces a table showing the change in a number of variables across the income distribution.
Stacked Reforms¶
TaxBrain also can produce stacked revenue estimates. To use this feature, simply modify your reform dictionary so that each key is the name of a section of your reform and each item is the associated reform provisions, as shown below.
payroll_json = """{"SS_Earnings_thd": {"2021": 400000}}"""
CG_rate_json = """{
"CG_brk3": {"2021": [1000000, 1000000, 1000000, 1000000, 1000000]},
"CG_rt4": {"2021": 0.396}
}"""
reform_dict = {
"Payroll Threshold Increase": payroll_json,
"Capital Gains Tax Changes": CG_rate_json
}
tb = TaxBrain(2021, 2022, reform=reform_dict, stacked=True, use_cps=True)
tb.run()
tb.stacked_table * 1e-9
This code will produce the following table:
2021 |
2022 |
2021-2022 |
|
---|---|---|---|
Payroll Threshold Increase |
65.97 |
70.9 |
136.87 |
Capital Gains Tax Changes |
19.57 |
18.95 |
38.52 |
Total |
85.54 |
89.85 |
175.39 |
As more models are added, Tax-Brain’s usage will change to adjust. While we will try and maintain backwards compatibility, that obviously cannot always happen. This document will be updated as Tax-Brain evolves.