Taxcalc-Payroll Calculator#

Taxcalc-Payroll Calculator

taxcalcpayroll.calculator#

class taxcalcpayroll.calculator.Calculator(policy=None, records=None, verbose=False, sync_years=True, consumption=None)[source]#

Constructor for the Calculator class.

Parameters:

  • policy (Policy class object) – this argument must be specified and object is copied for internal use

  • records (Records class object) – this argument must be specified and object is copied for internal use

  • verbose (boolean) – specifies whether or not to write to stdout data-loaded and data-extrapolated progress reports; default value is false.

  • sync_years (boolean) – specifies whether or not to synchronize policy year and records year; default value is true.

  • consumption (Consumption class object) – specifies consumption response assumptions used to calculate “effective” marginal tax rates; default is None, which implies no consumption responses assumed in marginal tax rate calculations; when argument is an object it is copied for internal use; also specifies consumption value of in-kind benefis with no in-kind consumption values specified implying consumption value is equal to government cost of providing the in-kind benefits

Raises:

ValueError: – if parameters are not the appropriate type.

Returns:

class instance

Return type:

Calculator

Notes

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

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

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

_calc_one_year(zero_out_calc_vars=False)[source]#

Call all the functions except those in the calc_all() method.

_taxinc_to_amt()[source]#

Call TaxInc through AMT functions.

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

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

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

Parameters:

  • calc (Calculator object) – calc represents the reform while self represents the baseline, where both self and calc have calculated taxes for this year before being used by this method

  • mars (integer or string) –

    specifies which filing status subgroup to show in the graph

    • ’ALL’: include all filing units in sample

    • 1: include only single filing units

    • 2: include only married-filing-jointly filing units

    • 3: include only married-filing-separately filing units

    • 4: include only head-of-household filing units

  • atr_measure (string) –

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

    • ’itax’: average individual income tax rate

    • ’ptax’: average payroll tax rate

    • ’combined’: sum of average income and payroll tax rates

  • pop_quantiles (boolean) – specifies whether or not weighted_deciles contain an equal number of people (True) or an equal number of filing units (False)

Return type:

graph that is a bokeh.plotting figure object

calc_all(zero_out_calc_vars=False)[source]#

Call all tax-calculation functions for the current_year.

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

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

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

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

consump_benval_params()[source]#

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

consump_param(param_name)[source]#

Return value of named parameter in embedded Consumption object.

dataframe(variable_list, all_vars=False)[source]#

Return Pandas DataFrame containing the listed variables from the embedded Records object. If all_vars is True, then the variable_list is ignored and all variables used as input to and calculated by the Calculator.calc_all() method (which does not include marginal tax rates) are included in the returned Pandas DataFrame.

diagnostic_table(num_years)[source]#

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

Parameters:

num_years (Integer) – number of years to include in diagnostic table starting with the Calculator object’s current_year (must be at least one and no more than what would exceed Policy end_year)

Return type:

Pandas DataFrame object containing the multi-year diagnostic table

difference_table(calc, groupby, tax_to_diff, pop_quantiles=False)[source]#

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

Parameters:

  • calc (Calculator object) – calc represents the reform while self represents the baseline

  • groupby (String object) – options for input: ‘weighted_deciles’, ‘standard_income_bins’ determines how the columns in resulting Pandas DataFrame are sorted

  • tax_to_diff (String object) – options for input: ‘iitax’, ‘payrolltax’, ‘combined’ specifies which tax to difference

  • pop_quantiles (boolean) – specifies whether or not weighted_deciles contain an equal number of people (True) or an equal number of filing units (False)

  • usage (Returns and typical) –

  • ------------------------- –

  • calc1.difference_table(calc2 (diff =) –

  • 'weighted_deciles' –

  • 'iitax') –

  • object ((where calc1 is a baseline Calculator) –

  • object). (and calc2 is a reform Calculator) –

  • DataFrame (The returned diff is a difference table as a Pandas) –

  • rows. (with DIST_TABLE_COLUMNS and groupby) –

  • NOTE (when groupby is 'weighted_deciles', the returned table has three) – extra rows containing top-decile detail consisting of statistics for the 0.90-0.95 quantile range (bottom half of top decile), for the 0.95-0.99 quantile range, and for the 0.99-1.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 0-10n row label), zero (denoted by a 0-10z row label), and positive (denoted by a 0-10p row label) values of the specified income_measure.

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

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

Parameters:

  • calc (Calculator object or None) – typically represents the reform while self represents the baseline; if calc is None, the second returned table is None

  • groupby (String object) –

    options for input: ‘weighted_deciles’, ‘standard_income_bins’,

    ’soi_agi_bins’

    determines how the columns in resulting Pandas DataFrame are sorted

  • pop_quantiles (boolean) – specifies whether or not weighted_deciles contain an equal number of people (True) or an equal number of filing units (False)

  • scaling (boolean) – specifies create_distribution_table utility function argument that determines whether table entry values are scaled or not

  • usage (Return and typical) –

  • ------------------------ –

  • dist1 –

  • calc1.distribution_tables(calc2 (dist2 =) –

  • 'weighted_deciles') –

  • OR –

  • dist1 –

  • calc1.distribution_tables(None (_ =) –

  • 'weighted_deciles') –

  • object ((where calc1 is a baseline Calculator) –

  • object). (and calc2 is a reform Calculator) –

  • a (Each of the dist1 and optional dist2 is a distribution table as) –

  • rows. (Pandas DataFrame with DIST_TABLE_COLUMNS and groupby) –

  • NOTE (when groupby is 'weighted_deciles', the returned tables have 3) – extra rows containing top-decile detail consisting of statistics for the 0.90-0.95 quantile range (bottom half of top decile), for the 0.95-0.99 quantile range, and for the 0.99-1.00 quantile range (top one percent); and the returned table splits the bottom decile into filing units with negative (denoted by a 0-10n row label), zero (denoted by a 0-10z row label), and positive (denoted by a 0-10p row label) values of the specified income_measure.

