Tax-Calculator Public API¶

The Tax-Calculator’s core capabilities are in the Python package called taxcalc, the source code for which is located in the tax-calculator/taxcalc directory tree.

Here we provide a high-level view of the public API of the taxcalc conda package with links to the source code. This high-level view is organized around the modules in the taxcalc package. Below is a list of the taxcalc package modules (in alphabetical order) with documentation about how to call each public class method and function. There is also a link to the source code for each documented member. However, it may be more convenient to access this list interactively via the alphabetical Index of taxcalc members.

Developers who want to use Tax-Calculator capabilities in their own projects should restrict themselves to using this public API. All other Tax-Calculator members are private and subject to change without advance notice.

taxcalc.Behavior¶

class taxcalc.Behavior(start_year=2013, num_years=15)[source]

Behavior is a subclass of the abstract Parameters class, and therefore, inherits its methods (none of which are shown here).

Constructor for elasticity-based behavioral-response class.

WARNING: the Behavior class is deprecated and will be removed soon. FUTURE: use the Behavioral-Responses behresp package OR

use the Tax-Calculator quantity_response function.
Parameters: start_year (integer) – first calendar year for behavioral-response elasticities. num_years (integer) – number of calendar years for which to specify elasticity values beginning with start_year. ValueError: – if start_year is less than Policy.JSON_START_YEAR if num_years is less than one. class instance Behavior
static _mtr12(calc1, calc2, mtr_of='e00200p', tax_type='combined')[source]

Computes marginal tax rates for Calculator objects calc1 and calc2 for specified mtr_of income type and specified tax_type.

static _update_cap_gain_income(cap_gain_change, calc)[source]

Implement capital gain change induced by behavioral responses.

static _update_ordinary_income(taxinc_change, calc)[source]

Implement total taxable income change induced by behavioral response.

has_any_response()[source]

Returns true if any behavioral-response elasticity is non-zero in any year; returns false if all elasticities are zero in all years.

has_response()[source]

Returns true if any behavioral-response elasticity is non-zero for the current_year; returns false if all elasticities are zero.

static response(calc1, calc2, trace=False)[source]

Implements TaxBrain “Partial Equilibrium Simulation” dynamic analysis.

Modify calc2 records to account for behavioral responses that arise
from the policy reform that involves moving from calc1 policy to calc2 policy. Neither calc1 nor calc2 need to have had calc_all() executed before calling the Behavior.response(calc1, calc2) method.
Returns new Calculator object — a deepcopy of calc2 — that
incorporates behavioral responses to the reform.
Note: the use here of a dollar-change income elasticity (rather than
a proportional-change elasticity) is consistent with Feldstein and Feenberg, “The Taxation of Two Earner Families”, NBER Working Paper No. 5155 (June 1995). A proportional-change elasticity was used by Gruber and Saez, “The elasticity of taxable income: evidence and implications”, Journal of Public Economics 84:1-32 (2002) [see equation 2 on page 10].
Note: the nature of the capital-gains elasticity used here is similar
to that used in Joint Committee on Taxation, “New Evidence on the Tax Elasticity of Capital Gains: A Joint Working Paper of the Staff of the Joint Committee on Taxation and the Congressional Budget Office”, (JCX-56-12), June 2012. In particular, the elasticity use here is equivalent to the term inside the square brackets on the right-hand side of equation (4) on page 11 — not the epsilon variable on the left-hand side of equation (4), which is equal to the elasticity used here times the weighted average marginal tax rate on long-term capital gains. So, the JCT-CBO estimate of -0.792 for the epsilon elasticity (see JCT-CBO, Table 5) translates into a much larger absolute value for the _BE_cg semi-elasticity used by Tax-Calculator. To calculate the elasticity from a semi-elasticity, we multiply by MTRs from TC and weight by shares of taxable gains. To avoid those with zero MTRs, we restrict this to the top 40% of tax units by AGI. Using this method, a semi-elasticity of -3.45 corresponds to a tax rate elasticity of -0.792.
update_behavior(revision)[source]

Implement multi-year behavior revision leaving current_year unchanged.

Parameters: revision (dictionary of one or more YEAR:MODS pairs) – see Notes to Parameters _update method for info on MODS structure ValueError: – if revision is not a dictionary. if each YEAR in revision is not an integer. if minimum YEAR in the YEAR:MODS pairs is less than start_year. if minimum YEAR in the YEAR:MODS pairs is less than current_year. if maximum YEAR in the YEAR:MODS pairs is greater than end_year. if _validate_assump_parameter_names_types generates errors. if _validate_assump_parameter_values generates errors. nothing void

Notes

Given a revision dictionary, typical usage of the Policy class is as follows:

behavior = Behavior()
behavior.update_behavior(revision)


In the above statements, the Behavior() call instantiates a behavior object (behavior) containing behavior baseline parameters, and the update_behavior(revision) call applies the (possibly multi-year) revision specified in revision and then sets the current_year to the value of current_year when update_behavior was called with parameters set for that pre-call year.

An example of a multi-year, multi-parameter revision is as follows:

revision = {
2016: {
'_BE_inc': [-0.3]
},
2017: {
'_BE_sub': [0.2]
}
}


Notice that each of the four YEAR:MODS pairs is specified as required by the private _update method, whose documentation provides several MODS dictionary examples.

IMPORTANT NOTICE: when specifying a revision dictionary always group all revision provisions for a specified year into one YEAR:MODS pair. If you make the mistake of specifying two or more YEAR:MODS pairs with the same YEAR value, all but the last one will be overwritten, and therefore, not part of the revision. This is because Python expects unique (not multiple) dictionary keys. There is no way to catch this error, so be careful to specify revision dictionaries correctly.

taxcalc.Calculator¶

class taxcalc.Calculator(policy=None, records=None, verbose=True, sync_years=True, consumption=None, behavior=None)[source]

Constructor for the Calculator class.

Parameters: policy (Policy class object) – this argument must be specified and object is copied for internal use records (Records class object) – this argument must be specified and object is copied for internal use verbose (boolean) – specifies whether or not to write to stdout data-loaded and data-extrapolated progress reports; default value is true. sync_years (boolean) – specifies whether or not to synchronize policy year and records year; default value is true. consumption (Consumption class object) – specifies consumption response assumptions used to calculate “effective” marginal tax rates; default is None, which implies no consumption responses assumed in marginal tax rate calculations; when argument is an object it is copied for internal use; also specifies consumption value of in-kind benefis with no in-kind consumption values specified implying consumption value is equal to government cost of providing the in-kind benefits behavior (Behavior class object) – specifies behavioral responses used by Calculator; default is None, which implies no behavioral responses to policy reform; when argument is an object it is copied for internal use ValueError: – if parameters are not the appropriate type. class instance Calculator

Notes

The most efficient way to specify current-law and reform Calculator objects is as follows:

pol = Policy() rec = Records() calc1 = Calculator(policy=pol, records=rec) # current-law pol.implement_reform(…) calc2 = Calculator(policy=pol, records=rec) # reform

All calculations are done on the internal copies of the Policy and Records objects passed to each of the two Calculator constructors.

static _convert_parameter_dict(param_key_dict)[source]

Converts specified param_key_dict into a dictionary whose primary keys are calendar years, and hence, is suitable as the argument to the Policy.implement_reform() method, or the Consumption.update_consumption() method, or the Behavior.update_behavior() method, or the GrowDiff.update_growdiff() method, or the GrowModel.update_growmodel() method.

Specified input dictionary has string parameter primary keys and string years as secondary keys.

Returned dictionary has integer years as primary keys and string parameters as secondary keys.

static _read_json_econ_assump_text(text_string)[source]

Strip //-comments from text_string and return 5 dict based on the JSON.

Specified text is JSON with at least 5 high-level key:value pairs: a “consumption”: {…} pair, a “behavior”: {…} pair, a “growdiff_baseline”: {…} pair, a “growdiff_response”: {…} pair, and a “growmodel”: {…} pair.

Other keys such as “policy” will raise a ValueError.

The {…} object may be empty (that is, be {}), or may contain one or more pairs with parameter string primary keys and string years as secondary keys. See tests/test_calculator.py for an extended example of a commented JSON economic assumption text that can be read by this method.

Note that an example is shown in the ASSUMP_CONTENTS string in the tests/test_calculator.py file.

Returned dictionaries (cons_dict, behv_dict, gdiff_baseline_dict, gdiff_respose_dict, growmodel_dict) have integer years as primary keys and string parameters as secondary keys.

These returned dictionaries are suitable as the arguments to the Consumption.update_consumption(cons_dict) method, or the Behavior.update_behavior(behv_dict) method, or the GrowDiff.update_growdiff(gdiff_dict) method, or the GrowModel.update_growmodel(growmodel_dict) method.

