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.

{
    "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"}
        },
        "operators": {
            "array_first": true,
            "label_to_extend": "year",
            "uses_extend_func": true
        }
    },
    "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,
                "level": "warn",
            }
        }
    },
}

Parameters Schema

{
    "schema": {
        "labels": {
            "year": {
                "type": "int",
                "validators": {"range": {"min": 2013, "max": 2027}}
            }
        },
        "additional_members": {
            "cpi_inflatable": {"type": "bool"},
            "cpi_inflated": {"type": "bool"}
        }
    },
    "operators": {
        "array_first": true,
        "label_to_extend": true,
        "uses_extend_func": true
    }
}

• 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.

• operators: Operators affect how the data is read into and handled by the Parameters class:

  • array_first: If value is true, parameters’ values will be accessed as arrays by default.

  • label_to_extend: The name of the label along which the missing values of the parameters will be extended. For more information, check out the extend docs.

  • uses_extend_func: If value is true, special logic is applied to the values of the parameters as they are extended. For more information, check out the indexing docs.

Default Parameters

{
	"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.

• 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):

  • level: All validators take a level argument which is either “error” or “warn”. By default it is set to “error”.

  • when:

    • is is set to equal_to by default but can also be greater_than or less_than.

      • e.g: "is": {"greater_than": 0}

    • If the sub-validators refer to the value of another parameter, then the other parameter must have number_dims equal to 0, i.e. be a scalar value and not an array value.

{
    "validators": {
        "range": {"min": "min value", "max": "max value", "level": "warn"},
        "choice": {"choices": ["list", "of", "allowed", "values"]},
        "date_range": {"min": "2018-01-01", "max": "2018-06-01"},
        "when": {
            "param": "other parameter",
            "is": "equal_value",
            "then": {
                "range": {
                    "min": "min value if other parameter is 'equal_value'"
                }
            },
            "otherwise": {
                "range": {
                    "min": "min value if other parameter is not 'equal_value'"
                }
            }
        }
    }
}