Source Code

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.

Here we provide a high-level view of the taxcalc package with links to the source code. This high-level view is organized around the modules that compose the taxcalc package. Below is a full list of the taxcalc package modules (in alphabetical order) with documentation about how to call each member of the module. There is also a link to the complete source code for each module member in the list. However, it may be more convenient to access this list interactively via the alphabetical Index of taxcalc modules and module members or the alphabetical Module Index.

taxcalc.behavior

Tax-Calculator elasticity-based behavioral-response Behavior class.

class taxcalc.behavior.Behavior(behavior_dict=None, start_year=2013, num_years=14)[source]

Constructor for elasticity-based behavioral-response class.

Parameters:
  • behavior_dict (dictionary of PARAM:DESCRIPTION pairs) – dictionary of behavioral-response elasticities; if None, default elasticities are read from the behavior.json file.
  • 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.
Raises:

ValueError: – if behavior_dict is neither None nor a dictionary. if num_years is less than one.

Returns:

class instance

Return type:

Behavior

_validate_elasticity_values()[source]

Check that behavioral-response elasticities have valid values.

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(calc_x, calc_y)[source]

Implements TaxBrain “Partial Equilibrium Simulation” dynamic analysis.

Modify calc_y records to account for behavioral responses that arise
from the policy reform that involves moving from calc_x.policy to calc_y.policy. Neither calc_x nor calc_y need to have had calc_all() executed before calling the Behavior.response(calc_x, calc_y) method.
Returns new Calculator object — a deepcopy of calc_y — 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(revisions)[source]

Update behavior for given revisions, a dictionary consisting of one or more year:modification dictionaries. For example: {2014: {‘_BE_sub’: [0.4, 0.3]}} Also checks for valid elasticity values in revisions dictionary. NOTE: this method uses the specified revisions to update the

DEFAULT elasticity values, so use this method just once rather than calling it sequentially in an attempt to update elasticities in several steps.

taxcalc.calculate

Tax-Calculator federal tax Calculator class.

class taxcalc.calculate.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 IMPORTANT NOTE: never pass the same Policy object to more than one

    Calculator. In other words, when specifying more than one Calculator object, do this: pol1 = Policy() rec1 = Records() calc1 = Calculator(policy=pol1, records=rec1) pol2 = Policy() rec2 = Records() calc2 = Calculator(policy=pol2, records=rec2)
  • records (Records class object) –

    this argument must be specified IMPORTANT NOTE: never pass the same Records object to more than one

    Calculator. In other words, when specifying more than one Calculator object, do this: pol1 = Policy() rec1 = Records() calc1 = Calculator(policy=pol1, records=rec1) pol2 = Policy() rec2 = Records() calc2 = Calculator(policy=pol2, records=rec2)
  • 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 syncronize 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.
  • behavior (Behavior class object) – specifies behaviorial responses used by Calculator; default is None, which implies no behavioral responses to policy reform.
Raises:

ValueError: – if parameters are not the appropriate type.

Returns:

class instance

Return type:

Calculator

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.

static convert_parameter_dict(param_key_dict)[source]
Converts specified param_key_dict into a dictionary whose primary
keys are calendary 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.
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.
current_law_version()[source]

Return Calculator object same as self except with current-law policy.

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

Calculates the marginal payroll, individual income, and combined tax rates for every tax filing unit.

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.
  • 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:

  • 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

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 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.

static read_json_econ_assump_text(text_string)[source]

Strip //-comments from text_string and return 4 dict based on the JSON. Specified text is JSON with at least 4 high-level string:object pairs:

a “consumption”: {...} pair, a “behavior”: {...} pair, a “growdiff_baseline”: {...} pair, and a “growdiff_response”: {...} pair. Other high-level pairs will be ignored by this method, except that a “policy” key 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_calculate.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
tests/test_calculate.py file.
Returned dictionaries (cons_dict,
behv_dict, gdiff_baseline_dict, gdiff_respose_dict)

have integer years as primary keys and string parameters as secondary keys.

The 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.
static read_json_param_files(reform_filename, assump_filename)[source]