static _read_json_policy_reform_text(text_string, growdiff_baseline_dict, growdiff_response_dict)[source]

Strip //-comments from text_string and return 1 dict based on the JSON.

Specified text is JSON with at least 1 high-level key:object pair: a “policy”: {…} pair.

Other keys such as “consumption”, “behavior”, “growdiff_baseline”, “growdiff_response” or “growmodel” will raise a ValueError.

The {…} object may be empty (that is, be {}), or may contain one or more pairs with parameter string primary keys and string years as secondary keys. See tests/test_calculator.py for an extended example of a commented JSON policy reform text that can be read by this method.

Returned dictionary prdict has integer years as primary keys and string parameters as secondary keys. This returned dictionary is suitable as the argument to the Policy implement_reform(prdict) method.

advance_to_year(year)[source]

The advance_to_year function gives an optional way of implementing increment year functionality by immediately specifying the year as input. New year must be at least the current year.

array(variable_name, variable_value=None)[source]
If variable_value is None, return numpy ndarray containing the
named variable in embedded Records object.
If variable_value is not None, set named variable in embedded Records
object to specified variable_value and return None (which can be ignored).
array_len

Length of arrays in embedded Records object.

atr_graph(calc, mars='ALL', atr_measure='combined')[source]

Create average tax rate graph that can be written to an HTML file (using the write_graph_file utility function) or shown on the screen immediately in an interactive or notebook session (following the instructions in the documentation of the xtr_graph_plot utility function). The graph shows the mean average tax rate for each expanded-income percentile excluding any percentile that includes a filing unit with negative or zero basline (self) expanded income.

Parameters: calc (Calculator object) – calc represents the reform while self represents the baseline, where both self and calc have calculated taxes for this year before being used by this method mars (integer or string) – specifies which filing status subgroup to show in the graph ’ALL’: include all filing units in sample 1: include only single filing units 2: include only married-filing-jointly filing units 3: include only married-filing-separately filing units 4: include only head-of-household filing units atr_measure (string) – specifies which average tax rate to show on graph’s y axis ’itax’: average individual income tax rate ’ptax’: average payroll tax rate ’combined’: sum of average income and payroll tax rates graph that is a bokeh.plotting figure object
behavior(param_name, param_value=None)[source]
If param_value is None, return named parameter in
embedded Behavior object.
If param_value is not None, set named parameter in
embedded Behavior object to specified param_value and return None (which can be ignored).
behavior_has_response()[source]

Return True if embedded Behavior object has response; otherwise return False.

calc_all(zero_out_calc_vars=False)[source]

Call all tax-calculation functions for the current_year.

ce_aftertax_income(calc, custom_params=None, require_no_agg_tax_change=True)[source]

Return dictionary that contains certainty-equivalent of the expected utility of after-tax expanded income computed for several constant-relative-risk-aversion parameter values for each of two Calculator objects: self, which represents the pre-reform situation, and calc, which represents the post-reform situation, both of which MUST have had calc_call() called before being passed to this function.

IMPORTANT NOTES: These normative welfare calculations are very simple. It is assumed that utility is a function of only consumption, and that consumption is equal to after-tax income. This means that any assumed behavioral responses that change work effort will not affect utility via the correpsonding change in leisure. And any saving response to changes in after-tax income do not affect consumption.

The cmin value is the consumption level below which marginal utility is considered to be constant. This allows the handling of filing units with very low or even negative after-tax expanded income in the expected-utility and certainty-equivalent calculations.

consump_benval_params()[source]

Return list of benefit-consumption-value parameter values in embedded Consumption object.

consump_param(param_name)[source]

Return value of named parameter in embedded Consumption object.

current_year

Calculator class current calendar year property.

data_year

Calculator class initial (i.e., first) records data year property.

dataframe(variable_list)[source]

Return Pandas DataFrame containing the listed variables from embedded Records object.

decile_graph(calc, include_zero_incomes=True, include_negative_incomes=True)[source]

Create graph that shows percentage change in aftertax expanded income (from going from policy in self to policy in calc) for each expanded-income decile and subgroups of the top decile. The graph can be written to an HTML file (using the write_graph_file utility function) or shown on the screen immediately in an interactive or notebook session (following the instructions in the documentation of the xtr_graph_plot utility function). NOTE: this method calls the distribution_tables method to

compute the values of the graphed statistic; consult that method for details on how the values are computed.
Parameters: calc (Calculator object) – calc represents the reform while self represents the baseline, where both self and calc have calculated taxes for this year before being used by this method include_zero_incomes (boolean) – if True (which is the default), the bottom decile does contain filing units with zero expanded_income; if False, the bottom decile does not contain filing units with zero expanded_income. include_negative_incomes (boolean) – if True (which is the default), the bottom decile does contain filing units with negative expanded_income; if False, the bottom decile does not contain filing units with negative expanded_income. graph that is a bokeh.plotting figure object
diagnostic_table(num_years)[source]

Generate multi-year diagnostic table containing aggregate statistics; this method leaves the Calculator object unchanged.

Parameters: num_years (Integer) – number of years to include in diagnostic table starting with the Calculator object’s current_year (must be at least one and no more than what would exceed Policy end_year) Pandas DataFrame object containing the multi-year diagnostic table
difference_table(calc, groupby, tax_to_diff)[source]

Get results from self and calc, sort them by expanded_income into table rows defined by groupby, compute grouped statistics, and return tax-difference table as a Pandas dataframe. This method leaves the Calculator objects unchanged. Note that the returned tables have consistent income groups (based on the self expanded_income) even though the baseline expanded_income in self and the reform expanded_income in calc are different.

Parameters: calc (Calculator object) – calc represents the reform while self represents the baseline groupby (String object) – options for input: ‘weighted_deciles’, ‘standard_income_bins’ determines how the columns in resulting Pandas DataFrame are sorted tax_to_diff (String object) – options for input: ‘iitax’, ‘payrolltax’, ‘combined’ specifies which tax to difference and typical usage (Returns) – ------------------------- – = calc1.difference_table(calc2, 'weighted_deciles', 'iitax') (diff) – calc1 is a baseline Calculator object ((where) – calc2 is a reform Calculator object) (and) – returned diff is a difference table as a Pandas DataFrame (The) – DIST_TABLE_COLUMNS and groupby rows. (with) – NOTE (when groupby is 'weighted_deciles', the returned table has three) – extra rows containing top-decile detail consisting of statistics for the 0.90-0.95 quantile range (bottom half of top decile), for the 0.95-0.99 quantile range, and for the 0.99-1.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 0-10n row label), zero (denoted by a 0-10z row label), and positive (denoted by a 0-10p row label) values of the specified income_measure.
distribution_table_dataframe()[source]

Return pandas DataFrame containing the DIST_TABLE_COLUMNS variables from embedded Records object.

distribution_tables(calc, groupby, scaling=True)[source]

Get results from self and calc, sort them by expanded_income into table rows defined by groupby, compute grouped statistics, and return tables as a pair of Pandas dataframes. This method leaves the Calculator object(s) unchanged. Note that the returned tables have consistent income groups (based on the self expanded_income) even though the baseline expanded_income in self and the reform expanded_income in calc are different.

Parameters: calc (Calculator object or None) – typically represents the reform while self represents the baseline; if calc is None, the second returned table is None groupby (String object) – options for input: ‘weighted_deciles’, ‘standard_income_bins’ determines how the columns in resulting Pandas DataFrame are sorted scaling (boolean) – specifies create_distribution_table utility function argument that determines whether table entries are scaled or not and typical usage (Return) – ------------------------ – dist2 = calc1.distribution_tables(calc2, 'weighted_deciles') (dist1,) – OR – _ = calc1.distribution_tables(None, 'weighted_deciles') (dist1,) – calc1 is a baseline Calculator object ((where) – calc2 is a reform Calculator object) (and) – of the dist1 and optional dist2 is a distribution table as a (Each) – DataFrame with DIST_TABLE_COLUMNS and groupby rows. (Pandas) – NOTE (when groupby is 'weighted_deciles', the returned tables have 3) – extra rows containing top-decile detail consisting of statistics for the 0.90-0.95 quantile range (bottom half of top decile), for the 0.95-0.99 quantile range, and for the 0.99-1.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 0-10n row label), zero (denoted by a 0-10z row label), and positive (denoted by a 0-10p row label) values of the specified income_measure.
incarray(variable_name, variable_add)[source]

increment_year()[source]

Advance all embedded objects to next year.

mtr(variable_str='e00200p', negative_finite_diff=False, zero_out_calculated_vars=False, calc_all_already_called=False, wrt_full_compensation=True)[source]

