TaxCalculator Public API¶
The TaxCalculator’s core capabilities are in the Python package called taxcalc, the source code for which is located in the taxcalculator/taxcalc directory tree.
Here we provide a highlevel view of the public API of the taxcalc conda package with links to the source code. This highlevel 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 TaxCalculator capabilities in their own projects should restrict themselves to using this public API. All other TaxCalculator 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 ParametersBase class, and therefore, inherits its methods (none of which are shown here).
Constructor for elasticitybased behavioralresponse class.
Parameters:  behavior_dict (dictionary of PARAM:DESCRIPTION pairs) – dictionary of behavioralresponse elasticities; if None, default elasticities are read from the behavior.json file.
 start_year (integer) – first calendar year for behavioralresponse elasticities.
 num_years (integer) – number of calendar years for which to specify elasticity values beginning with start_year.
Raises: ValueError: – if behavior_dict is neither None nor a dictionary. if num_years is less than one.
Returns: class instance
Return type: 
_validate_parameter_names_types
(revision)[source]¶ Check validity of parameter names and parameter types used in the specified revision dictionary.

_validate_parameter_values
(parameters_set)[source]¶ Check values of parameters in specified parameter_set using range information from the current_law_policy.json file.

has_any_response
()[source]¶ Returns true if any behavioralresponse elasticity is nonzero in any year; returns false if all elasticities are zero in all years.

has_response
()[source]¶ Returns true if any behavioralresponse elasticity is nonzero for the current_year; returns false if all elasticities are zero.

static
response
(calc2, mtr_cap=0.99, 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 dollarchange income elasticity (rather than
 a proportionalchange elasticity) is consistent with Feldstein and Feenberg, “The Taxation of Two Earner Families”, NBER Working Paper No. 5155 (June 1995). A proportionalchange elasticity was used by Gruber and Saez, “The elasticity of taxable income: evidence and implications”, Journal of Public Economics 84:132 (2002) [see equation 2 on page 10].
 Note: the nature of the capitalgains 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”, (JCX5612), June 2012. In particular, the elasticity use here is equivalent to the term inside the square brackets on the righthand side of equation (4) on page 11 — not the epsilon variable on the lefthand side of equation (4), which is equal to the elasticity used here times the weighted average marginal tax rate on longterm capital gains. So, the JCTCBO estimate of 0.792 for the epsilon elasticity (see JCTCBO, Table 5) translates into a much larger absolute value for the _BE_cg semielasticity used by TaxCalculator. To calculate the elasticity from a semielasticity, 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 semielasticity of 3.45 corresponds to a tax rate elasticity of 0.792.

update_behavior
(revision, raise_errors=True)[source]¶ Implement multiyear behavior revision and leave current_year unchanged.
Parameters:  revision (dictionary of one or more YEAR:MODS pairs) – see Notes to Parameters _update method for info on MODS structure
 raise_errors (boolean) –
 if True (the default), raises ValueError when parameter_errors
 exists;
 if False, does not raise ValueError when parameter_errors exists
 and leaves error handling to caller of update_behavior.
Raises: 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 raise_errors is True AND
_validate_parameter_names_types generates error OR _validate_parameter_values generates errors.
Returns: nothing
Return type: 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 multiyear) 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 precall year.
An example of a multiyear, multiparameter 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 dataloaded and dataextrapolated 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 inkind benefis with no inkind consumption values specified implying consumption value is equal to government cost of providing the inkind 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
Raises: ValueError: – if parameters are not the appropriate type.
Returns: class instance
Return type: Notes
The most efficient way to specify currentlaw and reform Calculator objects is as follows:
pol = Policy() rec = Records() calc1 = Calculator(policy=pol, records=rec) # currentlaw pol.implement_reform(…) calc2 = Calculator(policy=pol, records=rec) # reformAll calculations are done on the internal copies of the Policy and Records objects passed to each of the two Calculator constructors.

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 expandedincome 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 marriedfilingjointly filing units
 3: include only marriedfilingseparately filing units
 4: include only headofhousehold 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