Read JSON files and call Calculator.read_json_*_text methods returning a single dictionary containing five key:dict pairs: ‘policy’:dict, ‘consumption’:dict, ‘behavior’:dict, ‘growdiff_baseline’:dict and ‘growdiff_response’:dict.

static read_json_policy_reform_text(text_string)[source]

Strip //-comments from text_string and return 1 dict based on the JSON. Specified text is JSON with at least 1 high-level string:object pair:

a “policy”: {...} pair. Other high-level pairs will be ignored by this method, except that a “consumption”, “behavior”, “growdiff_baseline” or “growdiff_response” key 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_calculate.py for an extended example of a commented JSON policy reform text that can be read by this method.
Note that parameter code in the policy object is enclosed inside a
pair of double pipe characters (||) as shown in the REFORM_CONTENTS string in the tests/test_calculate.py file.
Returned dictionary rpol_dict
has integer years as primary keys and string parameters as secondary keys.
The returned dictionary is suitable as the argument to
the Policy implement_reform(rpol_dict) method.

taxcalc.consumption

Tax-Calculator marginal Consumption class.

class taxcalc.consumption.Consumption(consumption_dict=None, start_year=2013, num_years=14)[source]

Constructor for marginal Consumption class.

Parameters:
  • consumption_dict (dictionary of PARAM:DESCRIPTION pairs) – dictionary of marginal propensity to consume (MPC) parameters; if None, all MPC parameters are read from DEFAULTS_FILENAME file.
  • start_year (integer) – first calendar year for MPC parameters.
  • num_years (integer) – number of calendar years for which to specify MPC 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:

Consumption

has_response()[source]

Return true if any MPC parameters are positive for current_year; return false if all MPC parameters are zero.

response(records, income_change)[source]

Changes consumption-related records variables given income_change.

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: this method uses the specified revisions to update the

DEFAULT MPC parameter values, so use this method just once rather than calling it sequentially in an attempt to update MPC parameters in several steps.

taxcalc.decorators

Implement Numba JIT decorators used to speed-up tax-calculating functions.

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
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]

Make a decorator that takes in a calc-style function, create a function that handles the “high-level” function and the apply-style function.

Note: perhaps a better “bigger picture” description of what this does?

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) –
Returns:

Return type:

apply-style function

taxcalc.functions

Tax-Calculator functions that calculate payroll and individual income taxes.

taxcalc.functions.BenefitLimitation(calc)[source]

BenefitLimitation function: limits the benefits of select itemized deductions to a fraction of deductible expenses.

taxcalc.functions.BenefitSurtax(calc)[source]

BenefitSurtax function: computes itemized-deduction-benefit 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.functions.EITCamount[source]

Return EITC amount given specified parameters

taxcalc.functions.SchXYZ[source]

Return Schedule X, Y, Z tax amount for specified taxable_income.

taxcalc.functions.Taxes[source]

Taxes function returns tax amount given the progressive tax rate schedule specified by the rate* and (upper) tbrk* parameters and given income, filing status (MARS), and tax bracket base (tbrk_base).

taxcalc.growdiff

Tax-Calculator Growdiff class.

class taxcalc.growdiff.Growdiff(growdiff_dict=None, start_year=2013, num_years=14)[source]

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:

Growdiff

apply_to(growfactors)[source]

Apply updated growdiff values to specified Growfactors instance.

has_any_response()[source]

Returns true if any parameter is non-zero for any year; returns false if all parameters are zero in all years.

update_growdiff(revisions)[source]

Update growdiff default values using specified revisions, which is a dictionary containing one or more year:modification dictionaries. For example: {2014: {‘_AWAGE’: [0.01]}}.

taxcalc.growfactors

Tax-Calculator Growfactors class.

class taxcalc.growfactors.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.

factor_value(name, year)[source]

Return value of factor with specified name for specified year

first_year

Growfactors class start_year property

last_year

Growfactors class last_year property

price_inflation_rates(firstyear, lastyear)[source]

Return list of price inflation rates rounded to four decimal digits

update(name, year, diff)[source]

Add to self.gfdf[name][year] the specified diff amount

wage_growth_rates(firstyear, lastyear)[source]

Return list of wage growth rates rounded to four decimal digits

taxcalc.macro_elasticity

Implements TaxBrain “Macroeconomic Elasticities Simulation” dynamic analysis.