Calculates the marginal payroll, individual income, and combined tax rates for every tax filing unit, leaving the Calculator object in exactly the same state as it would be in after a calc_all() call.

The marginal tax rates are approximated as the change in tax liability caused by a small increase (the finite_diff) in the variable specified by the variable_str divided by that small increase in the variable, when wrt_full_compensation is false.

If wrt_full_compensation is true, then the marginal tax rates are computed as the change in tax liability divided by the change in total compensation caused by the small increase in the variable (where the change in total compensation is the sum of the small increase in the variable and any increase in the employer share of payroll taxes caused by the small increase in the variable).

If using ‘e00200s’ as variable_str, the marginal tax rate for all records where MARS != 2 will be missing. If you want to perform a function such as np.mean() on the returned arrays, you will need to account for this.

Parameters: variable_str (string) – specifies type of income or expense that is increased to compute the marginal tax rates. See Notes for list of valid variables. negative_finite_diff (boolean) – specifies whether or not marginal tax rates are computed by subtracting (rather than adding) a small finite_diff amount to the specified variable. zero_out_calculated_vars (boolean) – specifies value of zero_out_calc_vars parameter used in calls of Calculator.calc_all() method. calc_all_already_called (boolean) – specifies whether self has already had its Calculor.calc_all() method called, in which case this method will not do a final calc_all() call but use the incoming embedded Records object as the outgoing Records object embedding in self. wrt_full_compensation (boolean) – specifies whether or not marginal tax rates on earned income are computed with respect to (wrt) changes in total compensation that includes the employer share of OASDI and HI payroll taxes. A tuple of numpy arrays in the following order mtr_payrolltax (an array of marginal payroll tax rates.) mtr_incometax (an array of marginal individual income tax rates.) mtr_combined (an array of marginal combined tax rates, which is) – the sum of mtr_payrolltax and mtr_incometax.

Notes

The arguments zero_out_calculated_vars and calc_all_already_called cannot both be true.

Valid variable_str values are: ‘e00200p’, taxpayer wage/salary earnings (also included in e00200); ‘e00200s’, spouse wage/salary earnings (also included in e00200); ‘e00900p’, taxpayer Schedule C self-employment income (also in e00900); ‘e00300’, taxable interest income; ‘e00400’, federally-tax-exempt interest income; ‘e00600’, all dividends included in AGI ‘e00650’, qualified dividends (also included in e00600) ‘e01400’, federally-taxable IRA distribution; ‘e01700’, federally-taxable pension benefits; ‘e02000’, Schedule E total net income/loss ‘e02400’, all social security (OASDI) benefits; ‘p22250’, short-term capital gains; ‘p23250’, long-term capital gains; ‘e18500’, Schedule A real-estate-tax paid; ‘e19200’, Schedule A interest paid; ‘e26270’, S-corporation/partnership income (also included in e02000); ‘e19800’, Charity cash contributions; ‘e20100’, Charity non-cash contributions.

mtr_graph(calc, mars='ALL', mtr_measure='combined', mtr_variable='e00200p', alt_e00200p_text='', mtr_wrt_full_compen=False, income_measure='expanded_income', dollar_weighting=False)[source]

Create marginal tax rate graph that can be written to an HTML file (using the write_graph_file utility function) or shown on the screen immediately in an interactive or notebook session (following the instructions in the documentation of the xtr_graph_plot utility function).

Parameters: calc (Calculator object) – calc represents the reform while self represents the baseline mars (integer or string) – specifies which filing status subgroup to show in the graph ’ALL’: include all filing units in sample 1: include only single filing units 2: include only married-filing-jointly filing units 3: include only married-filing-separately filing units 4: include only head-of-household filing units mtr_measure (string) – specifies which marginal tax rate to show on graph’s y axis ’itax’: marginal individual income tax rate ’ptax’: marginal payroll tax rate ’combined’: sum of marginal income and payroll tax rates mtr_variable (string) – any string in the Calculator.VALID_MTR_VARS set specifies variable to change in order to compute marginal tax rates alt_e00200p_text (string) – text to use in place of mtr_variable when mtr_variable is ‘e00200p’; if empty string then use ‘e00200p’ mtr_wrt_full_compen (boolean) – see documentation of Calculator.mtr() argument wrt_full_compensation (value has an effect only if mtr_variable is ‘e00200p’) income_measure (string) – specifies which income variable to show on the graph’s x axis ’wages’: wage and salary income (e00200) ’agi’: adjusted gross income, AGI (c00100) ’expanded_income’: broader than AGI (see definition in calcfunctions.py file). dollar_weighting (boolean) – False implies both income_measure percentiles on x axis and mtr values for each percentile on the y axis are computed without using dollar income_measure weights (just sampling weights); True implies both income_measure percentiles on x axis and mtr values for each percentile on the y axis are computed using dollar income_measure weights (in addition to sampling weights). Specifying True produces a graph x axis that shows income_measure (not filing unit) percentiles. graph that is a bokeh.plotting figure object
n65()[source]

Return numpy ndarray containing the number of individuals age 65+ in each filing unit.

pch_graph(calc)[source]

Create percentage change in after-tax expanded income graph that can be written to an HTML file (using the write_graph_file utility function) or shown on the screen immediately in an interactive or notebook session (following the instructions in the documentation of the xtr_graph_plot utility function). The graph shows the dollar-weighted mean percentage change in after-tax expanded income for each expanded-income percentile excluding any percentile that includes a filing unit with negative or zero basline (self) expanded income.

Parameters: calc (Calculator object) – calc represents the reform while self represents the baseline, where both self and calc have calculated taxes for this year before being used by this method graph that is a bokeh.plotting figure object
policy_current_year(year=None)[source]

If year is None, return current_year of embedded Policy object. If year is not None, set embedded Policy current_year to year and

return None (which can be ignored).
policy_param(param_name, param_value=None)[source]
If param_value is None, return named parameter in
embedded Policy object.
If param_value is not None, set named parameter in
embedded Policy object to specified param_value and return None (which can be ignored).
static read_json_assumptions(assump)[source]

Read JSON assump object and return one dictionary that has the same structure as each subdictionary returned by the Calculator.read_json_param_objects method.

Note that the assump argument can be None, in which case the returned dictionary is empty. Also note that the assump argument can be a string containing a local file name, URL beginning with ‘http’, or valid JSON string.

The assump file/URL contents or JSON string must be like the structure required for each subsection of the assump argument of the Calculator.read_json_param_objects method.

static read_json_param_objects(reform, assump)[source]

Read JSON reform and assump objects and return a single dictionary containing 6 key:dict pairs: ‘policy’:dict, ‘consumption’:dict, ‘behavior’:dict, ‘growdiff_baseline’:dict, ‘growdiff_response’:dict, and ‘growmodel’:dict.

Note that either of the two function arguments can be None. If reform is None, the dict in the ‘policy’:dict pair is empty. If assump is None, the dict in all the other key:dict pairs is empty.

Also note that either of the two function arguments can be strings containing a valid JSON string (rather than a local filename), in which case the file reading is skipped and the appropriate read_json_*_text method is called.

Either of the two function arguments can also be a valid URL string beginning with ‘http’ and pointing to a valid JSON file hosted online.

The reform file/URL contents or JSON string must be like this: {“policy”: {…}} and the assump file/URL contents or JSON string must be like this: {“consumption”: {…},

“behavior”: {…}, “growdiff_baseline”: {…}, “growdiff_response”: {…}, “growmodel”: {…}}

The {…} should be empty like this {} if not specifying a policy reform or if not specifying any non-default economic assumptions of that type.

The ‘policy’ subdictionary of the returned dictionary is suitable as input into the Policy.implement_reform method.

The ‘consumption’ subdictionary of the returned dictionary is suitable as input into the Consumption.update_consumption method.

The ‘growdiff_baseline’ subdictionary of the returned dictionary is suitable as input into the GrowDiff.update_growdiff method.

The ‘growdiff_response’ subdictionary of the returned dictionary is suitable as input into the GrowDiff.update_growdiff method.

records_current_year(year=None)[source]

If year is None, return current_year of embedded Records object. If year is not None, set embedded Records current_year to year and

return None (which can be ignored).
records_include_behavioral_responses()[source]

Mark embedded Records object as including behavioral responses

static reform_documentation(params, policy_dicts=None)[source]

Generate reform documentation.

Parameters: params (dict) – dictionary is structured like dict returned from the static Calculator method read_json_param_objects() policy_dicts (list of dict or None) – each dictionary in list is a params[‘policy’] dictionary representing second and subsequent elements of a compound reform; None implies no compound reform with the simple reform characterized in the params[‘policy’] dictionary doc – the documentation for the policy reform specified in params String
reform_warnings

