ParamTools
Define, update, and validate your model's parameters.
How to use ParamTools
Subclass paramtools.Parameters and define your model's parameters:
import paramtools
class TaxParams(paramtools.Parameters):
defaults = {
"schema": {
"labels": {
"year": {
"type": "int",
"validators": {"range": {"min": 2013, "max": 2027}}
},
"marital_status": {
"type": "str",
"validators": {"choice": {"choices": ["single", "joint"]}}
},
},
"additional_members": {
"cpi_inflatable": {"type": "bool", "number_dims": 0},
"cpi_inflated": {"type": "bool", "number_dims": 0}
}
},
"standard_deduction": {
"title": "Standard deduction amount",
"description": "Amount filing unit can use as a standard deduction.",
"cpi_inflatable": True,
"cpi_inflated": True,
"type": "float",
"value": [
{"year": 2024, "marital_status": "single", "value": 13673.68},
{"year": 2024, "marital_status": "joint", "value": 27347.36},
{"year": 2025, "marital_status": "single", "value": 13967.66},
{"year": 2025, "marital_status": "joint", "value": 27935.33},
{"year": 2026, "marital_status": "single", "value": 7690.0},
{"year": 2026, "marital_status": "joint", "value": 15380.0}],
"validators": {
"range": {
"min": 0,
"max": 9e+99
}
}
},
}
params = TaxParams(
initial_state={"year": [2024, 2025, 2026]},
array_first=True
)
Check out the state:
params.view_state()
# {'year': [2024, 2025, 2026]}Parameters are available via instance attributes:
params.standard_deduction
# array([[13673.68, 27347.36],
# [13967.66, 27935.33],
# [ 7690. , 15380. ]])Take a look at the standard deduction parameter's labels:
params.from_array("standard_deduction")
# [{'year': 2024, 'marital_status': 'single', 'value': 13673.68},
# {'year': 2024, 'marital_status': 'joint', 'value': 27347.36},
# {'year': 2025, 'marital_status': 'single', 'value': 13967.66},
# {'year': 2025, 'marital_status': 'joint', 'value': 27935.33},
# {'year': 2026, 'marital_status': 'single', 'value': 7690.0},
# {'year': 2026, 'marital_status': 'joint', 'value': 15380.0}]Query the parameters:
params.specification(year=2026, marital_status="single", use_state=False)
# OrderedDict([('standard_deduction',
# [{'value': 0.0, 'year': 2026, 'marital_status': 'single'}])])Adjust the default values:
adjustment = {
"standard_deduction": [
{"year": 2026, "marital_status": "single", "value": 10000.0}
],
}
params.adjust(adjustment)
params.standard_deduction
# array([[13673.68, 27347.36],
# [13967.66, 27935.33],
# [10000. , 15380. ]])Set all values of the standard deduction parameter to 0:
adjustment = {
"standard_deduction": 0,
}
params.adjust(adjustment)
params.standard_deduction
# array([[0., 0.],
# [0., 0.],
# [0., 0.]])Errors on invalid input:
adjustment["standard_deduction"] = "higher"
params.adjust(adjustment)
# ---------------------------------------------------------------------------
# ValidationError Traceback (most recent call last)
# <ipython-input-7-d9ad03cf54d8> in <module>
# 1 adjustment["standard_deduction"] = "higher"
# ----> 2 params.adjust(adjustment)
# ~/Documents/ParamTools/paramtools/parameters.py in adjust(self, params_or_path, raise_errors)
# 134
# 135 if raise_errors and self._errors:
# --> 136 raise self.validation_error
# 137
# 138 # Update attrs.
# ValidationError: {'standard_deduction': ['Not a valid number: higher.']}Errors on input that's out of range:
adjustment["standard_deduction"] = [
{"marital_status": "single", "year": 2025, "value": -1}
]
params.adjust(adjustment)
# output:
# ---------------------------------------------------------------------------
# ValidationError Traceback (most recent call last)
# <ipython-input-14-208948dfbd1d> in <module>
# 1 adjustment["standard_deduction"] = [{"marital_status": "single", "year": 2025, "value": -1}]
# ----> 2 params.adjust(adjustment)
# ~/Documents/ParamTools/paramtools/parameters.py in adjust(self, params_or_path, raise_errors, extend_adj)
# 183
# 184 if raise_errors and self._errors:
# --> 185 raise self.validation_error
# 186
# 187 if self.label_to_extend is not None and extend_adj:
# ValidationError: {
# "standard_deduction": [
# "standard_deduction[marital_status=single, year=2025] -1.0 < min 0 "
# ]
# }How to install ParamTools
Install with conda:
conda install -c conda-forge paramtools
Install from source:
git clone https://github.com/PSLmodels/ParamTools
cd ParamTools
conda env create
conda activate paramtools-dev
pip install -e .
# optionally run tests:
py.test -v
Documentation
Full documentation available at paramtools.dev.
Contributing
Contributions are welcome! Checkout CONTRIBUTING.md to get started.
Credits
ParamTools is built on top of the excellent marshmallow JSON schema and validation framework. I encourage everyone to check out their repo and documentation. ParamTools was modeled off of Tax-Calculator's parameter processing and validation engine due to its maturity and sophisticated capabilities.