taxcalc.macro_elasticity.proportional_change_gdp(calc1, calc2, elasticity=0.0)[source]

This function harnesses econometric estimates of the historic relationship between tax policy and the macroeconomy to predict the effect of tax reforms on 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 1-AMTR). These estimates are derived from calculations of income-weighted marginal tax rates under the baseline and reform.

Evidence for this parameter can be found in Barro and Redlick’s “Macroeconomic Effects from Government Purchases and Taxes.” In particular, Barro and Redlick find that from a 1 percentage point increase 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 after tax rate of 0.36.

Karel Mertens’ “Marginal Tax Rates and Income: New Time Series Evidence” contains additional evidence, focussed on tax cuts affecting the upper part of the income distribution.

Both Mertens and Karel tentatively conclude that the effect stems from marginal rather than average tax rates.

Parameters:
  • calc1 (Calculator object for the pre-reform baseline) –
  • calc2 (Calculator object for the policy reform) –
  • elasticity (Float estimate of elasticity of GDP wrt 1-AMTR) –
Returns:

Return type:

Float estimate of proportional GDP impact of the reform.

taxcalc.parameters

Tax-Calculator abstract base parameters class.

class taxcalc.parameters.ParametersBase[source]

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

_update(year_mods)[source]

Private method used by public implement_reform and update_* methods in inheriting classes.

Parameters:year_mods (dictionary containing a single YEAR:MODS pair) – see Notes below for details on dictionary structure.
Raises:ValueError: – if year_mods is not a dictionary of the expected structure.
Returns:nothing
Return type:void

Notes

This is a private method that should never be used by clients of the inheriting classes. Instead, always use the public implement_reform or update_behavior methods. This is a private method that helps the public methods work.

This method implements a policy reform or behavior modification, the provisions of which are specified in the year_mods dictionary, that changes the values of some policy parameters in objects of inheriting classes. This year_mods dictionary contains exactly one YEAR:MODS pair, where the integer YEAR key indicates the calendar year for which the reform provisions in the MODS dictionary are implemented. The MODS dictionary contains PARAM:VALUE pairs in which the PARAM is a string specifying the policy parameter (as used in the DEFAULTS_FILENAME default parameter file) and the VALUE is a Python list of post-reform values for that PARAM in that YEAR. Beginning in the year following the implementation of a reform provision, the parameter whose value has been changed by the reform continues to be inflation indexed, if relevant, or not be inflation indexed according to that parameter’s cpi_inflated value loaded from DEFAULTS_FILENAME. For a cpi-related parameter, a reform can change the indexing status of a parameter by including in the MODS dictionary a term that is a PARAM_cpi:BOOLEAN pair specifying the post-reform indexing status of the parameter.

So, for example, to raise the OASDI (i.e., Old-Age, Survivors, and Disability Insurance) maximum taxable earnings beginning in 2018 to $500,000 and to continue indexing it in subsequent years as in current-law policy, the YEAR:MODS dictionary would be as follows:

{2018: {"_SS_Earnings_c":[500000]}}

But to raise the maximum taxable earnings in 2018 to $500,000 without any indexing in subsequent years, the YEAR:MODS dictionary would be as follows:

{2018: {"_SS_Earnings_c":[500000], "_SS_Earnings_c_cpi":False}}

And to raise in 2019 the starting AGI for EITC phaseout for married filing jointly filing status (which is a two-dimensional policy parameter that varies by the number of children from zero to three or more and is inflation indexed), the YEAR:MODS dictionary would be as follows:

{2019: {"_EITC_ps_MarriedJ":[[8000, 8500, 9000, 9500]]}}

Notice the pair of double square brackets around the four values for 2019. The one-dimensional parameters above require only a pair of single square brackets.

To model a change in behavior substitution effect, a year_mods dict example would be {2014: {‘_BE_inc’: [0.2, 0.3]}}

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

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

Expand the given data to account for the 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]

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, inflate, inflation_rates, num_years)[source]

Dispatch to either expand_1D or expand_2D depending on the dimension of x.

Parameters:
  • x (value to expand) – x must be either a scalar list or a 1D numpy array, or be either a list of scalar lists or a 2D numpy array.
  • 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