Calculator class embedded Policy object’s reform_warnings.

restore_records()[source]

Set the embedded Records object to the stored Records object that was saved in the last call to the store_records() method.

store_records()[source]

Make internal copy of embedded Records object that can then be restored after interim calculations that make temporary changes to the embedded Records object.

total_weight()[source]

Return all-filing-unit total of sampling weights. NOTE: var_weighted_mean = calc.weighted_total(var)/calc.total_weight()

weighted_total(variable_name)[source]

Return all-filing-unit weighted total of named Records variable.

zeroarray(variable_name)[source]

Set named variable in embedded Records object to zeros.

taxcalc.cli.tc¶

Command-line interface (CLI) to Tax-Calculator, which can be accessed as ‘tc’ from an installed taxcalc conda package.

taxcalc.cli.tc._write_expected_test_output()[source]

Private function that writes tc –test input and expected output files.

taxcalc.cli.tc.cli_tc_main()[source]

Contains command-line interface (CLI) to Tax-Calculator TaxCalcIO class.

taxcalc.Consumption¶

class taxcalc.Consumption[source]

Consumption is a subclass of the abstract Parameters class, and therefore, inherits its methods (none of which are shown here).

Constructor for Consumption class.

Parameters: none – class instance Consumption
benval_params()[source]

Returns list of BEN_*_value parameter values

has_response()[source]

Return true if any MPC parameters are positive for current_year or if any BEN value parameters are less than one for current_year; return false if all MPC parameters are zero and all BEN value parameters are one

response(records, income_change)[source]

Changes consumption-related records variables given income_change and the current values of the MPC consumption parameters

update_consumption(revision)[source]

Update consumption for given revision, a dictionary consisting of one or more year:modification dictionaries. For example: {2014: {‘_MPC_xxx’: [0.2, 0.1]}}

Note that this method uses the specified revision to update the default MPC parameter values and the default BEN parameter values, so use this method just once rather than calling it sequentially in an attempt to update the parameters in several steps.

taxcalc.decorators¶

Implement numba JIT decorators used to speed-up Tax-Calculator functions in the calcfunctions.py module.

class taxcalc.decorators.GetReturnNode[source]

A NodeVisitor to get the return tuple names from a calc-style function.

visit_Return(node)[source]

visit_Return is used by NodeVisitor.visit method.

taxcalc.decorators.apply_jit(dtype_sig_out, dtype_sig_in, parameters=None, **kwargs)[source]

Make a decorator that takes in a calc-style function, handle apply step.

taxcalc.decorators.create_apply_function_string(sigout, sigin, parameters)[source]

Create a string for a function of the form:

def ap_fuc(x_0, x_1, x_2, ...):
for i in range(len(x_0)):
x_0[i], ... = jitted_f(x_j[i], ...)
return x_0[i], ...


where the specific args to jitted_f and the number of values to return is determined by sigout and sigin.

Parameters: sigout (iterable of the out arguments) – sigin (iterable of the in arguments) – parameters (iterable of which of the args (from in_args) are parameter) – variables (as opposed to column records). This influences how we construct the apply-style function a String representing the function
taxcalc.decorators.create_toplevel_function_string(args_out, args_in, pm_or_pf)[source]

Create a string for a function of the form:

def hl_func(x_0, x_1, x_2, …):
Parameters: args_out (iterable of the out arguments) – args_in (iterable of the in arguments) – pm_or_pf (iterable of strings for object that holds each arg) – a String representing the function
taxcalc.decorators.id_wrapper(*dec_args, **dec_kwargs)[source]

Function wrapper when numba package is not available or when debugging

taxcalc.decorators.iterate_jit(parameters=None, **kwargs)[source]

Public decorator for a calc-style function (see calcfunctions.py) that transforms the calc-style function into an apply-style function that can be called by Calculator class methods (see calculator.py).

taxcalc.decorators.make_apply_function(func, out_args, in_args, parameters, do_jit=True, **kwargs)[source]

Takes a calc-style function and creates the necessary Python code for an apply-style function. Will also jit the function if desired.

Parameters: func (the calc-style function) – out_args (list of out arguments for the apply-style function) – in_args (list of in arguments for the apply-style function) – parameters (iterable of which of the args (from in_args) are parameter) – variables (as opposed to column records). This influences how we construct the apply-style function. do_jit (Bool, if True, jit the resulting apply-style function) – apply-style function

taxcalc.Parameters¶

class taxcalc.Parameters[source]

Inherit from this class for Policy, Behavior, Consumption, GrowDiff, and other groups of parameters that need to have a set_year method. Override this __init__ method and DEFAULTS_FILENAME.

static _expand_1D(x, inflate, inflation_rates, num_years)[source]

Private method called only from _expand_array method. Expand the given data x to account for given number of budget years. If necessary, pad out additional years by increasing the last given year using the given inflation_rates list.

static _expand_2D(x, inflate, inflation_rates, num_years)[source]

Private method called only from _expand_array method. Expand the given data to account for the given number of budget years. For 2D arrays, we expand out the number of rows until we have num_years number of rows. For each expanded row, we inflate using the given inflation rates list.

static _expand_array(x, x_int, x_bool, inflate, inflation_rates, num_years)[source]

Private method called only within this abstract base class. Dispatch to either _expand_1D or _expand_2D given dimension of x.

Parameters: x (value to expand) – x must be either a scalar list or a 1D numpy array, or x must be either a list of scalar lists or a 2D numpy array x_int (boolean) – True implies x has dtype=np.int8; False implies x has dtype=np.float64 or dtype=np.bool_ x_bool (boolean) – True implies x has dtype=np.bool_; False implies x has dtype=np.float64 or dtype=np.int8 inflate (boolean) – As we expand, inflate values if this is True, otherwise, just copy inflation_rates (list of inflation rates) – Annual decimal inflation rates num_years (int) – Number of budget years to expand expanded numpy array with specified dtype
classmethod _params_dict_from_json_file()[source]

Read DEFAULTS_FILENAME file and return complete dictionary.

Parameters: nothing (void) – params – containing complete contents of DEFAULTS_FILENAME file. dictionary
_validate_assump_parameter_names_types(revision)[source]

Check validity of assumption parameter names and parameter types used in the specified revision dictionary.

_validate_assump_parameter_values(parameters_set)[source]

Check values of assumption parameters in specified parameter_set.

current_year

Parameters class current calendar year property.

classmethod default_data(metadata=False)[source]

Return parameter data read from the subclass’s json file.

Parameters: metadata (boolean) – params dictionary of data
end_year

Parameters class lasst parameter year property.

indexing_rates(param_name)[source]

Return appropriate indexing rates for specified param_name.

inflation_rates()[source]

Override this method in subclass when appropriate.

initialize(start_year, num_years)[source]

Called from subclass __init__ function.

num_years

Parameters class number of parameter years property.

static param_dict_for_year(cyear, param_dict, param_info)[source]

Set parameters to their values for the specified calendar year.

Parameters: cyear (int) – calendar year for which to set parameter values param_dict (dict) – dictionary returned by the Calculator.read_json_assumptions method param_info (dict) – dictionary of information about each parameter that can be used in param_dict, where information about each parameter must include at a minimum the following key-value pairs: ‘default_value’: ‘minimum_value’: ‘maximum_value’: param_values_for_year – dictionary containing a key:value pair for each parameter in the param_info dictionary, where each pair looks like this: ‘’: dict
set_default_vals(known_years=999999)[source]

Called by initialize method and from some subclass methods.

set_year(year)[source]

Set parameters to their values for the specified calendar year.

Parameters: year (int) – calendar year for which to set current_year and parameter values ValueError: – if year is not in [start_year, end_year] range. nothing void

Notes

To increment the current year, use the following statement:

behavior.set_year(behavior.current_year + 1)


where, in this example, behavior is a Behavior object.

start_year

Parameters class first parameter year property.

wage_growth_rates()[source]

Override this method in subclass when appropriate.

taxcalc.Policy¶

class taxcalc.Policy(gfactors=None)[source]

Policy is a subclass of the abstract Parameters class, and therefore, inherits its methods (none of which are shown here).

Constructor for the federal tax policy class.

Parameters: gfactors (GrowFactors class instance) – containing price inflation rates and wage growth rates ValueError: – if gfactors is not a GrowFactors class instance or None. class instance Policy
_apply_clp_cpi_offset(cpi_offset_clp_data, num_years)[source]

Call this method from Policy constructor after self._inflation_rates has been set and before base class initialize method is called. (num_years is number of years for which inflation rates are specified)

_apply_reform_cpi_offset(reform)[source]