Returns: Return type: 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 taxcalculation functions for the current_year.

ce_aftertax_income
(calc, custom_params=None, require_no_agg_tax_change=True)[source]¶ Return dictionary that contains certaintyequivalent of the expected utility of aftertax expanded income computed for several constantrelativeriskaversion parameter values for each of two Calculator objects: self, which represents the prereform situation, and calc, which represents the postreform 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 aftertax 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 aftertax 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 aftertax expanded income in the expectedutility and certaintyequivalent calculations.

consump_benval_params
()[source]¶ Return list of benefitconsumptionvalue parameter values 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 expandedincome 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.
Returns: Return type: graph that is a bokeh.plotting figure object

diagnostic_table
(num_years)[source]¶ Generate multiyear 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) Returns: Return type: Pandas DataFrame object containing the multiyear diagnostic table

difference_table
(calc, groupby='weighted_deciles', income_measure='expanded_income', tax_to_diff='combined')[source]¶ Get results from self and calc, sort them based on groupby using income_measure, and return taxdifference 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 income_measure) even though the baseline income_measure in self and the income_measure in calc are different. Note that filing units are put into groupby categories using the specified income_measure in the baseline (self) situation.
Parameters:  calc (Calculator object) – calc represents the reform while self represents the baseline
 groupby (String object) –
 options for input: ‘weighted_deciles’, ‘standard_income_bins’,
 ’large_income_bins’, ‘small_income_bins’;
determines how the columns in resulting Pandas DataFrame are sorted
 income_measure (String object) – options for input: ‘expanded_income’ or ‘c00100’(AGI) specifies statistic used to place filing units in bins or deciles
 tax_to_diff (String object) – options for input: ‘iitax’, ‘payrolltax’, ‘combined’ specifies which tax to difference
 and typical usage (Returns) –
  –
 = calc1.difference_table(calc2) (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 topdecile detail consisting of statistics for the 0.900.95 quantile range (bottom half of top decile), for the 0.950.99 quantile range, and for the 0.991.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 010n row label), zero (denoted by a 010z row label), and positive (denoted by a 010p 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='weighted_deciles', income_measure='expanded_income', result_type='weighted_sum')[source]¶ Get results from self and calc, sort them based on groupby using income_measure, compute grouped statistics based on result_type, 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 income_measure) even though the baseline income_measure in self and the income_measure 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’,
 ’large_income_bins’, ‘small_income_bins’;
determines how the columns in resulting Pandas DataFrame are sorted
 income_measure (String object) – options for input: ‘expanded_income’ or ‘c00100’(AGI) specifies statistic used to place filing units in bins or deciles
 result_type (String object) – options for input: ‘weighted_sum’ or ‘weighted_avg’; determines how the table statistices are computed
 and typical usage (Return) –
  –
 dist2 = calc1.distribution_tables(calc2) (dist1,) –
 OR –
 _ = calc1.distribution_tables(None) (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 topdecile detail consisting of statistics for the 0.900.95 quantile range (bottom half of top decile), for the 0.950.99 quantile range, and for the 0.991.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 010n row label), zero (denoted by a 010z row label), and positive (denoted by a 010p row label) values of the specified income_measure.

incarray
(variable_name, variable_add)[source]¶ Add variable_add to named variable in embedded Records object.

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.
Returns:  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 selfemployment income (also in e00900); ‘e00300’, taxable interest income; ‘e00400’, federallytaxexempt interest income; ‘e00600’, all dividends included in AGI ‘e00650’, qualified dividends (also included in e00600) ‘e01400’, federallytaxable IRA distribution; ‘e01700’, federallytaxable pension benefits; ‘e02000’, Schedule E total net income/loss ‘e02400’, all social security (OASDI) benefits; ‘p22250’, shortterm capital gains; ‘p23250’, longterm capital gains; ‘e18500’, Schedule A realestatetax paid; ‘e19200’, Schedule A interest paid; ‘e26270’, Scorporation/partnership income (also included in e02000); ‘e19800’, Charity cash contributions; ‘e20100’, Charity noncash 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 marriedfilingjointly filing units
 3: include only marriedfilingseparately filing units
 4: include only headofhousehold 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
 functions.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.
