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
and default
specification
files:
from paramtools import Parameters
from paramtools import get_example_paths
# Get paths to weather example files.
schema_, defaults_ = get_example_paths('weather')
class WeatherParams(Parameters):
schema = schema_ # "schema.json"
defaults = defaults_ # "defaults.json"
params = WeatherParams(
initial_state={"month": "November", "dayofmonth": 1},
array_first=True
)
print(params.state)
# output: {'month': 'November', 'dayofmonth': 1}
Parameters are available via instance attributes:
print(params.average_precipitation)
# output: [[3.6] [3. ]]
Get the parameter’s value object:
print(params.from_array("average_precipitation"))
# output: [{'city': 'Atlanta, GA', 'month': 'November', 'value': 3.6}, {'city': 'Washington, D.C.', 'month': 'November', 'value': 3.0}]
Adjust the default specification:
adjustment = {
"average_precipitation": [
{"city": "Washington, D.C.", "month": "November", "value": 10},
{"city": "Atlanta, GA", "month": "November", "value": 15},
]
}
params.adjust(adjustment)
print(params.from_array("average_precipitation"))
# output: [{'city': 'Atlanta, GA', 'month': 'November', 'value': 15.0}, {'city': 'Washington, D.C.', 'month': 'November', 'value': 10.0}]
print(params.average_precipitation)
# output: [[15.] [10.]]
Errors on invalid input:
adjustment["average_precipitation"][0]["value"] = "rainy"
params.adjust(adjustment)
# output:
Traceback (most recent call last):
File "doc_ex.py", line 40, in <module>
raise saved_exc
File "doc_ex.py", line 30, in <module>
params.adjust(adjustment)
File "/home/henrydoupe/Documents/ParamTools/paramtools/parameters.py", line 123, in adjust
raise self.validation_error
paramtools.exceptions.ValidationError: {'average_precipitation': ['Not a valid number: rainy.']}
Errors on input that’s out of range:
adjustment["average_precipitation"][0]["value"] = 1000
adjustment["average_precipitation"][1]["value"] = 2000
params.adjust(adjustment, raise_errors=False)
print(params.errors)
# output: {'average_precipitation': ['average_precipitation 1000.0 must be less than 50 for dimensions city=Washington, D.C. , month=November', 'average_precipitation 2000.0 must be less than 50 for dimensions city=Atlanta, GA , month=November']}
How to install ParamTools¶
Install from PyPI:
pip install paramtools
Install from source:
git clone https://github.com/hdoupe/ParamTools
cd ParamTools
pip install -e .
Documentation¶
Full documentation available at https://paramtools.readthedocs.io/.
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 checkout their repo and documentation. ParamTools was modeled off of Tax-Calculator’s parameter processing and validation engine due to its maturity and sophisticated capabilities.