Call this method ONLY if _cpi_offset_in_reform returns True. Apply CPI offset to inflation rates and revert indexed parameter values in preparation for re-indexing. Also, return known_years which is (first cpi_offset year - start year + 1).

static _cpi_offset_in_reform(reform)[source]

Return true if cpi_offset is in reform; otherwise return false.

_validate_parameter_names_types(reform)[source]

Check validity of parameter names and parameter types used in the specified reform dictionary.

_validate_parameter_values(parameters_set)[source]

Check values of parameters in specified parameter_set using range information from the policy_current_law.json file.

ignore_reform_errors()[source]

Sets self._ignore_errors to True.

implement_reform(reform, print_warnings=False, raise_errors=True)[source]

Implement multi-year policy reform and leave current_year unchanged.

Parameters: reform (dictionary of one or more YEAR:MODS pairs) – see Notes to Parameters _update method for info on MODS structure print_warnings (boolean) – if True, prints warnings when parameter_warnings exists; if False, does not print warnings when parameter_warnings exists and leaves warning handling to caller of implement_reform. raise_errors (boolean) – if True, raises ValueError when parameter_errors exists; if False, does not raise ValueError when parameter_errors exists and leaves error handling to caller of implement_reform. ValueError: – if reform is not a dictionary. if each YEAR in reform is not an integer. if minimum YEAR in the YEAR:MODS pairs is less than start_year. if minimum YEAR in the YEAR:MODS pairs is less than current_year. if maximum YEAR in the YEAR:MODS pairs is greater than end_year. if raise_errors is True AND _validate_parameter_names_types generates errors OR _validate_parameter_values generates errors. nothing void

Notes

Given a reform dictionary, typical usage of the Policy class is as follows:

policy = Policy()
policy.implement_reform(reform)


In the above statements, the Policy() call instantiates a policy object (policy) containing current-law policy parameters, and the implement_reform(reform) call applies the (possibly multi-year) reform specified in reform and then sets the current_year to the value of current_year when implement_reform was called with parameters set for that pre-call year.

An example of a multi-year, multi-parameter reform is as follows:

reform = {
2016: {
'_EITC_c': [[900, 5000, 8000, 9000]],
'_II_em': [7000],
'_SS_Earnings_c': [300000]
},
2017: {
'_SS_Earnings_c': [500000], '_SS_Earnings_c_cpi': False
},
2019: {
'_EITC_c': [[1200, 7000, 10000, 12000]],
'_II_em': [9000],
'_SS_Earnings_c': [700000], '_SS_Earnings_c_cpi': True
}
}


Notice that each of the four YEAR:MODS pairs is specified as required by the private _update method, whose documentation provides several MODS dictionary examples.

IMPORTANT NOTICE: when specifying a reform dictionary always group all reform provisions for a specified year into one YEAR:MODS pair. If you make the mistake of specifying two or more YEAR:MODS pairs with the same YEAR value, all but the last one will be overwritten, and therefore, not part of the reform. This is because Python expects unique (not multiple) dictionary keys. There is no way to catch this error, so be careful to specify reform dictionaries correctly.

inflation_rates()[source]

Returns list of price inflation rates starting with JSON_START_YEAR.

static translate_json_reform_suffixes(indict, growdiff_baseline_dict, growdiff_response_dict)[source]

Replace any array parameters with suffixes in the specified JSON-derived “policy” dictionary, indict, and return a JSON-equivalent dictionary containing constructed array parameters and containing no parameters with suffixes, odict.

wage_growth_rates()[source]

Returns list of wage growth rates starting with JSON_START_YEAR.

taxcalc.Records¶

class taxcalc.Records(data='puf.csv', exact_calculations=False, gfactors=<taxcalc.growfactors.GrowFactors object>, weights='puf_weights.csv.gz', adjust_ratios='puf_ratios.csv', start_year=2011)[source]

Constructor for the tax-filing-unit Records class.

Notes

Typical usage when using PUF input data is as follows:

recs = Records()


which uses all the default parameters of the constructor, and therefore, imputed variables are generated to augment the data and initial-year grow factors are applied to the data. There are situations in which you need to specify the values of the Record constructor’s arguments, but be sure you know exactly what you are doing when attempting this.

Use Records.cps_constructor() to get a Records object instantiated with CPS input data.

_extrapolate(year)[source]

Apply to variables the grow factors for specified calendar year.

_read_ratios(ratios)[source]

Read Records adjustment ratios from file or create empty DataFrame if None

array_length

Length of arrays in Records class’s DataFrame.

static cps_constructor(data=None, exact_calculations=False, gfactors=<taxcalc.growfactors.GrowFactors object>)[source]

Static method returns a Records object instantiated with CPS input data. This works in a analogous way to Records(), which returns a Records object instantiated with PUF input data. This is a convenience method that eliminates the need to specify all the details of the CPS input data just as the default values of the arguments of the Records class constructor eliminate the need to specify all the details of the PUF input data.

current_year

Records class current calendar year property.

data_year

Records class original data year property.

increment_year()[source]

Add one to current year. Also, does extrapolation, reweighting, adjusting for new current year.

static read_cps_data()[source]

Return data in cps.csv.gz as a Pandas DataFrame.

static read_var_info()[source]

Read Records variables metadata from JSON file; returns dictionary and specifies static varname sets listed below.

set_current_year(new_current_year)[source]

Set current year to specified value and updates FLPDYR variable. Unlike increment_year method, extrapolation, reweighting, adjusting are skipped.

zero_out_changing_calculated_vars()[source]

Set to zero all variables in the Records.CHANGING_CALCULATED_VARS set.

taxcalc.TaxCalcIO¶

class taxcalc.TaxCalcIO(input_data, tax_year, baseline, reform, assump, outdir=None)[source]

Constructor for the Tax-Calculator Input-Output class.

TaxCalcIO class constructor call must be followed by init() call.

Parameters: input_data (string or Pandas DataFrame) – string is name of INPUT file that is CSV formatted containing variable names in the Records.USABLE_READ_VARS set, or Pandas DataFrame is INPUT data containing variable names in the Records.USABLE_READ_VARS set. INPUT vsrisbles not in the Records.USABLE_READ_VARS set can be present but are ignored. tax_year (integer) – calendar year for which taxes will be computed for INPUT. baseline (None or string) – None implies baseline policy is current-law policy, or string is name of optional BASELINE file that is a JSON reform file. reform (None or string) – None implies no policy reform (current-law policy), or string is name of optional REFORM file(s). assump (None or string) – None implies economic assumptions are standard assumptions, or string is name of optional ASSUMP file. outdir (None or string) – None implies output files written to current directory, or string is name of optional output directory class instance TaxCalcIO
analyze(writing_output_file=False, output_tables=False, output_graphs=False, dump_varset=None, output_dump=False, output_sqldb=False)[source]

Conduct tax analysis.

Parameters: writing_output_file (boolean) – whether or not to generate and write output file output_tables (boolean) – whether or not to generate and write distributional tables to a text file output_graphs (boolean) – whether or not to generate and write HTML graphs of average and marginal tax rates by income percentile dump_varset (set) – custom set of variables to include in dump and sqldb output; None implies include all variables in dump and sqldb output output_dump (boolean) – whether or not to replace standard output with all input and calculated variables using their Tax-Calculator names output_sqldb (boolean) – whether or not to write SQLite3 database with dump table containing same output as written by output_dump to a csv file Nothing
static annual_analysis(input_data, tax_year, baseline, reform, assump, aging_input_data, exact_calculations, growdiff_growmodel, year, writing_output_file, output_tables, output_graphs, dump_varset, output_dump, output_sqldb)[source]

Conduct static analysis for specifed growdiff_growmodel and year.

Parameters: five parameters are same as the first five parameters of (First) – TaxCalcIO.init method. (the) – seven parameters are same as the first seven parameters of (Last) – TaxCalcIO.analyze method. (the) – gd_dict GrowDiff sub-dictionary for year+1
custom_dump_variables(tcdumpvars_str)[source]

Return set of variable names extracted from tcdumpvars_str, which contains the contents of the tcdumpvars file in the current directory. Also, builds self.errmsg if any custom variables are not valid.

dump_output(dump_varset, mtr_inctax, mtr_paytax)[source]

Extract dump output and return it as Pandas DataFrame.

static growmodel_analysis(input_data, tax_year, baseline, reform, assump, aging_input_data, exact_calculations, writing_output_file=False, output_tables=False, output_graphs=False, dump_varset=None, output_dump=False, output_sqldb=False)[source]

High-level logic for dynamic analysis using GrowModel class.

Parameters: five parameters are same as the first five parameters of (First) – TaxCalcIO.init method. (the) – seven parameters are same as the first seven parameters of (Last) – TaxCalcIO.analyze method. (the) – Nothing
init(input_data, tax_year, baseline, reform, assump, growdiff_growmodel, aging_input_data, exact_calculations)[source]