Returns: Return type: graph that is a bokeh.plotting figure object

pch_graph
(calc)[source]¶ Create percentage change in aftertax 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 dollarweighted mean percentage change in aftertax expanded income for each expandedincome 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 Returns: Return type: 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_param_objects
(assump)[source]¶ Read JSON reform and assump objects and return a single dictionary containing five key:dict pairs: ‘policy’:dict, ‘consumption’:dict, ‘behavior’:dict, ‘growdiff_baseline’:dict and ‘growdiff_response’:dict.
Note that either of the first two parameters may be None. If reform is None, the dict in the ‘policy’:dict pair is empty. If assump is None, the dict in the ‘consumption’:dict pair, in the ‘behavior’:dict pair, in the ‘growdiff_baseline’:dict pair, and in the ‘growdiff_response’:dict pair, are all empty.
Also note that either of the first two parameters can be strings containing a valid JSON string (rather than a filename), in which case the file reading is skipped and the appropriate read_json_*_text method is called.
The reform file contents or JSON string must be like this: {“policy”: {…}} and the assump file contents or JSON string must be like: {“consumption”: {…},
“behavior”: {…}, “growdiff_baseline”: {…}, “growdiff_response”: {…}}
The returned dictionary contains parameter lists (not arrays).

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
(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 or subsequent elements of a compound reform; None implies no compound reform with the simple reform characterized in the params[‘policy’] dictionary
Returns: doc – the documentation for the policy reform specified in params
Return type: 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 allfilingunit total of sampling weights. NOTE: var_weighted_mean = calc.weighted_total(var)/calc.total_weight()
taxcalc.cli.tc¶
Commandline interface (CLI) to TaxCalculator, which can be accessed as ‘tc’ from an installed taxcalc conda package.
taxcalc.Consumption¶

class
taxcalc.
Consumption
(consumption_dict=None, start_year=2013, num_years=15)[source]¶ Consumption is a subclass of the abstract ParametersBase class, and therefore, inherits its methods (none of which are shown here).
Constructor for Consumption class.
Parameters:  consumption_dict (dictionary of PARAM:DESCRIPTION pairs) – dictionary of marginal propensity to consume (MPC) parameters and benefit (BEN) valueofinkindbenefit parameters; if None, all parameters are read from DEFAULTS_FILENAME file.
 start_year (integer) – first calendar year for consumption parameters.
 num_years (integer) – number of calendar years for which to specify parameter values beginning with start_year.
Raises: ValueError: – if consumption_dict is neither None nor a dictionary. if num_years is less than one.
Returns: class instance
Return type: 
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 consumptionrelated records variables given income_change and the current values of the MPC consumption parameters

update_consumption
(revisions)[source]¶ Update consumption for given revisions, 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 revisions 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 speedup TaxCalculator functions in the functions.py module.

class
taxcalc.decorators.
GetReturnNode
[source]¶ A NodeVisitor to get the return tuple names from a calcstyle function.

taxcalc.decorators.
apply_jit
(dtype_sig_out, dtype_sig_in, parameters=None, **kwargs)[source]¶ Make a decorator that takes in a calcstyle 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 applystyle function
Returns: Return type: 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, …):
 outputs = (…) = calc_func(…) header = […] return DataFrame(data, columns=header)
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) –
Returns: Return type: 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 calcstyle function (see functions.py) that transforms the calcstyle function into an applystyle function that can be called by Calculator class methods (see calculate.py).

