Skip to content

Commit

Permalink
Merge pull request #51 from PSLmodels/mkdocs
Browse files Browse the repository at this point in the history 
Re-write documentation and use mkdocs
  • Loading branch information
@hdoupe
hdoupe authored Apr 24, 2019
2 parents cacc7d3 + a8957db commit 05fdf10
Show file tree
Hide file tree
Showing 21 changed files with 878 additions and 1,363 deletions.
2 changes: 1 addition & 1 deletion .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ repos:
rev: 18.9b0
hooks:
- id: black
language_version: python3.7
language_version: python3
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.1.0
hooks:
Expand Down
4 changes: 0 additions & 4 deletions MANIFEST.in
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1 @@
include paramtools/examples/baseball/*.json
include paramtools/examples/weather/*.json
include paramtools/examples/taxparams/*.json
include paramtools/examples/taxparams-demo/*.json
include paramtools/examples/behresp/*.json
4 changes: 2 additions & 2 deletions PSL_catalog.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -38,8 +38,8 @@
"start_header": null,
"end_header": null,
"type": "html",
"source": "https://paramtools.readthedocs.io/en/latest/",
"data": "<a href=\"https://paramtools.readthedocs.io/en/latest/\">https://paramtools.readthedocs.io/en/latest/</a>"
"source": "https://paramtools.org",
"data": "<a href=\"https://paramtools.org\">https://paramtools.org</a>"
},
"user_changelog": {
"start_header": null,
Expand Down
196 changes: 123 additions & 73 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,127 +1,177 @@
# 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.
Define, update, and validate your model's parameters.

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:
Subclass `paramtools.Parameters` and define your model's [parameters](https://paramtools.org/parameters):

```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
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
)

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

```

Check out the state:

```python
params.view_state()

# {'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. ]]


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

Get the parameter's [value object](https://paramtools.readthedocs.io/en/latest/spec.html#value-object):
Take a look at the standard deduction parameter's labels:
```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}]

# [{'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](https://paramtools.readthedocs.io/en/latest/spec.html#adjustment-schema) the default specification:
Adjust the default values:

```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 ]
# 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"] = [{
"year": 2026,
"marital_status": "single",
"value": "higher"
}]
adjustment["standard_deduction"] = "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.']}
# ---------------------------------------------------------------------------
# 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
# 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}])])

adjustment["standard_deduction"] = -1
params.adjust(adjustment)
params.adjust(adjustment)

ii_bracket_2_val = spec["ii_bracket_2"][0]["value"]
ii_bracket_2_val
# output: 45957.0
# ---------------------------------------------------------------------------
# ValidationError Traceback (most recent call last)
# <ipython-input-8-8ea95339bb9b> in <module>
# 1 adjustment["standard_deduction"] = -1
# ----> 2 params.adjust(adjustment)

adjustment = {
"standard_deduction": [{
"year": 2026,
"marital_status": "single",
"value": -1
}],
"ii_bracket_1": [{
"year": 2026,
"marital_status": "single",
"value": ii_bracket_2_val + 1}
]
}
# ~/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.

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

```

Expand Down Expand Up @@ -149,15 +199,15 @@ py.test -v

Documentation
----------------
Full documentation available at https://paramtools.readthedocs.io/.
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 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.
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
Expand Down
20 changes: 0 additions & 20 deletions docs/Makefile
View file

This file was deleted.

Loading

0 comments on commit 05fdf10

Please sign in to comment.