TaxCalcIO class post-constructor method that completes initialization.

Parameters: five are same as the first five of the TaxCalcIO constructor (First) – input_data, tax_year, baseline, reform, assump. growdiff_growmodel (GrowDiff object or None) – growdiff_growmodel GrowDiff object is used only in the TaxCalcIO.growmodel_analysis method. aging_input_data (boolean) – whether or not to extrapolate Records data from data year to tax_year. exact_calculations (boolean) – specifies whether or not exact tax calculations are done without any smoothing of “stair-step” provisions in the tax law.
minimal_output()[source]

Extract minimal output and return it as Pandas DataFrame.

output_filepath()[source]

Return full path to output file named in TaxCalcIO constructor.

tax_year()[source]

Return calendar year for which TaxCalcIO calculations are being done.

static write_decile_table(dfx, tfile, tkind='Totals')[source]

Write to tfile the tkind decile table using dfx DataFrame.

write_doc_file()[source]

Write reform documentation to text file.

static write_empty_graph_file(fname, title, reason)[source]

Write HTML graph file with title but no graph for specified reason.

write_graph_files()[source]

Write graphs to HTML files.

write_output_file(output_dump, dump_varset, mtr_paytax, mtr_inctax)[source]

Write output to CSV-formatted file.

write_sqldb_file(dump_varset, mtr_paytax, mtr_inctax)[source]

Write dump output to SQLite3 database table dump.

write_tables_file()[source]

Write tables to text file.

taxcalc.tbi.tbi¶

The public API of the TaxBrain Interface (tbi) to Tax-Calculator, which can be used by other models in the Policy Simulation Library (PSL) collection of USA tax models.

The tbi functions are used by TaxBrain to call PSL tax models in order to do distributed processing of TaxBrain runs and in order to maintain the privacy of the IRS-SOI PUF data being used by TaxBrain. Maintaining privacy is done by “fuzzing” reform results for several randomly selected filing units in each table cell. The filing units randomly selected differ for each policy reform and the “fuzzing” involves replacing the post-reform tax results for the selected units with their pre-reform tax results.

taxcalc.tbi.tbi.calculator_objects(year_n, start_year, use_puf_not_cps, use_full_sample, user_mods, behavior_allowed)[source]
This function assumes that the specified user_mods is a dictionary
This function returns (calc1, calc2) where
calc1 is pre-reform Calculator object calculated for year_n, and calc2 is post-reform Calculator object calculated for year_n.
Set behavior_allowed to False when generating static results or
set behavior_allowed to True when generating dynamic results.
taxcalc.tbi.tbi.calculators(year_n, start_year, use_puf_not_cps, use_full_sample, user_mods)[source]
This function assumes that the specified user_mods is a dictionary
This function returns (calc1, calc2) where
calc1 is pre-reform Calculator object for year_n, and calc2 is post-reform Calculator object for year_n.

Neither Calculator object has had the calc_all() method executed.

taxcalc.tbi.tbi.check_user_mods(user_mods)[source]

Ensure specified user_mods is properly structured.

taxcalc.tbi.tbi.check_years(year_n, start_year, use_puf_not_cps)[source]

Ensure year_n and start_year values are valid given input data used.

taxcalc.tbi.tbi.check_years_return_first_year(year_n, start_year, use_puf_not_cps)[source]

Ensure year_n and start_year values are valid given input data used. Return value of first year, which is maximum of first records data year and first policy parameter year.

taxcalc.tbi.tbi.create_dict_table(dframe, row_names=None, column_types=None, num_decimals=2)[source]

Create and return dictionary with JSON-like content from specified dframe.

taxcalc.tbi.tbi.fuzzed(df1, df2, reform_affected, table_row_type)[source]

Create fuzzed df2 dataframe and corresponding unfuzzed df1 dataframe.

Parameters: df1 (Pandas DataFrame) – contains results variables for the baseline policy, which are not changed by this function df2 (Pandas DataFrame) – contains results variables for the reform policy, which are not changed by this function reform_affected (boolean numpy array (not changed by this function)) – True for filing units with a reform-induced combined tax difference; otherwise False table_row_type (string) – valid values are ‘aggr’, ‘xbin’, and ‘xdec’ df1, df2 – where copied df2 is fuzzed to maintain data privacy and where copied df1 has same filing unit order as has the fuzzed df2 Pandas DataFrames
taxcalc.tbi.tbi.random_seed(user_mods)[source]

Compute random seed based on specified user_mods, which is a dictionary returned by Calculator.read_json_parameter_files().

taxcalc.tbi.tbi.reform_warnings_errors(user_mods, using_puf)[source]

The reform_warnings_errors function assumes user_mods is a dictionary returned by the Calculator.read_json_param_objects() function.

This function returns a dictionary containing five STR:STR subdictionaries, where the dictionary keys are: ‘policy’, ‘behavior’, consumption’, ‘growdiff_baseline’ and ‘growdiff_response’; and the subdictionaries are: {‘warnings’: ‘<empty-or-message(s)>’, ‘errors’: ‘<empty-or-message(s)>’}. Note that non-policy parameters have no warnings, so the ‘warnings’ string for the non-policy parameters is always empty.

taxcalc.tbi.tbi.run_nth_year_gdp_elast_model(year_n, start_year, use_puf_not_cps, use_full_sample, user_mods, gdp_elasticity, return_dict=True)[source]
The run_nth_year_gdp_elast_model function assumes user_mods is a dictionary
Setting use_puf_not_cps=True implies use puf.csv input file;
otherwise, use cps.csv input file.
Setting use_full_sample=False implies use sub-sample of input file;
otherwsie, use the complete sample.
taxcalc.tbi.tbi.run_nth_year_taxcalc_model(year_n, start_year, use_puf_not_cps, use_full_sample, user_mods, return_dict=True)[source]
The run_nth_year_taxcalc_model function assumes user_mods is a dictionary
Setting use_puf_not_cps=True implies use puf.csv input file;
otherwise, use cps.csv input file.
Setting use_full_sample=False implies use sub-sample of input file;
otherwsie, use the complete sample.
taxcalc.tbi.tbi.summary_aggregate(res, df1, df2)[source]

res is dictionary of summary-results DataFrames. df1 contains results variables for baseline policy. df2 contains results variables for reform policy. returns augmented dictionary of summary-results DataFrames.

taxcalc.tbi.tbi.summary_diff_xbin(res, df1, df2)[source]

res is dictionary of summary-results DataFrames. df1 contains results variables for baseline policy. df2 contains results variables for reform policy. returns augmented dictionary of summary-results DataFrames.

taxcalc.tbi.tbi.summary_diff_xdec(res, df1, df2)[source]

res is dictionary of summary-results DataFrames. df1 contains results variables for baseline policy. df2 contains results variables for reform policy. returns augmented dictionary of summary-results DataFrames.

taxcalc.tbi.tbi.summary_dist_xbin(res, df1, df2)[source]

res is dictionary of summary-results DataFrames. df1 contains results variables for baseline policy. df2 contains results variables for reform policy. returns augmented dictionary of summary-results DataFrames.

taxcalc.tbi.tbi.summary_dist_xdec(res, df1, df2)[source]

res is dictionary of summary-results DataFrames. df1 contains results variables for baseline policy. df2 contains results variables for reform policy. returns augmented dictionary of summary-results DataFrames.

taxcalc.utils¶

PUBLIC low-level utility functions for Tax-Calculator.

taxcalc.utils.add_income_table_row_variable(dframe, income_measure, bin_edges)[source]

Add a variable to specified Pandas DataFrame, dframe, that specifies the table row and is called ‘table_row’. The rows are defined by the specified bin_edges function argument. Note that the bin groupings are LEFT INCLUSIVE, which means that bin_edges=[1,2,3,4] implies these three bin groupings: [1,2), [2,3), [3,4).

Parameters: dframe (Pandas DataFrame) – the object to which we are adding bins income_measure (String) – specifies income variable used to construct bins bin_edges (list of scalar bin edges) – dframe – the original input plus the added ‘table_row’ column Pandas DataFrame
taxcalc.utils.add_quantile_table_row_variable(dframe, income_measure, num_quantiles, decile_details=False, weight_by_income_measure=False)[source]

Add a variable to specified Pandas DataFrame, dframe, that specifies the table row and is called ‘table_row’. The rows hold equal number of filing units when weight_by_income_measure=False or equal number of income dollars when weight_by_income_measure=True. Assumes that specified dframe contains columns for the specified income_measure and for sample weights, s006. When num_quantiles is 10 and decile_details is True, the bottom decile is broken up into three subgroups (neg, zero, and pos income_measure ) and the top decile is broken into three subgroups (90-95, 95-99, and top 1%).