Returns:

Return type:

expanded numpy array with dtype=np.float64

set_year(year)[source]

Set parameters to values for 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.

static strip_Nones(x)[source]

Takes a 1D or 2D list, or a 1D or 2D numpy array. If x is 1D, when None is encountered, we return everything encountered before None. If x is 2D, we replace None with -1 and return.

Parameters:x (list or numpy array) –
Returns:
Return type:list

taxcalc.policy

Tax-Calculator federal tax policy Policy class.

class taxcalc.policy.Policy(gfactors=<taxcalc.growfactors.Growfactors object>, parameter_dict=None, start_year=2013, num_years=14)[source]

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:

Policy

current_law_version()[source]

Return Policy object same as self except with current-law policy.

implement_reform(reform)[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
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.
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 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.

wage_growth_rates()[source]

Returns list of wage growth rates starting with JSON_START_YEAR.

taxcalc.records

Tax-Calculator tax-filing-unit Records class.

class taxcalc.records.Records(data='puf.csv', exact_calculations=False, gfactors=<taxcalc.growfactors.Growfactors object>, weights='/home/docs/checkouts/readthedocs.org/user_builds/taxcalc/checkouts/latest/taxcalc/puf_weights.csv', adjust_ratios='/home/docs/checkouts/readthedocs.org/user_builds/taxcalc/checkouts/latest/taxcalc/puf_ratios.csv', start_year=2009)[source]

Constructor for the tax-filing-unit 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 Tax-Calculator, 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 “stair-step” provisions in income tax law; default value is false.
  • gfactors (Growfactors class instance or None) – containing record data extrapolation (or “blowup”) factors
  • 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 adjustment-ratios DataFrame; default value is filename of the default adjustment ratios.
  • weights (string or Pandas DataFrame or None) – string describes CSV file in which weights reside; DataFrame already contains weights; None creates empty sample-weights DataFrame; default value is filename of the default weights.
  • start_year (integer) –

    specifies calendar year of the data; default value is PUFCSV_YEAR. NOTE: 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 Tax-Calculator, read the DATAPREP.md file in the top-level 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 filing-unit 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:

Records

Notes

Typical usage is “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.

_adjust(year)[source]

Adjust value of income variables to match SOI distributions

_blowup(year)[source]

Applies to variables the grow factors for specified calendar year.

_read_adjust(adjust_ratios)[source]

Read Records adjustment ratios from file or uses specified DataFrame as data or creates empty DataFrame if None

_read_data(data, exact_calcs)[source]

Read Records data from file or use specified DataFrame as data. Specifies exact array depending on boolean value of exact_calcs.

_read_weights(weights)[source]

Read Records weights from file or use specified DataFrame as data or create empty DataFrame if None.

current_year

Return current calendar year of Records.

increment_year()[source]

Adds one to current year. Also, does blowup and reweighting for the new current year.

static read_var_info()[source]

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

set_current_year(new_current_year)[source]

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

zero_out_changing_calculated_vars()[source]

Set all Records.CHANGING_CALCULATED_VARS to zero.

taxcalc.taxcalcio

Tax-Calculator Input-Output class.

class taxcalc.taxcalcio.TaxCalcIO(input_data, tax_year, reform, assump)[source]

Constructor for the Tax-Calculator Input-Output class.

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.
  • reform (None or string) – None implies no policy reform (current-law policy), or string is name of optional REFORM file.
  • assump (None or string) – None implies economic assumptions are standard assumptions, or string is name of optional ASSUMP file.
Returns:

class instance

Return type:

TaxCalcIO

analyze(writing_output_file=False, output_tables=False, output_graphs=False, output_ceeu=False, output_dump=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 certainty-equivalent expected-utility statistics
  • output_dump (boolean) – whether or not to replace standard output with all input and calculated variables using their Tax-Calculator names
Returns:

Return type:

Nothing

static annual_analysis(input_data, tax_year, reform, assump, aging_input_data, exact_calculations, growdiff_response, year, writing_output_file, output_tables, output_graphs, output_ceeu, output_dump)[source]

Conduct static analysis for specifed year and growdiff_response.

Parameters:
  • six parameters are same as the first six parameters of (First) –
  • TaxCalcIO.init method. (the) –
  • five parameters are same as the first five parameters of (Last) –
  • TaxCalcIO.analyze method. (the) –
Returns:

gd_dict

Return type:

Growdiff sub-dictionary for year+1

static ceeu_output(cedict)[source]

Extract –ceeu output and return as text string.

dump_output(mtr_inctax, mtr_paytax)[source]

Extract –dump output and return as pandas DataFrame.

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

High-level logic for dynamic analysis using GrowModel class.

Parameters:
  • six parameters are same as the first six parameters of (First) –
  • TaxCalcIO.init method. (the) –
  • five parameters are same as the first five parameters of (Last) –
  • TaxCalcIO.analyze method. (the) –
Returns:

Return type:

Nothing

init(input_data, tax_year, reform, assump, growdiff_response, aging_input_data, exact_calculations)[source]

TaxCalcIO class post-constructor method that completes initialization.

Parameters:
  • four parameters are same as for TaxCalcIO constructor (First) – input_data, tax_year, 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 “stair-step” provisions in the tax law.
minimal_output()[source]

Extract minimal output and return as pandas DataFrame.

output_filepath()[source]

Return full path to output file named in TaxCalcIO constructor.

tax_year()[source]

Returns 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.

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, mtr_paytax, mtr_inctax)[source]

Write output to CSV-formatted file.

write_tables_file()[source]

Write tables to text file.

taxcalc.utils

Tax-Calculator utility functions.

taxcalc.utils.add_columns(pdf)[source]

Add several columns to specified Pandas DataFrame.

taxcalc.utils.add_income_bins(pdf, compare_with='soi', bins=None, right=True, income_measure='expanded_income')[source]

Add a column of income bins of income_measure using pandas ‘cut’. This will serve as a ‘grouper’ later on.

Parameters:
  • pdf (Pandas DataFrame object) – the object to which we are adding bins
  • compare_with (String, optional) – options for input: ‘tpc’, ‘soi’, ‘webapp’ determines which types of bins will be added default: ‘soi’
  • bins (iterable of scalars, optional income breakpoints.) – Follows pandas convention. The breakpoint is inclusive if right=True. This argument overrides any choice of compare_with.
  • right (bool, optional) – Indicates whether the bins include the rightmost edge or not. If right == True (the default), then the bins [1,2,3,4] indicate (1,2], (2,3], (3,4].
Returns:

pdf – the original input that bins have been added to

Return type:

Pandas DataFrame object

taxcalc.utils.add_weighted_income_bins(pdf, num_bins=10, labels=None, income_measure='expanded_income', weight_by_income_measure=False)[source]

Add a column of income bins to specified Pandas DataFrame, pdf, with the new column being named ‘bins’. Assumes that specified pdf contains columns for the specified income_measure and for sample weights, s006.

taxcalc.utils.agi_weighted(pdf, col_name)[source]

Return AGI-weighted mean of Pandas DataFrame col_name items.

taxcalc.utils.ascii_output(csv_filename, ascii_filename)[source]

Converts csv output from Calculator into ascii output with uniform columns and transposes data so columns are rows and rows are columns. In an ipython notebook, you can import this function from the utils module.

taxcalc.utils.atr_graph_data(calc1, calc2, mars='ALL', atr_measure='combined', min_avginc=1000)[source]

Prepare average tax rate data needed by xtr_graph_plot utility function.

Parameters:
  • calc1 (a Calculator object that refers to baseline policy) –
  • calc2 (a Calculator object that refers to reform policy) –
  • mars (integer or string) –
    options:
    ‘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; and 4: include only head-of-household filing units.

    specifies which filing status subgroup to show in the graph

  • atr_measure (string) –
    options:
    ‘itax’: average individual income tax rate; ‘ptax’: average payroll tax rate; and ‘combined’: sum of average income and payroll tax rates.

    specifies which average tax rate to show on graph’s y axis

  • min_avginc (float) – specifies the minimum average expanded income for a percentile to be included in the graph data
Returns:

Return type:

dictionary object suitable for passing to xtr_graph_plot utility function

taxcalc.utils.ce_aftertax_income(calc1, calc2, custom_params=None, require_no_agg_tax_change=True)[source]

Return dictionary that contains certainty-equivalent of the expected utility of after-tax income computed for constant-relative-risk-aversion parameter values for each of two Calculator objects: calc1, which represents the pre-reform situation, and calc2, 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.

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
Returns:

Return type:

certainty-equivalent of specified expected utility, exputil

taxcalc.utils.count_gt_zero(data)[source]

Return unweighted count of positive data items.

taxcalc.utils.count_lt_zero(data)[source]

Return unweighted count of negative data items.

taxcalc.utils.create_diagnostic_table(calc)[source]

Extract diagnostic table from specified Calculator object. This function leaves the specified calc object unchanged.

Parameters:calc (Calculator class object) –
Returns:
Return type:Pandas DataFrame object containing the table for calc.current_year
taxcalc.utils.create_difference_table(recs1, recs2, groupby, income_measure='expanded_income', income_to_present='iitax')[source]

Get results from two different Records objects for the same year, compare the two results, and return the differences as a Pandas DataFrame that is sorted according to the variable specified by the groupby argument.

Parameters:
  • recs1 (a Tax-Calculator Records object that refers to the baseline) –
  • recs2 (a Tax-Calculator Records object that refers to the reform) –
  • groupby (String object) – options for input: ‘weighted_deciles’, ‘small_income_bins’, ‘large_income_bins’, ‘webapp_income_bins’ determines how the columns in the resulting Pandas DataFrame are sorted
  • income_measure (String object) – options for input: ‘expanded_income’, ‘iitax’ classifier of income bins/deciles
  • income_to_present (String object) – options for input: ‘iitax’, ‘payrolltax’, ‘combined’
Returns:

Return type:

Pandas DataFrame object

taxcalc.utils.create_distribution_table(obj, groupby, result_type, income_measure='expanded_income', baseline_obj=None, diffs=False)[source]

Get results from object, sort them based on groupby, manipulate them based on result_type, and return them as a table.

Parameters:
  • obj (any object with array-like attributes named as in STATS_COLUMNS list) – Examples include a Tax-Calculator Records object and a Pandas DataFrame object, but if baseline_obj is specified, both obj and baseline_obj must have a current_year attribute
  • groupby (String object) – options for input: ‘weighted_deciles’, ‘small_income_bins’, ‘large_income_bins’, ‘webapp_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 data should be manipulated
  • baseline_obj (any object with array-like attributes named as in) – the STATS_COLUMNS list and having a current_year attribute Examples include a Tax-Calculator Records object
  • diffs (boolean) – indicates showing the results from reform or the difference between the baseline and reform. Turn this switch to True if you want to see the difference

Notes

Taxpayer Characteristics:

c04470 : Total itemized deduction

c00100 : AGI (Defecit)

c09600 : Alternative minimum tax

s006 : filing unit sample weight

Returns:
Return type:Pandas DataFrame object
taxcalc.utils.delete_file(filename)[source]

Remove specified file if it exists.

taxcalc.utils.diagnostic_table_odict(recs)[source]

Extract diagnostic table dictionary from specified Records object.

Parameters:recs (Records class object) –
Returns:
Return type:ordered dictionary of variable names and aggregate weighted values
taxcalc.utils.expanded_income_weighted(pdf, col_name)[source]

Return expanded-income-weighted mean of Pandas DataFrame col_name items.

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
Returns:

Return type:

expected utility of consumption array

taxcalc.utils.get_sums(pdf, not_available=False)[source]

Compute unweighted sum of items in each column of a Pandas DataFrame.

Returns:
Return type:Pandas Series object containing column sums indexed by pdf colum 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
Returns:

Return type:

utility of consumption

taxcalc.utils.means_and_comparisons(col_name, gpdf, weighted_total)[source]

Return new Pandas DataFrame based on grouped values of specified col_name in specified gpdf Pandas DataFrame. col_name: the column name to calculate against gpdf: grouped Pandas DataFrame

taxcalc.utils.mtr_graph_data(calc1, calc2, 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:
  • calc1 (a Calculator object that refers to baseline policy) –
  • calc2 (a Calculator object that refers to reform policy) –
  • mars (integer or string) –
    options:
    ‘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; and 4: include only head-of-household filing units.

    specifies which filing status subgroup to show in the graph

  • mtr_measure (string) –
    options:
    ‘itax’: marginal individual income tax rate; ‘ptax’: marginal payroll tax rate; and ‘combined’: sum of marginal income and payroll tax rates.

    specifies which marginal tax rate to show on graph’s y axis

  • 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) –
    options:
    ‘wages’: wage and salary income (e00200); ‘agi’: adjusted gross income, AGI (c00100); and ‘expanded_income’: sum of AGI, non-taxable interest income,
    non-taxable social security benefits, and employer share of FICA taxes.

    specifies which income variable to show on the graph’s x axis

  • 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.multiyear_diagnostic_table(calc, num_years=0)[source]

Generate multi-year diagnostic table from specified Calculator object. This function leaves the specified calc object unchanged.

Parameters:
  • calc (Calculator class object) –
  • num_years (integer (must be between 1 and number of available calc years)) –
Returns:

Return type:

Pandas DataFrame object containing the multi-year diagnostic table

taxcalc.utils.read_egg_csv(fname, **kwargs)[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.read_json_from_file(path)[source]

Return a dict of data loaded from the json file stored at path.

taxcalc.utils.requires_bokeh(func)[source]

Decorator for functions that require the bokeh package. If BOKEH_AVAILABLE=True, this does nothing. IF BOKEH_AVAILABLE=False, we raise an exception and tell the caller that they must install the bokeh package in order to use the function.

taxcalc.utils.results(obj)[source]

Get results from object and organize them into a table.

Parameters:obj (any object with array-like attributes named as in STATS_COLUMNS list) – Examples include a Tax-Calculator Records object and a Pandas DataFrame object
Returns:
Return type:Pandas DataFrame object
taxcalc.utils.string_to_number(string)[source]

Return either integer or float conversion of specified string.

taxcalc.utils.temporary_filename(suffix='')[source]

Return string containing filename.

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

Return unweighted sum of Pandas DataFrame col_name items.

taxcalc.utils.wage_weighted(pdf, col_name)[source]

Return wage-weighted mean of Pandas DataFrame col_name items.

taxcalc.utils.weighted(pdf, col_names)[source]

Return Pandas DataFrame in which each pdf column variable has been multiplied by the s006 weight variable in the specified Pandas DataFrame.

taxcalc.utils.weighted_avg_allcols(pdf, col_list, income_measure='expanded_income')[source]

Return Pandas DataFrame in which variables in col_list of pdf have their weighted_mean computed using the specifed income_measure, except for certain count-like column variables whose sum is computed.

taxcalc.utils.weighted_count(pdf)[source]

Return weighted count of items in Pandas DataFrame.

taxcalc.utils.weighted_count_gt_zero(pdf, col_name, tolerance=0.001)[source]

Return weighted count of positive Pandas DateFrame col_name items.

taxcalc.utils.weighted_count_lt_zero(pdf, col_name, tolerance=-0.001)[source]

Return weighted count of negative Pandas DateFrame col_name items.

taxcalc.utils.weighted_mean(pdf, col_name)[source]

Return weighted mean of Pandas DataFrame col_name items.

taxcalc.utils.weighted_perc_dec(pdf, col_name)[source]

Return weighted fraction (not percent) of negative values for the variable with col_name in the specified Pandas DataFrame.

taxcalc.utils.weighted_perc_inc(pdf, col_name)[source]

Return weighted fraction (not percent) of positive values for the variable with col_name in the specified Pandas DataFrame.

taxcalc.utils.weighted_share_of_total(pdf, col_name, total)[source]

Return ratio of weighted_sum(pdf, col_name) and specified total.

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

Return weighted sum of Pandas DataFrame col_name items.

taxcalc.utils.write_graph_file(*args, **kwargs)[source]

Raise error if bokeh package is not available.

taxcalc.utils.write_json_to_file(data, path, indent=4, sort_keys=False)[source]

Write data to a file at path in json format.

taxcalc.utils.xtr_graph_plot(*args, **kwargs)[source]

Raise error if bokeh package is not available.

taxcalc.cli.tc

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

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

Compare expected and actual test output files.

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

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

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

Write test input and expected output files.