Tax-Calculator Parameters

Tax-Calculator Parameters

taxcalc.parameters

class taxcalc.parameters.Parameters(start_year=None, num_years=None, last_known_year=None, removed=None, redefined=None, wage_indexed=None, **kwargs)

Base class that wraps ParamTools, providing parameter indexing for tax policy in the adjust method and convenience methods like set_year for classes inheriting from it. It also provides a backwards-compatible layer for Tax-Calculator versions prior to 3.0.

The defaults file path may be set through the defaults class attribute variable or through the DEFAULTS_FILE_NAME / DEFAULTS_FILE_PATH work flow.

A custom getter method is implemented so that the value of a parameter over all allowed years can conveniently be retrieved by adding an underscore before the variable name (e.g. EITC_c vs _EITC_c).

This class inherits methods from ParamTools like items:

import taxcalc as tc
pol = tc.Policy()

for name, value in pol.items():
    print(name, value)

# parameter_indexing_CPI_offset [0.]
# FICA_ss_trt_employer [0.062]
# SS_Earnings_c [113700.]

Check out the ParamTools documentation for more information on these inherited methods.

__getattr__(attr)

Get the value of a parameter over all years by accessing it with an underscore in front of its name: pol._EITC_c instead of pol.EITC_c.

static _read_json_revision(obj, topkey)

Read JSON revision specified by obj and topkey returning a single revision dictionary suitable for use with the Parameters._update or Parameters.adjust methods. The obj function argument can be None or a string, where the string can be:

• Path for a local file

• Link pointing to a valid JSON file

• Valid JSON text

The topkey argument must be a string containing the top-level key in a compound-revision JSON text for which a revision dictionary is returned. If the specified topkey is not among the top-level JSON keys, the obj is assumed to be a non-compound-revision JSON text for the specified topkey.

Some examples of valid links are:

• HTTP: https://raw.githubusercontent.com/PSLmodels/Tax-Calculator/master/taxcalc/reforms/2017_law.json

• Github API: github://PSLmodels:Tax-Calculator@master/taxcalc/reforms/2017_law.json

Checkout the ParamTools docs for more information on valid file URLs.

_update(revision, print_warnings, raise_errors)

A translation layer on top of adjust. Projects that have historically used the _update method with Tax-Calculator styled adjustments can continue to do so without making any changes to how they handle adjustments.

Converts reforms that are compatible with Tax-Calculator:

adjustment = {
    "standard_deduction": {2024: [10000.0, 10000.0]},
    "ss_rate": {2024: 0.2}
}

into reforms that are compatible with ParamTools:

{
    "standard_deduction": [
        {"year": 2024, "marital_status": "single", "value": 10000.0},
        {"year": 2024, "marital_status": "joint", "value": 10000.0}
    ],
    "ss_rate": [{"year": 2024, "value": 0.2}]}
}

adjust(params_or_path, print_warnings=True, raise_errors=True, **kwargs)

Update parameter values using a ParamTools styled adjustment.

Parameters:

• params_or_path (Dict, str) –

  New parameter values in the paramtools format. For example:

  {
      "standard_deduction": [
          {"year": 2024, "marital_status": "single", "value": 10000.0},
          {"year": 2024, "marital_status": "joint", "value": 10000.0}
      ],
      "ss_rate": [{"year": 2024, "value": 0.2}]}
  }
  

• print_warnings (Boolean) – Print parameter warnings or not

• raise_errors (Boolean) – Raise errors as a ValidationError. If False, they will be stored in the errors attribute.

Returns:

adjustment – Parsed paremeter dictionary

Return type:

Dict

adjust_with_indexing(params_or_path, **kwargs)

Adjust parameter values with the following indexing logic:

1. If “parameter_indexing_CPI_offset” is adjusted, first set parameter_indexing_CPI_offset to zero before implementing the adjusted parameter_indexing_CPI_offset to avoid stacking adjustments. Then, revert all values of indexed parameters to the ‘known’ values:

   1. The current values of parameters that are being adjusted are deleted after the first year in which parameter_indexing_CPI_offset is adjusted.

   2. The current values of parameters that are not being adjusted (i.e. are not in params) are deleted after the last known year, with the exception of parameters that revert to their pre-TCJA values in 2026. Instead, these (2026) parameter values are recalculated using the new inflation rates.

   After the ‘unknown’ values have been deleted, the last known value is extrapolated through the budget window. If there are indexed parameters in the adjustment, they will be included in the final adjustment call (unless their indexed status is changed).

2. If the “indexed” status is updated for any parameter:

   1. If a parameter has values that are being adjusted before the indexed status is adjusted, update those parameters first.

   2. Extend the values of that parameter to the year in which the status is changed.

   3. Change the indexed status for the parameter.

   4. Update parameter values in adjustment that are adjusted after the year in which the indexed status changes.

   5. Using the new “-indexed” status, extend the values of that parameter through the remaining years or until the -indexed status changes again.

3. Update all parameters that are not indexing related, i.e. they are not “parameter_indexing_CPI_offset” or do not end with “-indexed”.

4. Return parsed adjustment with all adjustments, including “-indexed” parameters.

Notable side-effects:

• All values of a parameter whose indexed status is adjusted are wiped out after the year in which the value is adjusted for the same hard-coding reason.

get_index_rate(param, label_to_extend_val)

Initalize indexing data and return the indexing rate value depending on the parameter name and label_to_extend_val, the value of label_to_extend. Returns: rate to use for indexing.

initialize(start_year, num_years, last_known_year=None, removed=None, redefined=None, wage_indexed=None, **kwargs)

Legacy method for initializing a Parameters instance. Projects should use the __init__ method in the future.

set_rates()

This method is implemented by classes inheriting Parameters.

static years_in_revision(revision)

Return list of years in specified revision dictionary, which is assumed to have a param:year:value format.

taxcalc.parameters.is_paramtools_format(params: str | Mapping[int, Any] | List[ValueObject])

Check first item in params to determine if it is using the ParamTools adjustment or the Tax-Calculator reform format. If first item is a dict, then it is likely be a Tax-Calculator reform. Otherwise, it is likely to be a ParamTools format.

Parameters:

params (dict) –

Either a ParamTools or Tax-Calculator styled parameters dict.

# ParamTools style format:
{
    "ss_rate": {2024: 0.2}
}

# Tax-Calculator style format:
{
    "ss_rate": [{"year": 2024, "value": 0.2}]}
}

Returns:

Whether params is likely to be a ParamTools formatted adjustment or not.

Return type:

bool