taxcalc.utils.atr_graph_data(vdf, year, mars='ALL', atr_measure='combined')[source]

Prepare average tax rate data needed by xtr_graph_plot utility function.

Parameters: vdf (a Pandas DataFrame object containing variables and tax liabilities) – (See Calculator.atr_graph method for required elements of vdf.) year (integer) – specifies calendar year of the data in vdf mars (integer or string) – specifies which filing status subgroup to show in the graph ’ALL’: include all filing units in sample 1: include only single filing units 2: include only married-filing-jointly filing units 3: include only married-filing-separately filing units 4: include only head-of-household filing units atr_measure (string) – specifies which average tax rate to show on graph’s y axis ’itax’: average individual income tax rate ’ptax’: average payroll tax rate ’combined’: sum of average income and payroll tax rates dictionary object suitable for passing to xtr_graph_plot utility function
taxcalc.utils.bootstrap_se_ci(data, seed, num_samples, statistic, alpha)[source]

Return bootstrap estimate of standard error of statistic and bootstrap estimate of 100*(1-2*alpha)% confidence interval for statistic in a dictionary along with specified seed and nun_samples (B) and alpha.

taxcalc.utils.ce_aftertax_expanded_income(df1, df2, custom_params=None, require_no_agg_tax_change=True)[source]

Return dictionary that contains certainty-equivalent of the expected utility of after-tax expanded income computed for several constant-relative-risk-aversion parameter values for each of two Pandas DataFrame objects: df1, which represents the pre-reform situation, and df2, which represents the post-reform situation. Both DataFrame objects must contain ‘s006’, ‘combined’, and ‘expanded_income’ columns.

IMPORTANT NOTES: These normative welfare calculations are very simple. It is assumed that utility is a function of only consumption, and that consumption is equal to after-tax income. This means that any assumed behavioral responses that change work effort will not affect utility via the correpsonding change in leisure. And any saving response to changes in after-tax income do not affect consumption.

The cmin value is the consumption level below which marginal utility is considered to be constant. This allows the handling of filing units with very low or even negative after-tax expanded income in the expected-utility and certainty-equivalent calculations.

taxcalc.utils.certainty_equivalent(exputil, crra, cmin)[source]

Calculate and return certainty-equivalent of exputil of consumption assuming an isoelastic utility function with crra and cmin as parameters.

Parameters: exputil (float) – expected utility value crra (non-negative float) – constant relative risk aversion parameter of isoelastic utility function cmin (positive float) – consumption level below which marginal utility is assumed to be constant certainty-equivalent of specified expected utility, exputil
taxcalc.utils.create_diagnostic_table(vdf, year)[source]

Extract single-year diagnostic table from Pandas DataFrame object returned from a calc.dataframe(DIST_VARIABLES + [‘surtax’]) call.

Parameters: vdf (Pandas DataFrame object containing the variables) – year (calendar year for which variables were drawn from Calculator object) – Pandas DataFrame object containing the diagnostic table
taxcalc.utils.create_difference_table(vdf1, vdf2, groupby, tax_to_diff)[source]

Get results from two different vdf, construct tax difference results, and return the difference statistics as a table.

Parameters: vdf1 (Pandas DataFrame including columns named in DIFF_VARIABLES list) – for example, object returned from a dataframe(DIFF_VARIABLE) call on the basesline Calculator object vdf2 (Pandas DataFrame including columns in the DIFF_VARIABLES list) – for example, object returned from a dataframe(DIFF_VARIABLE) call on the reform Calculator object groupby (String object) – options for input: ‘weighted_deciles’ or ’standard_income_bins’ or ‘soi_agi_bins’ determines how the rows in the resulting Pandas DataFrame are sorted tax_to_diff (String object) – options for input: ‘iitax’, ‘payrolltax’, ‘combined’ specifies which tax to difference difference table as a Pandas DataFrame with DIFF_TABLE_COLUMNS and groupby rows. NOTE (when groupby is ‘weighted_deciles’, the returned table has three) – extra rows containing top-decile detail consisting of statistics for the 0.90-0.95 quantile range (bottom half of top decile), for the 0.95-0.99 quantile range, and for the 0.99-1.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 0-10n row label), zero (denoted by a 0-10z row label), and positive (denoted by a 0-10p row label) values of the specified income_measure.
taxcalc.utils.create_distribution_table(vdf, groupby, income_measure, scaling=True)[source]

Get results from vdf, sort them by expanded_income based on groupby, and return them as a table.

Parameters: vdf (Pandas DataFrame including columns named in DIST_TABLE_COLUMNS list) – for example, an object returned from the Calculator class distribution_table_dataframe method groupby (String object) – options for input: ‘weighted_deciles’ or ’standard_income_bins’ or ‘soi_agi_bins’ determines how the rows in the resulting Pandas DataFrame are sorted income_measure (String object) – options for input: ‘expanded_income’ or ‘expanded_income_baseline’ determines which variable is used to sort rows scaling (boolean) – specifies whether or not table entries are scaled distribution table as a Pandas DataFrame with DIST_TABLE_COLUMNS and groupby rows. NOTE (when groupby is ‘weighted_deciles’, the returned table has three) – extra rows containing top-decile detail consisting of statistics for the 0.90-0.95 quantile range (bottom half of top decile), for the 0.95-0.99 quantile range, and for the 0.99-1.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 0-10n row label), zero (denoted by a 0-10z row label), and positive (denoted by a 0-10p row label) values of the specified income_measure.
taxcalc.utils.dec_graph_data(dist_table1, dist_table2, year, include_zero_incomes, include_negative_incomes)[source]

Prepare data needed by dec_graph_plot utility function.

Parameters: dist_table1 (a Pandas DataFrame object returned from the) – Calculator class distribution_tables method for baseline dist_table2 (a Pandas DataFrame object returned from the) – Calculator class distribution_tables method for reform year (integer) – specifies calendar year of the data in the diff_table include_zero_incomes (boolean) – if True, the bottom decile does contain filing units with zero expanded_income; if False, the bottom decile does not contain filing units with zero expanded_income. include_negative_incomes (boolean) – if True, the bottom decile does contain filing units with negative expanded_income; if False, the bottom decile does not contain filing units with negative expanded_income. dictionary object suitable for passing to dec_graph_plot utility function
taxcalc.utils.dec_graph_plot(data, width=850, height=500, xlabel='', ylabel='', title='')[source]

Plot stacked decile graph using data returned from dec_graph_data function.

Parameters: data (dictionary object returned from dec_graph_data() utility function) – width (integer) – width of plot expressed in pixels height (integer) – height of plot expressed in pixels xlabel (string) – x-axis label; if ‘’, then use label generated by dec_graph_data ylabel (string) – y-axis label; if ‘’, then use label generated by dec_graph_data title (string) – graph title; if ‘’, then use title generated by dec_graph_data bokeh.plotting figure object containing a raster graphics plot

Notes

USAGE EXAMPLE:

gdata = dec_graph_data(...)
gplot = dec_graph_plot(gdata)


THEN when working interactively in a Python notebook:

bp.show(gplot)


OR when executing script using Python command-line interpreter:

bio.output_file('graph-name.html', title='Change in After-Tax Income')
bio.show(gplot)  [OR bio.save(gplot) WILL JUST WRITE FILE TO DISK]


WILL VISUALIZE GRAPH IN BROWSER AND WRITE GRAPH TO SPECIFIED HTML FILE

To convert the visualized graph into a PNG-formatted file, click on the “Save” icon on the Toolbar (located in the top-right corner of the visualized graph) and a PNG-formatted file will written to your Download directory.

The ONLY output option the bokeh.plotting figure has is HTML format, which (as described above) can be converted into a PNG-formatted raster graphics file. There is no option to make the bokeh.plotting figure generate a vector graphics file such as an EPS file.

taxcalc.utils.delete_file(filename)[source]

Remove specified file if it exists.

taxcalc.utils.expected_utility(consumption, probability, crra, cmin)[source]

Calculate and return expected utility of consumption.

Parameters: consumption (numpy array) – consumption for each filing unit probability (numpy array) – samplying probability of each filing unit crra (non-negative float) – constant relative risk aversion parameter of isoelastic utility function cmin (positive float) – consumption level below which marginal utility is assumed to be constant expected utility of consumption array
taxcalc.utils.get_sums(dframe)[source]

Compute unweighted sum of items in each column of Pandas DataFrame, dframe.

Returns: Pandas Series object containing column sums indexed by dframe column names.
taxcalc.utils.isoelastic_utility_function(consumption, crra, cmin)[source]