incarray(variable_name, variable_add)[source]#

Add variable_add to named variable in embedded Records object.

increment_year()[source]#

Advance all embedded objects to next year.

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

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

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

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

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

Parameters:

  • variable_str (string) – specifies type of income or expense that is increased to compute the marginal tax rates. See Notes for list of valid variables.

  • negative_finite_diff (boolean) – specifies whether or not marginal tax rates are computed by subtracting (rather than adding) a small finite_diff amount to the specified variable.

  • zero_out_calculated_vars (boolean) – specifies value of zero_out_calc_vars parameter used in calls of Calculator.calc_all() method.

  • calc_all_already_called (boolean) – specifies whether self has already had its Calculor.calc_all() method called, in which case this method will not do a final calc_all() call but use the incoming embedded Records object as the outgoing Records object embedding in self.

  • wrt_full_compensation (boolean) – specifies whether or not marginal tax rates on earned income are computed with respect to (wrt) changes in total compensation that includes the employer share of OASDI and HI payroll taxes.

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 self-employment income (also in e00900); ‘e00300’, taxable interest income; ‘e00400’, federally-tax-exempt interest income; ‘e00600’, all dividends included in AGI ‘e00650’, qualified dividends (also included in e00600) ‘e01400’, federally-taxable IRA distribution; ‘e01700’, federally-taxable pension benefits; ‘e02000’, Schedule E total net income/loss ‘e02400’, all social security (OASDI) benefits; ‘p22250’, short-term capital gains; ‘p23250’, long-term capital gains; ‘e18500’, Schedule A real-estate-tax paid; ‘e19200’, Schedule A interest paid; ‘e26270’, S-corporation/partnership income (also included in e02000); ‘e19800’, Charity cash contributions; ‘e20100’, Charity non-cash contributions; ‘k1bx14p’, Partnership income (also included in e26270 and e02000).

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

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

Parameters:

  • calc (Calculator object) – calc represents the reform while self represents the baseline

  • mars (integer or string) –

    specifies which filing status subgroup to show in the graph

    • ’ALL’: include all filing units in sample

    • 1: include only single filing units

    • 2: include only married-filing-jointly filing units

    • 3: include only married-filing-separately filing units

    • 4: include only head-of-household filing units

  • mtr_measure (string) –

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

    • ’itax’: marginal individual income tax rate

    • ’ptax’: marginal payroll tax rate

    • ’combined’: sum of marginal income and payroll tax rates

  • mtr_variable (string) – any string in the Calculator.VALID_MTR_VARS set specifies variable to change in order to compute marginal tax rates

  • alt_e00200p_text (string) – text to use in place of mtr_variable when mtr_variable is ‘e00200p’; if empty string then use ‘e00200p’

  • mtr_wrt_full_compen (boolean) – see documentation of Calculator.mtr() argument wrt_full_compensation (value has an effect only if mtr_variable is ‘e00200p’)

  • income_measure (string) –

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

    • ’wages’: wage and salary income (e00200)

    • ’agi’: adjusted gross income, AGI (c00100)

    • ’expanded_income’: broader than AGI (see definition in

      calcfunctions.py file).

  • pop_quantiles (boolean) – specifies whether or not weighted_deciles contain an equal number of people (True) or an equal number of filing units (False)

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

Return type:

graph that is a bokeh.plotting figure object

n65()[source]#

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

pch_graph(calc, pop_quantiles=False)[source]#

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

Parameters:

  • calc (Calculator object) – calc represents the reform while self represents the baseline, where both self and calc have calculated taxes for this year before being used by this method

  • pop_quantiles (boolean) – specifies whether or not weighted_deciles contain an equal number of people (True) or an equal number of filing units (False)

Return type:

graph that is a bokeh.plotting figure object

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(reform, assump)[source]#

Read JSON reform and assump objects and return a composite dictionary containing four key:dict pairs: ‘policy’:dict, ‘consumption’:dict, ‘growdiff_baseline’:dict, and ‘growdiff_response’:dict.

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

Also note that either of the two function arguments can be strings containing a valid JSON string (rather than a local filename).

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

The reform file/URL contents or JSON string must be like this: {“policy”: {…}} OR {…} (in other words, the top-level policy key is optional) and the assump file/URL contents or JSON string must be like this: {“consumption”: {…},

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

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

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

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

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

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

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

Generate reform documentation versus current-law policy.

Parameters:

  • params (dict) – dictionary is structured like dict returned from the static Calculator.read_json_param_objects() method

  • policy_dicts (list of dict or None) – each dictionary in list is a params[‘policy’] dictionary representing second and subsequent elements of a compound reform; None implies no compound reform with the simple reform characterized in the params[‘policy’] dictionary

Returns:

doc – the documentation for the specified policy reform

Return type:

String

restore_records()[source]#

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

store_records()[source]#

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

total_weight()[source]#

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

weighted_total(variable_name)[source]#

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

zeroarray(variable_name)[source]#

Set named variable in embedded Records object to zeros.