Metadata-Version: 2.1
Name: paramtools
Version: 0.4.1
Summary: Library for parameter processing and validation with a focus on computational modeling projects
Home-page: https://github.com/hdoupe/ParamTools
Author: Hank Doupe
Author-email: henrymdoupe@gmail.com
License: UNKNOWN
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Description-Content-Type: text/markdown
Requires-Dist: marshmallow (>=3.*)
Requires-Dist: numpy
Requires-Dist: python-dateutil (>=2.8.0)

# ParamTools

ParamTools defines the parameter input space for computational modeling projects.

- Defines the default parameter space.
- Facilitates adjusting that space.
- Performs validation on the default space and the adjusted space.

How to use ParamTools
---------------------------

Subclass the `Parameters` class and set your [specification schema](https://paramtools.readthedocs.io/en/latest/spec.html#specification-schema) and [default specification](https://paramtools.readthedocs.io/en/latest/spec.html#default-specification) files:

```python
from paramtools import Parameters
from paramtools import get_example_paths

schema_, defaults_ = get_example_paths('taxparams-demo')
class TaxParams(Parameters):
    schema = schema_  # schema.json
    defaults = defaults_  # defaults.json

params = TaxParams(
    initial_state={"year": [2024, 2025, 2026]},
    array_first=True
)

print("# output ", params.view_state())
# output  {'year': [2024, 2025, 2026]}

```

Parameters are available via instance attributes:

```python
params.standard_deduction
# output:  [[13673.68 27347.36 13673.68 20510.52 27347.36]
#  [13967.66 27935.33 13967.66 20951.49 27935.33]
#  [ 7690.   15380.    7690.   11323.   15380.  ]]


```

Get the parameter's [value object](https://paramtools.readthedocs.io/en/latest/spec.html#value-object):
```python
params.from_array("standard_deduction")
# output:  [{'year': 2024, 'marital_status': 'single', 'value': 13673.68}, {'year': 2024, 'marital_status': 'joint', 'value': 27347.36}, {'year': 2024, 'marital_status': 'separate', 'value': 13673.68}, {'year': 2024, 'marital_status': 'headhousehold', 'value': 20510.52}, {'year': 2024, 'marital_status': 'widow', 'value': 27347.36}, {'year': 2025, 'marital_status': 'single', 'value': 13967.66}, {'year': 2025, 'marital_status': 'joint', 'value': 27935.33}, {'year': 2025, 'marital_status': 'separate', 'value': 13967.66}, {'year': 2025, 'marital_status': 'headhousehold', 'value': 20951.49}, {'year': 2025, 'marital_status': 'widow', 'value': 27935.33}, {'year': 2026, 'marital_status': 'single', 'value': 7690.0}, {'year': 2026, 'marital_status': 'joint', 'value': 15380.0}, {'year': 2026, 'marital_status': 'separate', 'value': 7690.0}, {'year': 2026, 'marital_status': 'headhousehold', 'value': 11323.0}, {'year': 2026, 'marital_status': 'widow', 'value': 15380.0}]
```

[Adjust](https://paramtools.readthedocs.io/en/latest/spec.html#adjustment-schema) the default specification:

```python
adjustment = {
    "standard_deduction": [
        {"year": 2026, "marital_status": "single", "value": 10000.0}
    ],
    "social_security_tax_rate": [
        {"year": 2026, "value": 0.14}
    ]
}
params.adjust(adjustment)
params.standard_deduction
# output:  [[13673.68 27347.36 13673.68 20510.52 27347.36]
#  [13967.66 27935.33 13967.66 20951.49 27935.33]
#  [10000.   15380.    7690.   11323.   15380.  ]]

print(params.social_security_tax_rate)
# output:  [0.124 0.124 0.14 ]
```


Errors on invalid input:
```python
adjustment["standard_deduction"] = [{
  "year": 2026,
  "marital_status": "single",
  "value": "higher"
}]
params.adjust(adjustment)

# output:
Traceback (most recent call last):
  File "doc_ex.py", line 60, in <module>
    raise saved_exc
  File "doc_ex.py", line 33, in <module>
    params.adjust(adjustment)
  File "/home/henrydoupe/Documents/ParamTools/paramtools/parameters.py", line 123, in adjust
    raise self.validation_error
paramtools.exceptions.ValidationError: {'standard_deduction': ['Not a valid number: higher.']}

```

Errors on input that's out of range:
```python
# get value of ii_bracket_2 at year 2026, marital status "single".
spec = params.specification(year=2026, marital_status="single", use_state=False)
spec
# output:  OrderedDict([('standard_deduction', [{'year': 2026, 'value': 10000.0, 'marital_status': 'single'}]), ('ii_bracket_1', [{'year': 2026, 'value': 11293.0, 'marital_status': 'single'}]), ('ii_bracket_2', [{'year': 2026, 'value': 45957.0, 'marital_status': 'single'}]), ('social_security_tax_rate', [{'year': 2026, 'value': 0.14}])])


ii_bracket_2_val = spec["ii_bracket_2"][0]["value"]
ii_bracket_2_val
# output: 45957.0

adjustment = {
    "standard_deduction": [{
      "year": 2026,
      "marital_status": "single",
      "value": -1
    }],
    "ii_bracket_1": [{
      "year": 2026,
      "marital_status": "single",
      "value": ii_bracket_2_val + 1}
    ]
}

params.adjust(adjustment, raise_errors=False)
params.errors
# output:
# {
#   'standard_deduction': ['standard_deduction -1.0 must be greater than 0 for dimensions marital_status=single , year=2026'],
#   'ii_bracket_1': ['ii_bracket_1 45958.0 must be less than 45957.0 for dimensions marital_status=single , year=2026']
# }

```

How to install ParamTools
-----------------------------------------

Install from PyPI:

```
conda install paramtools -c pslmodels
```

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 https://paramtools.readthedocs.io/.

Contributing
-------------------------
Contributions are welcome! Checkout [CONTRIBUTING.md][3] to get started.

Credits
---------
ParamTools is built on top of the excellent [marshmallow][1] JSON schema and validation framework. I encourage everyone to checkout their repo and documentation. ParamTools was modeled off of [Tax-Calculator's][2] parameter processing and validation engine due to its maturity and sophisticated capabilities.

[1]: https://github.com/marshmallow-code/marshmallow
[2]: https://github.com/PSLmodels/Tax-Calculator
[3]: https://github.com/PSLmodels/ParamTools/blob/master/CONTRIBUTING.md

