diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index dea67bf..8cd8299 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -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: diff --git a/MANIFEST.in b/MANIFEST.in index 75a9fce..e271e97 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -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 diff --git a/PSL_catalog.json b/PSL_catalog.json index b170be3..9dbe68c 100644 --- a/PSL_catalog.json +++ b/PSL_catalog.json @@ -38,8 +38,8 @@ "start_header": null, "end_header": null, "type": "html", - "source": "https://paramtools.readthedocs.io/en/latest/", - "data": "https://paramtools.readthedocs.io/en/latest/" + "source": "https://paramtools.org", + "data": "https://paramtools.org" }, "user_changelog": { "start_header": null, diff --git a/README.md b/README.md index e1791c0..0f6b44c 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,70 @@ # 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]} ``` @@ -34,94 +72,106 @@ 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 - raise saved_exc - File "doc_ex.py", line 33, in - 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) +# in +# 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) +# in +# 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.']} ``` @@ -149,7 +199,7 @@ py.test -v Documentation ---------------- -Full documentation available at https://paramtools.readthedocs.io/. +Full documentation available at [paramtools.org](https://paramtools.org). Contributing ------------------------- @@ -157,7 +207,7 @@ 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 diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index 5ae6b25..0000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# Minimal makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -SPHINXPROJ = ParamTools -SOURCEDIR = source -BUILDDIR = build - -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) - -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/README Example.ipynb b/docs/README Example.ipynb new file mode 100644 index 0000000..4044d90 --- /dev/null +++ b/docs/README Example.ipynb @@ -0,0 +1,374 @@ +{ + "cells": [ + { + "cell_type": "code", + "execution_count": 1, + "metadata": {}, + "outputs": [], + "source": [ + "from paramtools import Parameters\n", + "\n", + "class TaxParams(Parameters):\n", + " defaults = {\n", + " \"schema\": {\n", + " \"labels\": {\n", + " \"year\": {\n", + " \"type\": \"int\",\n", + " \"validators\": {\"range\": {\"min\": 2013, \"max\": 2027}}\n", + " },\n", + " \"marital_status\": {\n", + " \"type\": \"str\",\n", + " \"validators\": {\"choice\": {\"choices\": [\"single\", \"joint\"]}}\n", + " },\n", + " },\n", + " \"additional_members\": {\n", + " \"cpi_inflatable\": {\"type\": \"bool\", \"number_dims\": 0},\n", + " \"cpi_inflated\": {\"type\": \"bool\", \"number_dims\": 0}\n", + " }\n", + " },\n", + " \"standard_deduction\": {\n", + " \"title\": \"Standard deduction amount\",\n", + " \"description\": \"Amount filing unit can use as a standard deduction.\",\n", + " \"cpi_inflatable\": True,\n", + " \"cpi_inflated\": True,\n", + " \"type\": \"float\",\n", + " \"value\": [\n", + " {\"year\": 2024, \"marital_status\": \"single\", \"value\": 13673.68},\n", + " {\"year\": 2024, \"marital_status\": \"joint\", \"value\": 27347.36},\n", + " {\"year\": 2025, \"marital_status\": \"single\", \"value\": 13967.66},\n", + " {\"year\": 2025, \"marital_status\": \"joint\", \"value\": 27935.33},\n", + " {\"year\": 2026, \"marital_status\": \"single\", \"value\": 7690.0},\n", + " {\"year\": 2026, \"marital_status\": \"joint\", \"value\": 15380.0}],\n", + " \"validators\": {\n", + " \"range\": {\n", + " \"min\": 0,\n", + " \"max\": 9e+99\n", + " }\n", + " }\n", + " },\n", + " }\n", + "\n", + "params = TaxParams(\n", + " initial_state={\"year\": [2024, 2025, 2026]},\n", + " array_first=True\n", + ")\n", + "\n" + ] + }, + { + "cell_type": "code", + "execution_count": 2, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "{'year': [2024, 2025, 2026]}" + ] + }, + "execution_count": 2, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "params.view_state()" + ] + }, + { + "cell_type": "code", + "execution_count": 3, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "array([[13673.68, 27347.36],\n", + " [13967.66, 27935.33],\n", + " [ 7690. , 15380. ]])" + ] + }, + "execution_count": 3, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "params.standard_deduction" + ] + }, + { + "cell_type": "code", + "execution_count": 4, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "[{'year': 2024, 'marital_status': 'single', 'value': 13673.68},\n", + " {'year': 2024, 'marital_status': 'joint', 'value': 27347.36},\n", + " {'year': 2025, 'marital_status': 'single', 'value': 13967.66},\n", + " {'year': 2025, 'marital_status': 'joint', 'value': 27935.33},\n", + " {'year': 2026, 'marital_status': 'single', 'value': 7690.0},\n", + " {'year': 2026, 'marital_status': 'joint', 'value': 15380.0}]" + ] + }, + "execution_count": 4, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "params.from_array(\"standard_deduction\")" + ] + }, + { + "cell_type": "code", + "execution_count": 9, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "OrderedDict([('standard_deduction',\n", + " [{'value': 0.0, 'year': 2026, 'marital_status': 'single'}])])" + ] + }, + "execution_count": 9, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "# query parameters\n", + "params.specification(year=2026, marital_status=\"single\", use_state=False)" + ] + }, + { + "cell_type": "code", + "execution_count": 5, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "array([[13673.68, 27347.36],\n", + " [13967.66, 27935.33],\n", + " [10000. , 15380. ]])" + ] + }, + "execution_count": 5, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "adjustment = {\n", + " \"standard_deduction\": [\n", + " {\"year\": 2026, \"marital_status\": \"single\", \"value\": 10000.0}\n", + " ],\n", + "}\n", + "params.adjust(adjustment)\n", + "params.standard_deduction\n" + ] + }, + { + "cell_type": "code", + "execution_count": 6, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "array([[0., 0.],\n", + " [0., 0.],\n", + " [0., 0.]])" + ] + }, + "execution_count": 6, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "adjustment = {\n", + " \"standard_deduction\": 0,\n", + "}\n", + "params.adjust(adjustment)\n", + "params.standard_deduction\n" + ] + }, + { + "cell_type": "code", + "execution_count": 7, + "metadata": {}, + "outputs": [ + { + "ename": "ValidationError", + "evalue": "{'standard_deduction': ['Not a valid number: higher.']}", + "output_type": "error", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mValidationError\u001b[0m Traceback (most recent call last)", + "\u001b[0;32m\u001b[0m in \u001b[0;36m\u001b[0;34m\u001b[0m\n\u001b[1;32m 1\u001b[0m \u001b[0madjustment\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m\"standard_deduction\"\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m\"higher\"\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 2\u001b[0;31m \u001b[0mparams\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0madjust\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0madjustment\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m", + "\u001b[0;32m~/Documents/ParamTools/paramtools/parameters.py\u001b[0m in \u001b[0;36madjust\u001b[0;34m(self, params_or_path, raise_errors)\u001b[0m\n\u001b[1;32m 134\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 135\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mraise_errors\u001b[0m \u001b[0;32mand\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0m_errors\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 136\u001b[0;31m \u001b[0;32mraise\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mvalidation_error\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m 137\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 138\u001b[0m \u001b[0;31m# Update attrs.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", + "\u001b[0;31mValidationError\u001b[0m: {'standard_deduction': ['Not a valid number: higher.']}" + ] + } + ], + "source": [ + "adjustment[\"standard_deduction\"] = \"higher\"\n", + "params.adjust(adjustment)\n" + ] + }, + { + "cell_type": "code", + "execution_count": 8, + "metadata": {}, + "outputs": [ + { + "ename": "ValidationError", + "evalue": "{'standard_deduction': ['standard_deduction -1.0 must be greater than 0.']}", + "output_type": "error", + "traceback": [ + "\u001b[0;31m---------------------------------------------------------------------------\u001b[0m", + "\u001b[0;31mValidationError\u001b[0m Traceback (most recent call last)", + "\u001b[0;32m\u001b[0m in \u001b[0;36m\u001b[0;34m\u001b[0m\n\u001b[1;32m 1\u001b[0m \u001b[0madjustment\u001b[0m\u001b[0;34m[\u001b[0m\u001b[0;34m\"standard_deduction\"\u001b[0m\u001b[0;34m]\u001b[0m \u001b[0;34m=\u001b[0m \u001b[0;34m-\u001b[0m\u001b[0;36m1\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m----> 2\u001b[0;31m \u001b[0mparams\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0madjust\u001b[0m\u001b[0;34m(\u001b[0m\u001b[0madjustment\u001b[0m\u001b[0;34m)\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m", + "\u001b[0;32m~/Documents/ParamTools/paramtools/parameters.py\u001b[0m in \u001b[0;36madjust\u001b[0;34m(self, params_or_path, raise_errors)\u001b[0m\n\u001b[1;32m 134\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 135\u001b[0m \u001b[0;32mif\u001b[0m \u001b[0mraise_errors\u001b[0m \u001b[0;32mand\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0m_errors\u001b[0m\u001b[0;34m:\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0;32m--> 136\u001b[0;31m \u001b[0;32mraise\u001b[0m \u001b[0mself\u001b[0m\u001b[0;34m.\u001b[0m\u001b[0mvalidation_error\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n\u001b[0m\u001b[1;32m 137\u001b[0m \u001b[0;34m\u001b[0m\u001b[0m\n\u001b[1;32m 138\u001b[0m \u001b[0;31m# Update attrs.\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0;34m\u001b[0m\u001b[0m\n", + "\u001b[0;31mValidationError\u001b[0m: {'standard_deduction': ['standard_deduction -1.0 must be greater than 0.']}" + ] + } + ], + "source": [ + "adjustment[\"standard_deduction\"] = -1\n", + "params.adjust(adjustment)\n" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [], + "source": [ + "defaults = {\n", + " \"schema\": {\n", + " \"labels\": {\n", + " \"year\": {\n", + " \"type\": \"int\",\n", + " \"validators\": {\"range\": {\"min\": 2013, \"max\": 2027}}\n", + " },\n", + " \"marital_status\": {\n", + " \"type\": \"str\",\n", + " \"validators\": {\"choice\": {\"choices\": [\"single\", \"joint\", \"separate\",\n", + " \"headhousehold\", \"widow\"]}}\n", + " },\n", + " },\n", + " \"additional_members\": {\n", + " \"cpi_inflatable\": {\"type\": \"bool\"},\n", + " \"cpi_inflated\": {\"type\": \"bool\"}\n", + " }\n", + " },\n", + " \"personal_exemption\": {\n", + " \"title\": \"Personal Exemption\",\n", + " \"description\": \"A simple version of the personal exemption.\",\n", + " \"notes\": \"\",\n", + " \"cpi_inflatable\": True,\n", + " \"cpi_inflated\": True,\n", + " \"type\": \"float\",\n", + " \"value\": 0,\n", + " \"validators\": {\n", + " \"range\": {\n", + " \"min\": 0,\n", + " }\n", + " }\n", + " },\n", + " \"standard_deduction\": {\n", + " \"title\": \"Standard deduction amount\",\n", + " \"description\": \"Amount filing unit can use as a standard deduction.\",\n", + " \"cpi_inflatable\": True,\n", + " \"cpi_inflated\": True,\n", + " \"type\": \"float\",\n", + " \"value\": [\n", + " {\"year\": 2024, \"marital_status\": \"single\", \"value\": 13673.68},\n", + " {\"year\": 2024, \"marital_status\": \"joint\", \"value\": 27347.36},\n", + " {\"year\": 2024, \"marital_status\": \"separate\", \"value\": 13673.68},\n", + " {\"year\": 2024, \"marital_status\": \"headhousehold\", \"value\": 20510.52},\n", + " {\"year\": 2024, \"marital_status\": \"widow\", \"value\": 27347.36},\n", + " {\"year\": 2025, \"marital_status\": \"single\", \"value\": 13967.66},\n", + " {\"year\": 2025, \"marital_status\": \"joint\", \"value\": 27935.33},\n", + " {\"year\": 2025, \"marital_status\": \"separate\", \"value\": 13967.66},\n", + " {\"year\": 2025, \"marital_status\": \"headhousehold\", \"value\": 20951.49},\n", + " {\"year\": 2025, \"marital_status\": \"widow\", \"value\": 27935.33}],\n", + " \"validators\": {\n", + " \"range\": {\n", + " \"min\": 0,\n", + " \"max\": 9e+99\n", + " }\n", + " }\n", + " },\n", + "}\n", + "\n", + "class Params(Parameters):\n", + " defaults = defaults" + ] + }, + { + "cell_type": "code", + "execution_count": 13, + "metadata": {}, + "outputs": [], + "source": [ + "params = Params()\n", + "\n" + ] + }, + { + "cell_type": "code", + "execution_count": 17, + "metadata": {}, + "outputs": [ + { + "data": { + "text/plain": [ + "[{'value': 0.0}]" + ] + }, + "execution_count": 17, + "metadata": {}, + "output_type": "execute_result" + } + ], + "source": [ + "params.personal_exemption" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [] + } + ], + "metadata": { + "kernelspec": { + "display_name": "Python (paramtools-dev)", + "language": "python", + "name": "paramtools-dev" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.7.1" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/docs/docs/CNAME b/docs/docs/CNAME new file mode 100644 index 0000000..6509f79 --- /dev/null +++ b/docs/docs/CNAME @@ -0,0 +1 @@ +paramtools.org \ No newline at end of file diff --git a/docs/docs/index.md b/docs/docs/index.md new file mode 100644 index 0000000..0f6b44c --- /dev/null +++ b/docs/docs/index.md @@ -0,0 +1,214 @@ +# 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) +# in +# 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) +# in +# 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 \ No newline at end of file diff --git a/docs/docs/parameters.md b/docs/docs/parameters.md new file mode 100644 index 0000000..92fa6cc --- /dev/null +++ b/docs/docs/parameters.md @@ -0,0 +1,156 @@ +# Parameters + +Define your default parameters and let ParamTools handle the rest. + +The ParamTools JSON file is split into two components: a component that defines the structure of your default inputs and a component that defines the variables that are used in your model. The first component is a top level member named `schema`. The second component consists of key-value pairs where the key is the parameter's name and the value is its data. + + +```json +{ + "schema": { + "labels": { + "year": { + "type": "int", + "validators": {"range": {"min": 2013, "max": 2027}} + }, + "marital_status": { + "type": "str", + "validators": {"choice": {"choices": ["single", "joint", "separate", + "headhousehold", "widow"]}} + }, + }, + "additional_members": { + "cpi_inflatable": {"type": "bool"}, + "cpi_inflated": {"type": "bool"} + } + }, + "personal_exemption": { + "title": "Personal Exemption", + "description": "A simple version of the personal exemption.", + "cpi_inflatable": true, + "cpi_inflated": true, + "type": "float", + "value": 0, + "validators": { + "range": { + "min": 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": 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}], + "validators": { + "range": { + "min": 0, + "max": 9e+99 + } + } + }, +} +``` + + + + + +## Parameters Schema + +```json +{ + "schema": { + "labels": { + "year": { + "type": "int", + "validators": {"range": {"min": 2013, "max": 2027}} + } + }, + "additional_members": { + "cpi_inflatable": {"type": "bool"}, + "cpi_inflated": {"type": "bool"} + } + } +} +``` + +- `labels`: Labels are used for defining, accessing, and updating a parameter's values. +- `additional_members`: Additional Members are parameter level members that are specific to your model. For example, "title" is a parameter level member that is required by ParamTools, but "cpi_inflated" is not. Therefore, "cpi_inflated" needs to be defined in `additional_members`. + + + +## Default Parameters + +```json +{ + "standard_deduction": { + "title": "Standard deduction amount", + "description": "Amount filing unit can use as a standard deduction.", + "cpi_inflatable": true, + "cpi_inflated": true, + "type": "float", + "number_dims": 0, + "value": [ + {"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}], + "validators": { + "range": { + "min": 0, + "max": 9e+99 + } + } + } +} +``` + +### Members: + +- `title`: A human readable name for the parameter. + +- `description`: Describe the parameter. +- `notes`: (*optional*) Additional advice or information. +- `type`: Data type of the parameter. Allowed types are `int`, `float`, `bool`, `str` and `date` (YYYY-MM-DD). +- `number_dims`: (*optional, default is 0*) Number of dimensions for the value, as defined by [`np.ndim`][1]. + +- `value`: Value of the parameter and optionally, the corresponding labels. It can be written in two ways: + + - if labels are used: `{"value": [{"value": "my value", **labels}]}` + + - if labels are not used: `{"value": "my value"}` + +- `validators`: Key-value pairs of the validator objects (*the ranges are inclusive*): + +```json +{ + "validators": { + "range": {"min": "min value", "max": "max value"}, + "choice": {"choices": ["list", "of", "allowed", "values"]}, + "date_range": {"min": "2018-01-01", "max": "2018-06-01"} + } +} +``` + + + +[1]: https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.ndim.html diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index b4f72e9..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,36 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build -set SPHINXPROJ=ParamTools - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% - -:end -popd diff --git a/docs/markdown/spec.md b/docs/markdown/spec.md deleted file mode 100644 index db3752d..0000000 --- a/docs/markdown/spec.md +++ /dev/null @@ -1,319 +0,0 @@ -# JSON Spec - -Specification Schema --------------------------------------- - -Define the labels of the parameter space. - -- "schema_name": Name of the schema. -- "labels": Mapping of [Label objects](#label-object). -- "optional_params": Mapping of [Optional objects](#optional-object). -- Example: - ```json - { - "schema_name": "weather", - "labels": { - "city": { - "type": "str", - "validators": {"choice": {"choices": ["Atlanta, GA", - "Washington, D.C."]}} - }, - "month": { - "type": "str", - "validators": {"choice": {"choices": ["January", "February", - "March", "April", "May", - "June", "July", "August", - "September", "October", - "November", "December"]}} - }, - "dayofmonth": { - "type": "int", - "validators": {"range": {"min": 1, "max": 31}} - } - }, - "additional_members": { - "scale": {"type": "str", "number_dims": 0}, - "source": {"type": "str", "number_dims": 0} - } - } - ``` - -Default Specification ---------------------------------------------- - -Define the default values of the project's parameter space. - -- A mapping of [Parameter Objects](#parameter-object). -- Example: - ```json - { - "average_high_temperature": { - "title": "Average High Temperature", - "description": "Average high temperature for each day for a selection of cities", - "notes": "Data has only been collected for Atlanta and Washington and for only the first of the month.", - "scale": "fahrenheit", - "source": "NOAA", - "type": "int", - "number_dims": 0, - "value": [ - {"city": "Washington, D.C.", "month": "January", "dayofmonth": 1, "value": 43}, - {"city": "Washington, D.C.", "month": "February", "dayofmonth": 1, "value": 47}, - {"city": "Washington, D.C.", "month": "March", "dayofmonth": 1, "value": 56}, - {"city": "Washington, D.C.", "month": "April", "dayofmonth": 1, "value": 67}, - {"city": "Washington, D.C.", "month": "May", "dayofmonth": 1, "value": 76}, - {"city": "Washington, D.C.", "month": "June", "dayofmonth": 1, "value": 85}, - {"city": "Washington, D.C.", "month": "July", "dayofmonth": 1, "value": 89}, - {"city": "Washington, D.C.", "month": "August", "dayofmonth": 1, "value": 87}, - {"city": "Washington, D.C.", "month": "September", "dayofmonth": 1, "value": 81}, - {"city": "Washington, D.C.", "month": "October", "dayofmonth": 1, "value": 69}, - {"city": "Washington, D.C.", "month": "November", "dayofmonth": 1, "value": 59}, - {"city": "Washington, D.C.", "month": "December", "dayofmonth": 1, "value": 48}, - {"city": "Atlanta, GA", "month": "January", "dayofmonth": 1, "value": 53}, - {"city": "Atlanta, GA", "month": "February", "dayofmonth": 1, "value": 58}, - {"city": "Atlanta, GA", "month": "March", "dayofmonth": 1, "value": 66}, - {"city": "Atlanta, GA", "month": "April", "dayofmonth": 1, "value": 73}, - {"city": "Atlanta, GA", "month": "May", "dayofmonth": 1, "value": 80}, - {"city": "Atlanta, GA", "month": "June", "dayofmonth": 1, "value": 86}, - {"city": "Atlanta, GA", "month": "July", "dayofmonth": 1, "value": 89}, - {"city": "Atlanta, GA", "month": "August", "dayofmonth": 1, "value": 88}, - {"city": "Atlanta, GA", "month": "September", "dayofmonth": 1, "value": 82}, - {"city": "Atlanta, GA", "month": "October", "dayofmonth": 1, "value": 74}, - {"city": "Atlanta, GA", "month": "November", "dayofmonth": 1, "value": 64}, - {"city": "Atlanta, GA", "month": "December", "dayofmonth": 1, "value": 55} - ], - "validators": {"range": {"min": -130, "max": 135}}, - "out_of_range_minmsg": "", - "out_of_range_maxmsg": "", - "out_of_range_action": "warn" - }, - "average_precipitation": { - "title": "Average Precipitation", - "description": "Average precipitation for a selection of cities by month", - "notes": "Data has only been collected for Atlanta and Washington", - "scale": "inches", - "source": "NOAA", - "type": "float", - "number_dims": 0, - "value": [ - {"city": "Washington, D.C.", "month": "January", "value": 3.1}, - {"city": "Washington, D.C.", "month": "February", "value": 2.6}, - {"city": "Washington, D.C.", "month": "March", "value": 3.5}, - {"city": "Washington, D.C.", "month": "April", "value": 3.3}, - {"city": "Washington, D.C.", "month": "May", "value": 4.3}, - {"city": "Washington, D.C.", "month": "June", "value": 4.3}, - {"city": "Washington, D.C.", "month": "July", "value": 4.6}, - {"city": "Washington, D.C.", "month": "August", "value": 3.8}, - {"city": "Washington, D.C.", "month": "September", "value": 3.9}, - {"city": "Washington, D.C.", "month": "October", "value": 3.7}, - {"city": "Washington, D.C.", "month": "November", "value": 3}, - {"city": "Washington, D.C.", "month": "December", "value": 3.5}, - {"city": "Atlanta, GA", "month": "January", "value": 3.6}, - {"city": "Atlanta, GA", "month": "February", "value": 3.7}, - {"city": "Atlanta, GA", "month": "March", "value": 4.3}, - {"city": "Atlanta, GA", "month": "April", "value": 3.5}, - {"city": "Atlanta, GA", "month": "May", "value": 3.8}, - {"city": "Atlanta, GA", "month": "June", "value": 3.6}, - {"city": "Atlanta, GA", "month": "July", "value": 5}, - {"city": "Atlanta, GA", "month": "August", "value": 3.8}, - {"city": "Atlanta, GA", "month": "September", "value": 3.7}, - {"city": "Atlanta, GA", "month": "October", "value": 2.8}, - {"city": "Atlanta, GA", "month": "November", "value": 3.6}, - {"city": "Atlanta, GA", "month": "December", "value": 4.1} - ], - "validators": {"range": {"min": 0, "max": 50}}, - "out_of_range_minmsg": "str", - "out_of_range_maxmsg": "str", - "out_of_range_action": "stop" - } - } - ``` - - -Adjustment Schema ----------------------------- - -Adjust a given specification. - -- A mapping of parameters and lists of [Value objects](#value-object). -- Example: - ```json - { - "average_temperature": [ - {"city": "Washington, D.C.", - "month": "November", - "dayofmonth": 1, - "value": 60}, - {"city": "Washington, D.C.", - "month": "November", - "dayofmonth": 2, - "value": 63}, - ], - "average_precipitation": [ - {"city": "Washington, D.C.", - "month": "November", - "dayofmonth": 1, - "value": 0.2}, - ] - } - ``` - -JSON Object and Property Definitions ---------------------------------------- - -### Objects - -#### Label object - -- Used for defining the labels of the parameter space. - - "type": Define the datatype of the label values. See the [Type property](#type-property). - - "validators": A mapping of [Validator objects](#validator-object) - - ```json - { - "month": { - "type": "str", - "validators": {"choice": {"choices": ["January", "February", - "March", "April", "May", - "June", "July", "August", - "September", "October", - "November", "December"]}} - }, - } - ``` - -#### Optional object - -- Used for defining optional parameters on the schema. Upstream projects may - find it value to attach additional information to each parameter that is - not essential for ParamTools to perform validation. - - Arguments: - - "type": See [Type property](#type-property). - - "number_dims": See [Number-Labels Property](#number-labels-property). - - Example: - ```json - { - "scale": {"type": "str", "number_dims": 0}, - } - ``` - - Note: [Validator objects](#validator-object) may be defined on this object in the future. - - -#### Parameter object - -- Used for documenting the parameter and defining the default value of a parameter over the entire parameter space and its validation behavior. - - Arguments: - - "param_name": The name of the parameter as it is used in the modeling project. - - "title": "title": A human readable name for the parameter. - - "description": Describes the parameter. - - "notes": Additional advice or information. - - "type": Data type of the parameter. See [Type property](#type-property). - - "number_dims": Number of labels of the parameter. See [Number-Labels property](#number-labels-property) - - "value": A list of (Value objects)[#value-object]. - - "validators": A mapping of (Validator objects)[#validator-object] - - "out_of_range_{min/max/other op}_msg": Extra information to be used in the message(s) that will be displayed if the parameter value is outside of the specified range. Note that this is in the spec but not currently implemented. - - "out_of_range_action": Action to take when specified parameter is outside of the specified range. Options are "stop" or "warn". Note that this is in the spec but only "stop" is currently implemented. - - Example: - ```json - { - "title": "Average Precipitation", - "description": "Average precipitation for a selection of cities by month", - "notes": "Data has only been collected for Atlanta and Washington", - "scale": "inches", - "source": "NOAA", - "type": "float", - "number_dims": 0, - "value": [ - {"city": "Washington, D.C.", "month": "January", "value": 3.1}, - {"city": "Washington, D.C.", "month": "February", "value": 2.6}, - {"city": "Atlanta, GA", "month": "January", "value": 3.6}, - {"city": "Atlanta, GA", "month": "February", "value": 3.7} - ], - "validators": {"range": {"min": 0, "max": 50}}, - "out_of_range_minmsg": "str", - "out_of_range_maxmsg": "str", - "out_of_range_action": "stop" - } - ``` - -#### Validator object - -- Used for validating user input. -- Available validators: - - "range": Define a minimum and maximum value for a given parameter. - - Arguments: - - "min": Minimum allowed value. - - "max": Maximum allowed value. - - Example: - ```json - { - "range": {"min": 0, "max": 10} - } - ``` - - "choice": Define a set of values that this parameter can take. - - Arguments: - - "choice": List of allowed values. - - Example: - ```json - { - "choice": {"choices": ["allowed choice", "another allowed choice"]} - } - ``` - -#### Value object - -- Used to describe the value of a parameter for one or more points in the parameter space. - - "value": The value of the parameter at this point in space. - - Zero or more label properties that define which parts of the parameter space this value should be applied to. These label properties are defined by [Label objects](#label-object) in the [Specification Schema](#specification-schema). - - - Example: - ```json - { - "city": "Washington, D.C.", - "month": "November", - "dayofmonth": 1, - "value": 50 - } - ``` - - -### Properties - -#### Type property - -- "type": The parameter's data type. Supported types are: - - "int": Integer. - - "float": Floating point. - - "bool": Boolean. Either True or False. - - "str"`: String. - - "date": Date. Needs to be of the format "YYYY-MM-DD". - - Example: - ```json - { - "type": "int" - } - ``` - -#### Number-Labels property - -- "number_dims": The number of dimensions for the specified value. A scalar (e.g. 10) has zero labels, a list (e.g. [1, 2]) has one label, a nested list (e.g. [[1, 2], [3, 4]]) has two labels, etc. - - Example: - Note that "value" is a scalar. - ```json - { - "number_dims": 0, - "value": [{"city": "Washington", "state": "D.C.", "value": 10}] - } - ``` - - Note that "value" is an one-labelal list. - ```json - { - "number_dims": 1, - "value": [{"city": "Washington", "state": "D.C.", "value": [38, -77]}] - } - ``` - - -[`numpy.nlabel`]: https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.nlabel.html -[marshmallow]: https://marshmallow.readthedocs.io/en/3.0/ -[Tax-Calculator's]: https://github.com/open-source-economics/Tax-Calculator diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml new file mode 100644 index 0000000..22c533c --- /dev/null +++ b/docs/mkdocs.yml @@ -0,0 +1,5 @@ +site_name: ParamTools Docs +nav: + - Home: index.md + - Parameters: parameters.md +theme: mkdocs \ No newline at end of file diff --git a/docs/source/_static/css/main.css b/docs/source/_static/css/main.css deleted file mode 100644 index 55a564b..0000000 --- a/docs/source/_static/css/main.css +++ /dev/null @@ -1,4 +0,0 @@ - -pre { - width: 40rem; -} \ No newline at end of file diff --git a/docs/source/api_reference.rst b/docs/source/api_reference.rst deleted file mode 100644 index 5e77e21..0000000 --- a/docs/source/api_reference.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. _api: - -************* -API Reference -************* - -.. module:: paramtools - -Parameters -=========== - - -.. autoclass:: paramtools.Parameters - :inherited-members: - -.. _api_fields: - - -Fields -====== - -.. automodule:: paramtools.contrib.fields - :members: - - -Validate -======== - -.. automodule:: paramtools.contrib.validate - :members: diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index cb1089f..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,174 +0,0 @@ -# -*- coding: utf-8 -*- -# -# Configuration file for the Sphinx documentation builder. -# -# This file does only contain a selection of the most common options. For a -# full list see the documentation: -# http://www.sphinx-doc.org/en/master/config - -# -- Path setup -------------------------------------------------------------- - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- Project information ----------------------------------------------------- - -project = "ParamTools" -copyright = "2019, Hank Doupe" -author = "Hank Doupe" - -# The short X.Y version -version = "" -# The full version, including alpha/beta/rc tags -release = "" - - -# -- General configuration --------------------------------------------------- - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = [ - "sphinx.ext.autodoc", - "sphinx.ext.doctest", - "sphinx.ext.viewcode", - "sphinx.ext.autosectionlabel", -] -autosectionlabel_prefix_document = True - -# Add any paths that contain templates here, relative to this directory. -templates_path = ["_templates"] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = ".rst" - -# The master toctree document. -master_doc = "index" - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This pattern also affects html_static_path and html_extra_path . -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = "sphinx" - - -# -- Options for HTML output ------------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = "alabaster" - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -# -# html_theme_options = {} - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ["_static"] - -# Custom sidebar templates, must be a dictionary that maps document names -# to template names. -# -# The default sidebars (for documents that don't match any pattern) are -# defined by theme itself. Builtin themes are using these templates by -# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', -# 'searchbox.html']``. -# -# html_sidebars = {} - - -# -- Options for HTMLHelp output --------------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = "ParamToolsdoc" - - -# -- Options for LaTeX output ------------------------------------------------ - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - ( - master_doc, - "ParamTools.tex", - "ParamTools Documentation", - "Hank Doupe", - "manual", - ) -] - - -# -- Options for manual page output ------------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, "paramtools", "ParamTools Documentation", [author], 1) -] - - -# -- Options for Texinfo output ---------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - ( - master_doc, - "ParamTools", - "ParamTools Documentation", - author, - "ParamTools", - "One line description of project.", - "Miscellaneous", - ) -] - - -# -- Extension configuration ------------------------------------------------- - - -def setup(app): - app.add_stylesheet("css/main.css") diff --git a/docs/source/fields.rst b/docs/source/fields.rst deleted file mode 100644 index 7fb9c45..0000000 --- a/docs/source/fields.rst +++ /dev/null @@ -1,6 +0,0 @@ -Fields -======= - -ParamTools implements the types defined in the :ref:`spec:Type property`. ParamTools uses `NumPy types `__ for Parameter values and regular Python types for all other types. - -Refer to :ref:`api_reference:Fields` for details on each field. diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 58ae026..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,30 +0,0 @@ -.. ParamTools documentation master file, created by - sphinx-quickstart on Wed Feb 13 10:07:04 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -.. include:: readme.rst - -Guide -========= -.. toctree:: - :maxdepth: 2 - - spec - fields - validate - -API Reference -============= - -.. toctree:: - :maxdepth: 2 - - api_reference - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/source/readme.rst b/docs/source/readme.rst deleted file mode 100644 index 3b8e394..0000000 --- a/docs/source/readme.rst +++ /dev/null @@ -1,176 +0,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 `__ -and `default -specification `__ -files: - -.. code:: 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: - -.. code:: 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 `__: - -.. code:: 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 `__ -the default specification: - -.. code:: 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: - -.. code:: 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 - raise saved_exc - File "doc_ex.py", line 33, in - 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: - -.. code:: 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 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'] - # } - -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 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. diff --git a/docs/source/spec.rst b/docs/source/spec.rst deleted file mode 100644 index 1aa4db4..0000000 --- a/docs/source/spec.rst +++ /dev/null @@ -1,479 +0,0 @@ -JSON Spec -========= - -Specification Schema --------------------- - -Define the labels of the parameter space. - -- "schema\_name": Name of the schema. -- "labels": Mapping of `Label objects <#label-object>`__. -- "optional\_params": Mapping of `Optional - objects <#optional-object>`__. -- Example: - - .. code:: json - - { - "schema_name": "policy", - "labels": { - "year": { - "type": "int", - "validators": {"range": {"min": 2013, "max": 2027}} - }, - "marital_status": { - "type": "str", - "validators": {"choice": {"choices": ["single", "joint", "separate", - "headhousehold", "widow"]}} - }, - "idedtype": { - "type": "str", - "validators": {"choice": {"choices": ["medical", "statelocal", - "realestate", "casualty", - "misc", "interest", "charity"]}} - }, - "EIC": { - "type": "str", - "validators": {"choice": {"choices": ["0kids", "1kid", - "2kids", "3+kids"]}} - } - }, - "additional_members": { - "section_1": {"type": "str", "number_dims": 0}, - "section_2": {"type": "str", "number_dims": 0}, - "section_3": {"type": "str", "number_dims": 0}, - "irs_ref": {"type": "str", "number_dims": 0}, - "start_year": {"type": "int", "number_dims": 0}, - "cpi_inflatable": {"type": "bool", "number_dims": 0}, - "cpi_inflated": {"type": "bool", "number_dims": 0}, - "compatible_data": {"type": "compatible_data", "number_dims": null} - } - } - - -Default Specification ---------------------- - -Define the default values of the project"s parameter space. - -- A mapping of `Parameter Objects <#parameter-object>`__. -- Example: - - .. code:: json - - { - "standard_deduction": { - "title": "Standard deduction amount", - "description": "Amount filing unit can use as a standard deduction.", - "section_1": "Standard Deduction", - "section_2": "Standard Deduction Amount", - "irs_ref": "Form 1040, line 8, instructions. ", - "notes": "", - "start_year": 2024, - "cpi_inflatable": true, - "cpi_inflated": true, - "type": "float", - "number_dims": 0, - "value": [ - {"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}], - "out_of_range_minmsg": "", - "out_of_range_maxmsg": "", - "out_of_range_action": "stop", - "validators": { - "range": { - "min": 0, - "max": 9e+99 - } - } - }, - "social_security_tax_rate": { - "description": "Social Security FICA rate, including both employer and employee.", - "section_1": "Payroll Taxes", - "section_2": "Social Security FICA", - "irs_ref": "", - "notes": "", - "start_year": 2026, - "cpi_inflatable": false, - "cpi_inflated": false, - "value": [ - {"year": 2024, "value": 0.124}, - {"year": 2025, "value": 0.124}, - {"year": 2026, "value": 0.124} - ], - "out_of_range_minmsg": "", - "out_of_range_maxmsg": "", - "out_of_range_action": "stop", - "number_dims": 0, - "title": "Social Security payroll tax rate", - "type": "float", - "validators": { - "range": { - "min": 0, - "max": 1 - } - } - }, - "ii_bracket_1": { - "title": "Personal income (regular/non-AMT/non-pass-through) tax bracket (upper threshold) 1", - "description": "Taxable income below this threshold is taxed at tax rate 1.", - "section_1": "Personal Income", - "section_2": "Regular: Non-AMT, Non-Pass-Through", - "irs_ref": "Form 1040, line 44, instruction (Schedule XYZ).", - "notes": "", - "start_year": 2013, - "cpi_inflatable": true, - "cpi_inflated": true, - "number_dims": 0, - "type": "float", - "value": [ - {"year": 2024, "marital_status": "single", "value": 10853.48}, - {"year": 2024, "marital_status": "joint", "value": 21706.97}, - {"year": 2024, "marital_status": "separate", "value": 10853.48}, - {"year": 2024, "marital_status": "headhousehold", "value": 15496.84}, - {"year": 2024, "marital_status": "widow", "value": 21706.97}, - {"year": 2025, "marital_status": "single", "value": 11086.83}, - {"year": 2025, "marital_status": "joint", "value": 22173.66}, - {"year": 2025, "marital_status": "separate", "value": 11086.83}, - {"year": 2025, "marital_status": "headhousehold", "value": 15830.02}, - {"year": 2025, "marital_status": "widow", "value": 22173.66}, - {"year": 2026, "marital_status": "single", "value": 11293.0}, - {"year": 2026, "marital_status": "joint", "value": 22585.0}, - {"year": 2026, "marital_status": "separate", "value": 11293.0}, - {"year": 2026, "marital_status": "headhousehold", "value": 16167.0}, - {"year": 2026, "marital_status": "widow", "value": 22585.0}], - "out_of_range_minmsg": "", - "out_of_range_maxmsg": "for _II_brk2", - "out_of_range_action": "stop", - "validators": { - "range": { - "min": 0, - "max": "ii_bracket_2" - } - } - }, - "ii_bracket_2": { - "title": "Personal income (regular/non-AMT/non-pass-through) tax bracket (upper threshold) 2", - "description": "Income below this threshold and above tax bracket 1 is taxed at tax rate 2.", - "section_1": "Personal Income", - "section_2": "Regular: Non-AMT, Non-Pass-Through", - "irs_ref": "Form 1040, line 11, instruction (Schedule XYZ).", - "notes": "", - "start_year": 2013, - "cpi_inflatable": true, - "cpi_inflated": true, - "number_dims": 0, - "type": "float", - "value": [ - {"year": 2024, "marital_status": "single", "value": 44097.61}, - {"year": 2024, "marital_status": "joint", "value": 88195.23}, - {"year": 2024, "marital_status": "separate", "value": 44097.61}, - {"year": 2024, "marital_status": "headhousehold", "value": 59024.71}, - {"year": 2024, "marital_status": "widow", "value": 88195.23}, - {"year": 2025, "marital_status": "single", "value": 45045.71}, - {"year": 2025, "marital_status": "joint", "value": 90091.43}, - {"year": 2025, "marital_status": "separate", "value": 45045.71}, - {"year": 2025, "marital_status": "headhousehold", "value": 60293.74}, - {"year": 2025, "marital_status": "widow", "value": 90091.43}, - {"year": 2026, "marital_status": "single", "value": 45957.0}, - {"year": 2026, "marital_status": "joint", "value": 91915.0}, - {"year": 2026, "marital_status": "separate", "value": 45957.0}, - {"year": 2026, "marital_status": "headhousehold", "value": 61519.0}, - {"year": 2026, "marital_status": "widow", "value": 91915.0}], - "out_of_range_minmsg": "", - "out_of_range_maxmsg": "", - "out_of_range_action": "stop", - "validators": { - "range": { - "min": "ii_bracket_1", - "max": 9e+99 - } - } - } - } - - -Adjustment Schema ------------------ - -Adjust a given specification. - -- A mapping of parameters and lists of `Value - objects <#value-object>`__. -- Example: - - .. code:: json - - { - "standard_deduction": [ - {"year": 2026, "marital_status": "single", "value": 10000.0} - ], - "social_security_tax_rate": [ - {"year": 2026, "value": 0.14} - ] - } - -JSON Object and Property Definitions ------------------------------------- - -Objects -~~~~~~~ - -Label object -^^^^^^^^^^^^^^^^ - -- Used for defining the labels of the parameter space. - - - "type": Define the datatype of the label values. See the `Type - property <#type-property>`__. - - "validators": A mapping of `Validator - objects <#validator-object>`__ - - .. code:: json - - { - "marital_status": { - "type": "str", - "validators": {"choice": {"choices": ["single", "joint", "separate", - "headhousehold", "widow"]}} - } - } - -Optional object -^^^^^^^^^^^^^^^ - -- Used for defining optional parameters on the schema. Upstream - projects may find it value to attach additional information to each - parameter that is not essential for ParamTools to perform validation. - - - Arguments: - - - "type": See `Type property <#type-property>`__. - - "number\_labels": See `Number-Labels - Property <#number-labels-property>`__. - - - Example: - - .. code:: json - - { - "start_year": {"type": "int", "number_dims": 0} - } - - - Note: `Validator objects <#validator-object>`__ may be defined on - this object in the future. - -Parameter object -^^^^^^^^^^^^^^^^ - -- Used for documenting the parameter and defining the default value of - a parameter over the entire parameter space and its validation - behavior. - - - Arguments: - - - "param\_name": The name of the parameter as it is used in the - modeling project. - - "title": "title": A human readable name for the parameter. - - "description": Describes the parameter. - - "notes": Additional advice or information. - - "type": Data type of the parameter. See `Type - property <#type-property>`__. - - "number\_labels": Number of labels of the parameter. See - `Number-Labels property <#number-labels-property>`__ - - "value": A list of `Value objects <#value-object>`__. - - "validators": A mapping of `Validator - objects <#validator-object>`__. - - "out\_of\_range\_{min/max/other op}\_msg": Extra information to - be used in the message(s) that will be displayed if the - parameter value is outside of the specified range. Note that - this is in the spec but not currently implemented. - - "out\_of\_range\_action": Action to take when specified - parameter is outside of the specified range. Options are "stop" - or "warn". Note that this is in the spec but only "stop" is - currently implemented. - - - Example: - - .. code:: json - - { - "standard_deduction": { - "title": "Standard deduction amount", - "description": "Amount filing unit can use as a standard deduction.", - "section_1": "Standard Deduction", - "section_2": "Standard Deduction Amount", - "irs_ref": "Form 1040, line 8, instructions. ", - "notes": "", - "start_year": 2013, - "cpi_inflatable": true, - "cpi_inflated": true, - "type": "float", - "number_dims": 0, - "value": [ - {"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}], - "out_of_range_minmsg": "", - "out_of_range_maxmsg": "", - "out_of_range_action": "stop", - "compatible_data": { - "puf": true, - "cps": true - }, - "validators": { - "range": { - "min": 0, - "max": 9e+99 - } - } - } - } - -Validator object -^^^^^^^^^^^^^^^^ - -- Used for validating user input. -- Available validators: - - - "range": Define a minimum and maximum value for a parameter. - - - Arguments: - - - "min": Minimum allowed value. - - "max": Maximum allowed value. - - - Example: - - .. code:: json - - { - "range": {"min": 0, "max": 10} - } - - - "choice": Define a set of values that this parameter can take. - - - Arguments: - - - "choice": List of allowed values. - - - Example: - - .. code:: json - - { - "choice": {"choices": ["allowed choice", "another allowed choice"]} - } - - - "date_range": Define a minimum and maximum value for a date type parameter. - - - Arguments: - - - "min": Minimum allowed value. - - "max": Maximum allowed value. - - - Example: - - .. code:: json - - { - "range": {"min": "2019-01-01", "max": "2019-06-01"} - } - - -Value object -^^^^^^^^^^^^ - -- Used to describe the value of a parameter for one or more points in - the parameter space. - - - "value": The value of the parameter at this point in space. - - Zero or more label properties that define which parts of the - parameter space this value should be applied to. These label - properties are defined by `Label - objects <#label-object>`__ in the `Specification - Schema <#specification-schema>`__. - - - Example: - - .. code:: json - - { - "year": 2026, - "marital_status": "single", - "value": 7690.0 - } - - -Properties -~~~~~~~~~~ - -Type property -^^^^^^^^^^^^^ - -- "type": The parameter"s data type. Supported types are: - - - "int": Integer. - - "float": Floating point. - - "bool": Boolean. Either True or False. - - "str": String. - - "date": Date. Needs to be of the format "YYYY-MM-DD". - - Example: - - .. code:: json - - { - "type": "int" - } - - -Number-Labels property -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -- "number\_labels": The number of dimensions for the specified value. A - scalar (e.g. 10) has zero labels, a list (e.g. [1, 2]) has one - label, a nested list (e.g. [[1, 2], [3, 4]]) has two labels, - etc. - - - Example: Note that "value" is a scalar. - - .. code:: json - - { - "number_dims": 0, - "value": [{"year": 2026, "marital_status": "single", "value": 7690.0}] - } - - Note that "value" is an one-labelal list. - - .. code:: json - - { - "number_dims": 1, - "value": [{"position": "shortstop", "value": ["Derek Jeter", "Andrelton Simmons"]}] - } diff --git a/docs/source/validate.rst b/docs/source/validate.rst deleted file mode 100644 index 03c0b98..0000000 --- a/docs/source/validate.rst +++ /dev/null @@ -1,4 +0,0 @@ -Validate -========= - -Refer to :ref:`api_reference:Validate` for details on each field. diff --git a/paramtools/utils.py b/paramtools/utils.py index fb46bdd..d2a9731 100644 --- a/paramtools/utils.py +++ b/paramtools/utils.py @@ -18,15 +18,12 @@ def read_json(path): def get_example_paths(name): - assert name in ("taxparams", "weather", "taxparams-demo", "behresp") + assert name in ("taxparams-demo",) current_path = os.path.abspath(os.path.dirname(__file__)) - schema_def_path = os.path.join( - current_path, f"examples/{name}/schema.json" - ) default_spec_path = os.path.join( current_path, f"examples/{name}/defaults.json" ) - return (schema_def_path, default_spec_path) + return default_spec_path class LeafGetter: