Metadata-Version: 2.1
Name: paramtools
Version: 0.5.3
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

Define, update, and validate your model's parameters.

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

Subclass `paramtools.Parameters` and define your model's [parameters](https://paramtools.org/parameters):

```python
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:

```python
params.view_state()

# {'year': [2024, 2025, 2026]}

```

Parameters are available via instance attributes:

```python
params.standard_deduction

# array([[13673.68, 27347.36],
#        [13967.66, 27935.33],
#        [ 7690.  , 15380.  ]])
```

Take a look at the standard deduction parameter's labels:
```python
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:
```python
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:

```python
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:

```python
adjustment = {
    "standard_deduction": 0,
}
params.adjust(adjustment)
params.standard_deduction

# array([[0., 0.],
#        [0., 0.],
#        [0., 0.]])

```


Errors on invalid input:
```python
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:
```python
adjustment["standard_deduction"] = -1
params.adjust(adjustment)
params.adjust(adjustment)

# ---------------------------------------------------------------------------
# ValidationError                           Traceback (most recent call last)
# <ipython-input-8-8ea95339bb9b> in <module>
#       1 adjustment["standard_deduction"] = -1
# ----> 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': ['standard_deduction -1.0 must be greater than 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.org](https://paramtools.org).

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 check out 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