taxcalc.decorators.
make_apply_function
(func, out_args, in_args, parameters, do_jit=True, **kwargs)[source]¶ Takes a calcstyle function and creates the necessary Python code for an applystyle function. Will also jit the function if desired.
Parameters:  func (the calcstyle function) –
 out_args (list of out arguments for the applystyle function) –
 in_args (list of in arguments for the applystyle 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 applystyle function.
 do_jit (Bool, if True, jit the resulting applystyle function) –
Returns: Return type: applystyle function
taxcalc.functions¶
TaxCalculator functions that calculate payroll and individual income taxes.
Note: the cpi_offset policy parameter is the only policy parameter that does not appear here; it is used in the policy.py file to possibly adjust the price inflation rate used to index policy parameters (as would be done in a reform that introduces chainedCPI indexing).

taxcalc.functions.
BenefitLimitation
(calc)[source]¶ Limits the benefits of select itemized deductions to a fraction of deductible expenses.

taxcalc.functions.
BenefitPrograms
(calc)[source]¶ Calculate total government cost and consumption value of benefits delivered by nonrepealed benefit programs.

taxcalc.functions.
BenefitSurtax
(calc)[source]¶ Computes itemizeddeductionbenefit surtax and adds the surtax amount to income tax, combined tax, and surtax liabilities.

taxcalc.functions.
ComputeBenefit
(calc, ID_switch)[source]¶ Calculates the value of the benefits accrued from itemizing.
taxcalc.Growdiff¶

class
taxcalc.
Growdiff
(growdiff_dict=None, start_year=2013, num_years=15)[source]¶ Growdiff is a subclass of the abstract ParametersBase class, and therefore, inherits its methods (none of which are shown here).
Constructor for growth difference class.
Parameters:  growdiff_dict (dictionary of PARAM:DESCRIPTION pairs) – dictionary of growth difference parameters; if None, default parameters are read from the growdiff.json file.
 start_year (integer) – first calendar year for growth difference parameters.
 num_years (integer) – number of calendar years for which to specify parameter values beginning with start_year.
Raises: ValueError: – if growdiff_dict is neither None nor a dictionary. if num_years is less than one.
Returns: class instance
Return type:
taxcalc.Growfactors¶

class
taxcalc.
Growfactors
(growfactors_filename='/home/docs/checkouts/readthedocs.org/user_builds/taxcalc/checkouts/latest/taxcalc/growfactors.csv')[source]¶ Constructor for the Growfactors class.
Parameters: growfactors_filename (string) – string is name of CSV file in which grow factors reside; default value is name of file containing baseline grow factors. Raises: ValueError: – if growfactors_filename is not a string. Returns: class instance Return type: Growfactors Notes
Typical usage is “gfactor = Growfactors()”, which produces an object containing the default grow factors in the Growfactors.FILENAME file.

first_year
¶ Growfactors class start_year property.

last_year
¶ Growfactors class last_year property.

taxcalc.macro_elasticity¶
Implements TaxBrain “Macroeconomic Elasticities Simulation” dynamic analysis.

taxcalc.macro_elasticity.
proportional_change_in_gdp
(year, calc1, calc2, elasticity)[source]¶ This function harnesses econometric estimates of the historic relationship between tax policy and the macro economy to predict the effect of tax reforms on economic growth.
In particular, this model relies on estimates of how GDP responds to changes in the average after tax rate on wage income across all taxpayers (one minus the average marginal tax rate, or 1AMTR). These estimates are derived from calculations of incomeweighted marginal tax rates under the baseline and reform. The reforminduced change in GDP in year t is assumed to be equal to the assumed elasticity times the absolute (not proportional) change in one minus the average marginal tax rate in year t1. In other words, the currentyear change in GDP is assumed to be related to the prioryear change in the average marginal tax rate.
Empirical evidence on this elasticity can be found in Robert Barro and Charles Redlick, “Macroeconomic Effects from Government Purchases and Taxes” (2011 Quarterly Journal of Economics). A prepublication version of this paper is available at the following URL: <siteresources.worldbank.org/INTMACRO/Resources/BarroBRedlickBpaper.pdf>. In particular, Barro and Redlick find that a 1 percentage point decrease in the AMTR leads to a 0.54 percent increase in GDP. Evaluated at the sample mean, this translates to an elasticity of GDP with respect to the average aftertax marginal rate of about 0.36.
A more recent paper by Karel Mertens and Jose L. Montiel Olea, entitled “Marginal Tax Rates and Income: New Time Series Evidence”, NBER working paper 19171 (June 2013 with September 2017 revisions) <www.nber.org/papers/w19171.pdf>, contains additional empirical evidence suggesting the elasticity is no less than the 0.36 Barro Redlick estimate and perhaps somewhat higher (see section 4.6). Their summary of the Barro and Redlick findings (on page 5) are as follows: “Barro and Redlick (2011) however find that a one percentage point cut in the AMTR raises per capita GDP by around 0.5% in the following year. This estimate is statistically significant and amounts to a short run GDP elasticity to the netoftax rate of 0.36”.
Parameters:  year (calendar year of the reforminduced proportion change in GDP) –
 calc1 (Calculator object for the prereform baseline for prior year) –
 calc2 (Calculator object for the policy reform for prior year) –
 elasticity (Float estimate of elasticity of GDP wrt 1AMTR) –
Returns:  Float estimate of proportional change in GDP induced by the reform
 Note that proportional means a relative change but it is not expressed
 in percentage terms
taxcalc.ParametersBase¶

class
taxcalc.
ParametersBase
[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.

current_year
¶ ParametersBase class current calendar year property.

classmethod
default_data
(metadata=False, start_year=None)[source]¶ Return parameter data read from the subclass’s json file.
Parameters:  metadata (boolean) –
 start_year (int or None) –
Returns: params
Return type: dictionary of data

end_year
¶ ParametersBase class lasst parameter year property.

num_years
¶ ParametersBase class number of parameter years property.

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 current_year and parameter values Raises: ValueError: – if year is not in [start_year, end_year] range. Returns: nothing Return type: 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
¶ ParametersBase class first parameter year property.

taxcalc.Policy¶

class
taxcalc.
Policy
(gfactors=None, start_year=2013, num_years=15)[source]¶ Policy is a subclass of the abstract ParametersBase 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
 parameter_dict (dictionary of PARAM:DESCRIPTION pairs) – dictionary of policy parameters; if None, default policy parameters are read from the current_law_policy.json file.
 start_year (integer) – first calendar year for historical policy parameters.
 num_years (integer) – number of calendar years for which to specify policy parameter values beginning with start_year.
Raises: ValueError: – if gfactors is not a Growfactors class instance. if parameter_dict is neither None nor a dictionary. if num_years is less than one.
Returns: class instance
Return type: 
_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 reindexing. Also, return known_years which is (first cpi_offset year  start year + 1).

_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 current_law_policy.json file.

implement_reform
(reform, print_warnings=True, raise_errors=True)[source]¶ Implement multiyear 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 (the default), 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 (the default), 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.
Raises: 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.
Returns: nothing
Return type: 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 currentlaw policy parameters, and the implement_reform(reform) call applies the (possibly multiyear) 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 precall year.
An example of a multiyear, multiparameter 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.

static
translate_json_reform_suffixes
(growdiff_baseline_dict, growdiff_response_dict)[source]¶ Replace any array parameters with suffixes in the specified JSONderived “policy” dictionary, indict, and return a JSONequivalent dictionary containing constructed array parameters and containing no parameters with suffixes, odict.
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', benefits=None, start_year=2011)[source]¶ Constructor for the taxfilingunit Records class.
Parameters:  data (string or Pandas DataFrame) – string describes CSV file in which records data reside; DataFrame already contains records data; default value is the string ‘puf.csv’ For details on how to use your own data with the TaxCalculator, look at the test_Calculator_using_nonstd_input() function in the tests/test_calculate.py file.
 exact_calculations (boolean) – specifies whether or not exact tax calculations are done without any smoothing of “stairstep” provisions in income tax law; default value is false.
 gfactors (Growfactors class instance or None) – containing record data extrapolation (or “blowup”) factors. NOTE: the constructor should never call the _blowup() method.
 weights (string or Pandas DataFrame or None) – string describes CSV file in which weights reside; DataFrame already contains weights; None creates empty sampleweights DataFrame; default value is filename of the PUF weights.
 adjust_ratios (string or Pandas DataFrame or None) – string describes CSV file in which adjustment ratios reside; DataFrame already contains adjustment ratios; None creates empty adjustmentratios DataFrame; default value is filename of the PUF adjustment ratios.
 start_year (integer) – specifies calendar year of the input data; default value is PUFCSV_YEAR. Note that if specifying your own data (see above) as being a custom data set, be sure to explicitly set start_year to the custom data’s calendar year. For details on how to use your own data with the TaxCalculator, read the DATAPREP.md file in the toplevel directory and then look at the test_Calculator_using_nonstd_input() function in the taxcalc/tests/test_calculate.py file.
Raises: ValueError: – if data is not the appropriate type. if taxpayer and spouse variables do not add up to filingunit total. if dividends is less than qualified dividends. if gfactors is not None or a Growfactors class instance. if start_year is not an integer. if files cannot be found.
Returns: class instance
Return type: 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 initialyear 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.

_read_benefits
(benefits)[source]¶ Read Records extrapolated benefits from a file or uses a specified DataFrame or creates an empty DataFrame if None. Should only be used with the cps.csv file

_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
(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_var_info
()[source]¶ Read Records variables metadata from JSON file; returns dictionary and specifies static varname sets listed below.
taxcalc.TaxCalcIO¶

class
taxcalc.
TaxCalcIO
(input_data, tax_year, baseline, reform, assump, outdir=None)[source]¶ Constructor for the TaxCalculator InputOutput 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 currentlaw policy, or string is name of optional BASELINE file that is a JSON reform file.
 reform (None or string) – None implies no policy reform (currentlaw 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
Returns: class instance
Return type: 
analyze
(writing_output_file=False, output_tables=False, output_graphs=False, output_ceeu=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
 output_ceeu (boolean) – whether or not to calculate and write to stdout standard certaintyequivalent expectedutility statistics
 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 TaxCalculator 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
Returns: Return type: Nothing

static
annual_analysis
(tax_year, baseline, reform, assump, aging_input_data, exact_calculations, growdiff_response, year, writing_output_file, output_tables, output_graphs, output_ceeu, dump_varset, output_dump, output_sqldb)[source]¶ Conduct static analysis for specifed year and growdiff_response.
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) –
Returns: gd_dict
Return type: Growdiff subdictionary 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
(tax_year, baseline, reform, assump, aging_input_data, exact_calculations, writing_output_file=False, output_tables=False, output_graphs=False, output_ceeu=False, dump_varset=None, output_dump=False, output_sqldb=False)[source]¶ Highlevel 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) –
Returns: Return type: Nothing

init
(input_data, tax_year, baseline, reform, assump, growdiff_response, aging_input_data, exact_calculations)[source]¶ TaxCalcIO class postconstructor 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_response (Growdiff object or None) – growdiff_response Growdiff object is used only by the TaxCalcIO.growmodel_analysis method; must be None in all other cases.
 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 “stairstep” provisions in the tax law.

static
write_decile_table
(tfile, tkind='Totals')[source]¶ Write to tfile the tkind decile table using dfx DataFrame.

static
write_empty_graph_file
(title, reason)[source]¶ Write HTML graph file with title but no graph for specified reason.

write_output_file
(output_dump, dump_varset, mtr_paytax, mtr_inctax)[source]¶ Write output to CSVformatted file.
taxcalc.tbi.tbi¶
The public API of the TaxBrain Interface (tbi).
The tbi functions are used by TaxBrain to call TaxCalculator in order to do distributed processing of TaxBrain runs and in order to maintain the privacy of the IRSSOI 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 postreform tax results for the selected units with their prereform tax results.

taxcalc.tbi.tbi.
reform_warnings_errors
(user_mods)[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 two STR:STR pairs: {‘warnings’: ‘<emptyormessage(s)>’, ‘errors’: ‘<emptyormessage(s)>’} In each pair the second string is empty if there are no messages. Any returned messages are generated using current_law_policy.json information on known policy parameter names and parameter value ranges.
Note that this function will return one or more error messages if the user_mods[‘policy’] dictionary contains any unknown policy parameter names or if any *_cpi parameters have values other than True or False. These situations prevent implementing the policy reform specified in user_mods, and therefore, no rangerelated warnings or errors will be returned in this case.

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
 returned by the Calculator.read_json_param_objects() function.
 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 subsample of input file;
 otherwsie, use the complete sample.

taxcalc.tbi.tbi.
run_nth_year_tax_calc_model
(year_n, start_year, use_puf_not_cps, use_full_sample, user_mods, return_dict=True)[source]¶  The run_nth_year_tax_calc_model function assumes user_mods is a dictionary
 returned by the Calculator.read_json_param_objects() function.
 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 subsample of input file;
 otherwsie, use the complete sample.
taxcalc.utils¶
PUBLIC lowlevel utility functions for TaxCalculator.

taxcalc.utils.
add_income_table_row_variable
(pdf, income_measure, bin_type='soi', bins=None, right=True)[source]¶ Add a variable to specified Pandas DataFrame, pdf, that specifies the table row and is called ‘table_row’. The rows are defined by the specified bin_type and optional bins function arguments.
Parameters:  pdf (Pandas DataFrame) – the object to which we are adding bins
 income_measure (String) – specifies income variable used to construct bins
 bin_type (String, optional) – options for input: ‘standard’, ‘tpc’, ‘soi’ default: ‘soi’
 bins (iterable of scalars, optional income breakpoints) – follows Pandas convention; the breakpoint is inclusive if right=True; this argument overrides the compare_with argument
 right (bool, optional) – indicates whether the bins include the rightmost edge or not; if right == True (the default), then bins=[1,2,3,4] implies this bin grouping (1,2], (2,3], (3,4]
Returns: pdf – the original input plus the added ‘table_row’ column
Return type: Pandas DataFrame

taxcalc.utils.
add_quantile_table_row_variable
(pdf, income_measure, num_quantiles, decile_details=False, weight_by_income_measure=False)[source]¶ Add a variable to specified Pandas DataFrame, pdf, 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 pdf 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 (9095, 9599, 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 marriedfilingjointly filing units
 3: include only marriedfilingseparately filing units
 4: include only headofhousehold 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
Returns: Return type: 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*(12*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 certaintyequivalent of the expected utility of aftertax expanded income computed for several constantrelativeriskaversion parameter values for each of two Pandas DataFrame objects: df1, which represents the prereform situation, and df2, which represents the postreform 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 aftertax 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 aftertax 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 aftertax expanded income in the expectedutility and certaintyequivalent calculations.

taxcalc.utils.
certainty_equivalent
(exputil, crra, cmin)[source]¶ Calculate and return certaintyequivalent of exputil of consumption assuming an isoelastic utility function with crra and cmin as parameters.
Parameters:  exputil (float) – expected utility value
 crra (nonnegative float) – constant relative risk aversion parameter of isoelastic utility function
 cmin (positive float) – consumption level below which marginal utility is assumed to be constant
Returns: Return type: certaintyequivalent of specified expected utility, exputil

taxcalc.utils.
create_diagnostic_table
(vdf, year)[source]¶ Extract singleyear diagnostic table from Pandas DataFrame object derived from a Calculator object using the dataframe(DIST_VARIABLES) method.
Parameters:  vdf (Pandas DataFrame object containing the variables) –
 year (calendar year for which variables were drawn from Calculator object) –
Returns: Return type: Pandas DataFrame object containing the diagnostic table

taxcalc.utils.
create_difference_table
(vdf1, vdf2, groupby, income_measure, 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’, ‘standard_income_bins’,
 ’large_income_bins’, ‘small_income_bins’;
determines how the columns in the resulting Pandas DataFrame are sorted
 income_measure (String object) – options for input: ‘expanded_income’, ‘c00100’(AGI) specifies statistic used to place filing units in bins or deciles
 tax_to_diff (String object) – options for input: ‘iitax’, ‘payrolltax’, ‘combined’ specifies which tax to difference
Returns:  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 topdecile detail consisting of statistics for the 0.900.95 quantile range (bottom half of top decile), for the 0.950.99 quantile range, and for the 0.991.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 010n row label), zero (denoted by a 010z row label), and positive (denoted by a 010p row label) values of the specified income_measure.

taxcalc.utils.
create_distribution_table
(vdf, groupby, income_measure, result_type)[source]¶ Get results from vdf, sort them based on groupby using income_measure, manipulate them based on result_type, and return them as a table.
Parameters:  vdf (Pandas DataFrame including columns named in DIST_TABLE_COLUMNS list) – for example, object returned from the Calculator class distribution_table_dataframe method
 groupby (String object) –
 options for input: ‘weighted_deciles’, ‘standard_income_bins’,
 ’large_income_bins’, ‘small_income_bins’;
determines how the columns in the resulting Pandas DataFrame are sorted
 result_type (String object) – options for input: ‘weighted_sum’ or ‘weighted_avg’; determines how the table statistices are computed
 income_measure (String object) – options for input: ‘expanded_income’, ‘c00100’(AGI) specifies statistic used to place filing units in bins or deciles
Notes
Taxpayer Characteristics:
c04470 : Total itemized deductions
c00100 : AGI
c09600 : Alternative minimum tax
s006 : filing unit sample weight
Returns:  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 topdecile detail consisting of statistics for the 0.900.95 quantile range (bottom half of top decile), for the 0.950.99 quantile range, and for the 0.991.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 010n row label), zero (denoted by a 010z row label), and positive (denoted by a 010p 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.
Returns: Return type: 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) – xaxis label; if ‘’, then use label generated by dec_graph_data
 ylabel (string) – yaxis label; if ‘’, then use label generated by dec_graph_data
 title (string) – graph title; if ‘’, then use title generated by dec_graph_data
Returns: Return type: 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 commandline interpreter:
bio.output_file('graphname.html', title='Change in AfterTax 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 PNGformatted file, click on the “Save” icon on the Toolbar (located in the topright corner of the visualized graph) and a PNGformatted 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 PNGformatted 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.
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 (nonnegative float) – constant relative risk aversion parameter of isoelastic utility function
 cmin (positive float) – consumption level below which marginal utility is assumed to be constant
Returns: Return type: expected utility of consumption array

taxcalc.utils.
get_sums
(pdf)[source]¶ Compute unweighted sum of items in each column of Pandas DataFrame, pdf.
Returns: Return type: Pandas Series object containing column sums indexed by pdf 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 (nonnegative float) – constant relative risk aversion parameter
 cmin (positive float) – consumption level below which marginal utility is assumed to be constant
Returns: Return type: utility of consumption

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 marriedfilingjointly filing units
 3: include only marriedfilingseparately filing units
 4: include only headofhousehold 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, nontaxable interest income, nontaxable 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.
Returns: Return type: 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 difference means one or more numbers differ (between linelist1 and linelist2) by more than the small amount. NOTE: this function is meant to be used only in the unit tests to handle small differences in floating point values generated by Python 2.7 and 3.6, where a nonzero small amount is used only under Python 3.6.

taxcalc.utils.
pch_graph_data
(vdf, year)[source]¶ Prepare percentage change in aftertax 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
Returns: Return type: 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 aftertax 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) – xaxis label; if ‘’, then use label generated by pch_graph_data
 ylabel (string) – yaxis label; if ‘’, then use label generated by pch_graph_data
 title (string) – graph title; if ‘’, then use title generated by pch_graph_data
Returns: Return type: bokeh.plotting figure object containing a raster graphics plot
Notes
See Notes to xtr_graph_plot function.

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
(pdf, col_name)[source]¶ Return unweighted sum of Pandas DataFrame col_name items.

taxcalc.utils.
weighted_sum
(pdf, 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
Returns: Return type: 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) – xaxis label; if ‘’, then use label generated by ?tr_graph_data
 ylabel (string) – yaxis 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
Returns: Return type: 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 commandline interpreter:
bio.output_file('graphname.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 PNGformatted file, click on the “Save” icon on the Toolbar (located in the topright corner of the visualized graph) and a PNGformatted 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 PNGformatted raster graphics file. There is no option to make the bokeh.plotting figure generate a vector graphics file such as an EPS file.