Calculate and return utility of consumption.

Parameters: consumption (float) – consumption for a filing unit crra (non-negative float) – constant relative risk aversion parameter cmin (positive float) – consumption level below which marginal utility is assumed to be constant utility of consumption
taxcalc.utils.json_to_dict(json_text)[source]

Convert specified JSON text into an ordered Python dictionary.

Parameters: json_text (string) – JSON text. ValueError: – if json_text contains a JSON syntax error. dictionary – JSON data expressed as an ordered Python dictionary. collections.OrderedDict
taxcalc.utils.mtr_graph_data(vdf, year, mars='ALL', mtr_measure='combined', mtr_variable='e00200p', alt_e00200p_text='', mtr_wrt_full_compen=False, income_measure='expanded_income', dollar_weighting=False)[source]

Prepare marginal tax rate data needed by xtr_graph_plot utility function.

Parameters: vdf (a Pandas DataFrame object containing variables and marginal tax rates) – (See Calculator.mtr_graph method for required elements of vdf.) year (integer) – specifies calendar year of the data in vdf mars (integer or string) – specifies which filing status subgroup to show in the graph ’ALL’: include all filing units in sample 1: include only single filing units 2: include only married-filing-jointly filing units 3: include only married-filing-separately filing units 4: include only head-of-household filing units mtr_measure (string) – specifies which marginal tax rate to show on graph’s y axis ’itax’: marginal individual income tax rate ’ptax’: marginal payroll tax rate ’combined’: sum of marginal income and payroll tax rates mtr_variable (string) – any string in the Calculator.VALID_MTR_VARS set specifies variable to change in order to compute marginal tax rates alt_e00200p_text (string) – text to use in place of mtr_variable when mtr_variable is ‘e00200p’; if empty string then use ‘e00200p’ mtr_wrt_full_compen (boolean) – see documentation of Calculator.mtr() argument wrt_full_compensation (value has an effect only if mtr_variable is ‘e00200p’) income_measure (string) – specifies which income variable to show on the graph’s x axis ’wages’: wage and salary income (e00200) ’agi’: adjusted gross income, AGI (c00100) ’expanded_income’: sum of AGI, non-taxable interest income, non-taxable social security benefits, and employer share of FICA taxes. dollar_weighting (boolean) – False implies both income_measure percentiles on x axis and mtr values for each percentile on the y axis are computed without using dollar income_measure weights (just sampling weights); True implies both income_measure percentiles on x axis and mtr values for each percentile on the y axis are computed using dollar income_measure weights (in addition to sampling weights). Specifying True produces a graph x axis that shows income_measure (not filing unit) percentiles. dictionary object suitable for passing to xtr_graph_plot utility function
taxcalc.utils.nonsmall_diffs(linelist1, linelist2, small=0.0)[source]

Return True if line lists differ significantly; otherwise return False. Significant numerical difference means one or more numbers differ (between linelist1 and linelist2) by more than the specified small amount.

taxcalc.utils.pch_graph_data(vdf, year)[source]

Prepare percentage change in after-tax expanded income data needed by pch_graph_plot utility function.

Parameters: vdf (a Pandas DataFrame object containing variables) – (See Calculator.pch_graph method for required elements of vdf.) year (integer) – specifies calendar year of the data in vdf dictionary object suitable for passing to pch_graph_plot utility function
taxcalc.utils.pch_graph_plot(data, width=850, height=500, xlabel='', ylabel='', title='')[source]

Plot percentage change in after-tax expanded income using data returned from the pch_graph_data function.

Parameters: data (dictionary object returned from ?tr_graph_data() utility function) – width (integer) – width of plot expressed in pixels height (integer) – height of plot expressed in pixels xlabel (string) – x-axis label; if ‘’, then use label generated by pch_graph_data ylabel (string) – y-axis label; if ‘’, then use label generated by pch_graph_data title (string) – graph title; if ‘’, then use title generated by pch_graph_data bokeh.plotting figure object containing a raster graphics plot

Notes

See Notes to xtr_graph_plot function.

taxcalc.utils.quantity_response(quantity, price_elasticity, aftertax_price1, aftertax_price2, income_elasticity, aftertax_income1, aftertax_income2)[source]

Calculate dollar change in quantity using a log-log response equation, which assumes that the proportional change in the quantity is equal to the sum of two terms: (1) the proportional change in the quanitity’s marginal aftertax price

times an assumed price elasticity, and
1. the proportional change in aftertax income times an assumed income elasticity.
Parameters: quantity (numpy array) – pre-response quantity whose response is being calculated price_elasticity (float) – coefficient of the percentage change in aftertax price of the quantity in the log-log response equation aftertax_price1 (numpy array) – marginal aftertax price of the quanitity under baseline policy Note that this function forces prices to be in [0.01, inf] range, but the caller of this function may want to constrain negative or very small prices to be somewhat larger in order to avoid extreme proportional changes in price. Note this is NOT an array of marginal tax rates (MTR), but rather usually 1-MTR (or in the case of quantities, like charitable giving, whose MTR values are non-positive, 1+MTR). aftertax_price2 (numpy array) – marginal aftertax price of the quantity under reform policy Note that this function forces prices to be in [0.01, inf] range, but the caller of this function may want to constrain negative or very small prices to be somewhat larger in order to avoid extreme proportional changes in price. Note this is NOT an array of marginal tax rates (MTR), but rather usually 1-MTR (or in the case of quantities, like charitable giving, whose MTR values are non-positive, 1+MTR). income_elasticity (float) – coefficient of the percentage change in aftertax income in the log-log response equation aftertax_income1 (numpy array) – aftertax income under baseline policy Note that this function forces income to be in [1, inf] range, but the caller of this function may want to constrain negative or small incomes to be somewhat larger in order to avoid extreme proportional changes in aftertax income. aftertax_income2 (numpy array) – aftertax income under reform policy Note that this function forces income to be in [1, inf] range, but the caller of this function may want to constrain negative or small incomes to be somewhat larger in order to avoid extreme proportional changes in aftertax income. response – dollar change in quantity calculated from log-log response equation numpy array
taxcalc.utils.read_egg_csv(fname, index_col=None)[source]

Read from egg the file named fname that contains CSV data and return pandas DataFrame containing the data.

taxcalc.utils.read_egg_json(fname)[source]

Read from egg the file named fname that contains JSON data and return dictionary containing the data.

taxcalc.utils.unweighted_sum(dframe, col_name)[source]

Return unweighted sum of Pandas DataFrame col_name items.

taxcalc.utils.weighted_sum(dframe, col_name)[source]

Return weighted sum of Pandas DataFrame col_name items.

taxcalc.utils.write_graph_file(figure, filename, title)[source]

Write HTML file named filename containing figure. The title is the text displayed in the browser tab.

Parameters: figure (bokeh.plotting figure object) – filename (string) – name of HTML file to which figure is written; should end in .html title (string) – text displayed in browser tab when HTML file is displayed in browser Nothing
taxcalc.utils.xtr_graph_plot(data, width=850, height=500, xlabel='', ylabel='', title='', legendloc='bottom_right')[source]

Plot marginal/average tax rate graph using data returned from either the mtr_graph_data function or the atr_graph_data function.

Parameters: data (dictionary object returned from ?tr_graph_data() utility function) – width (integer) – width of plot expressed in pixels height (integer) – height of plot expressed in pixels xlabel (string) – x-axis label; if ‘’, then use label generated by ?tr_graph_data ylabel (string) – y-axis label; if ‘’, then use label generated by ?tr_graph_data title (string) – graph title; if ‘’, then use title generated by ?tr_graph_data legendloc (string) – options: ‘top_right’, ‘top_left’, ‘bottom_left’, ‘bottom_right’ specifies location of the legend in the plot bokeh.plotting figure object containing a raster graphics plot

Notes

USAGE EXAMPLE:

gdata = mtr_graph_data(...)
gplot = xtr_graph_plot(gdata)


THEN when working interactively in a Python notebook:

bp.show(gplot)


OR when executing script using Python command-line interpreter:

bio.output_file('graph-name.html', title='?TR by Income Percentile')
bio.show(gplot)  [OR bio.save(gplot) WILL JUST WRITE FILE TO DISK]


WILL VISUALIZE GRAPH IN BROWSER AND WRITE GRAPH TO SPECIFIED HTML FILE

To convert the visualized graph into a PNG-formatted file, click on the “Save” icon on the Toolbar (located in the top-right corner of the visualized graph) and a PNG-formatted file will written to your Download directory.

The ONLY output option the bokeh.plotting figure has is HTML format, which (as described above) can be converted into a PNG-formatted raster graphics file. There is no option to make the bokeh.plotting figure generate a vector graphics file such as an EPS file.