Writing parameters#

Parameters are values that can change over time (but are the same for an entire country package, i.e. they can’t be different for different entities). The parameters/ folder of a country package contains the parameter tree, a tree of parameter nodes (objects that hold parameters as children) containing parameters or subnodes. A parameter node can be represented either as a folder, or a YAML file. Parameters are stored in parameter files. For example, a parameter tree might have the following structure in a country repo:

parameters/
├── child_benefit/
│   ├── basic.yaml
│   ├── child.yaml
|   ├── family.yaml
│   └── index.yaml # Contains metadata for the child_benefit node.
├── income_tax/
│   ├── basic.yaml
│   ├── personal.yaml
│   └── thresholds.yaml
├── national_insurance/
│   ├── basic.yaml
│   ├── employee.yaml
│   └── thresholds.yaml
└── universal_credit/
    ├── basic.yaml
    ├── child.yaml
    └── family.yaml

Parameter values#

Parameters are defined as a function of time, and are evaluated at a given instant. To achieve this, parameters must be defined with a value history: a set of time-dated values (where the value at a given instant is the last-set value before that instant). For example, the child_benefit.basic.amount parameter might have the following value history:

values:
   2019-04-01: 20.00
   2019-04-02: 21.00
   2019-04-03: 22.00
   2019-04-04: 23.00
   2019-04-05: 24.00

Metadata#

Each parameter (or parameter node) can also set metadata: data that describes the parameter, such as its name, description, and units. While the metadata for each parameter and node is freeform, using the schemas defined in policyengine_core.data_structures will ensure consistency between country packages, and better maintainability.

Here’s an example metadata specification for the child_benefit.basic.amount parameter:

description: The UK provides this Child Benefit per child.

metadata:
    label: Child Benefit
    period: year
    unit: currency-GBP
    reference: 
        - label: GOV.UK | Child Benefit
          href: https://www.gov.uk/government/publications/child-benefit-rates-and-thresholds/child-benefit-rates-and-thresholds

Metadata for parameters#

class policyengine_core.data_structures.ParameterMetadata[source]#

A single legislative value that can change over time.

description: str#: A longer description of the parameter.

documentation: str#: Any relevant information about the parameter’s implementation (not its legislative meaning- use the description for that field).

label: str#: The display text to use for the parameter. Should be short and less than a full sentence.

name: str#: The name identifying this parameter. Should be snake-case and Python-safe.

reference: List[Reference]#: A list of references to legislation or other documents that define this parameter.

unit: str#: The real-world meaning of a particular value.

uprating: Union[UpratingIndex, UpratingSchema]#

The schema for uprating this parameter.

The process for uprating parameter \(X\) based on parameter \(Y\) is as follows:

Look at \(X\) and \(Y\) at the same time, and move forward in history.
If \(Y\) increases by \(z\)%, then increase \(X\) by \(z\)%.

Metadata for parameter nodes#

class policyengine_core.data_structures.ParameterNodeMetadata[source]#

A collection of related parameters.

breakdown: List[Union[VariableBreakdown, DynamicBreakdown]]#

The sets defining the children, grandchildren and further descendants of this node.

For example:

metadata:
    breakdown:
        - region # If `region` is an Enum-type variable with possible values `[ENGLAND, WALES]` then these children will be added.
        - range(1, 7) # This code is `eval`uated to produce the list `[1, 2, 3, 4, 5, 6]` which are then added as grandchildren.
        - [True, False] # This list is added as great-grandchildren (using the same `eval` method as above).

label: str#: The display text to use for the parameter node and its children (unless overridden). Should be short and less than a full sentence.

name: str#: The name identifying this parameter node and its children (unless overridden). Should be snake-case and Python-safe.

propagate_metadata_to_children: bool#: Whether to propagate metadata to children of this node. This excludes breakdown.

reference: List[Reference]#: A list of references that apply to all descendants of this node.

Specifying references#

class policyengine_core.data_structures.Reference[source]#

A reference to a piece of legislation or other document.

href: str#: The URL to link to.

label: str#: The display text to use for the reference.

type: str = 'general'#: The type of reference.

Units#

class policyengine_core.data_structures.Unit[source]#

The real-world meaning of a particular value.

EUR = 'currency-EUR'#: Euros.

GBP = 'currency-GBP'#: British pounds sterling.

PERCENT = '/1'#: A percentage.

USD = 'currency-USD'#: United States dollars.

Other specifications#

class policyengine_core.data_structures.parameter_metadata.SelfUprating[source]#

Bases: UpratingIndex

A special value (“self”) that indicates that the parameter node should be uprated based on the fixed rate increase between two points in its history.

class policyengine_core.data_structures.parameter_metadata.UpratingIndex[source]#

Bases: str

The name of a parameter whose values are used to uprate a parameter node.

class policyengine_core.data_structures.parameter_metadata.UpratingRoundingConfig[source]#

Bases: dict

interval: float#: The interval to round to.

type: str#: Either ‘nearest’, ‘upwards’ or ‘downwards’.

class policyengine_core.data_structures.parameter_metadata.UpratingSchema[source]#

Bases: dict

A schema for uprating a parameter node.

parameter: UpratingIndex#: The name of the parameter whose values are used to uprate the parameter node.

start_instant: int#: The instant to add uprated values after.

type: UpratingRoundingConfig#: The rounding configuration to use when uprating.

class policyengine_core.data_structures.parameter_node_metadata.DynamicBreakdown[source]#

Bases: str

A Python expression that evaluates to a list of child nodes in a parameter node.

class policyengine_core.data_structures.parameter_node_metadata.VariableBreakdown[source]#

Bases: str

The name of a variable with Enum type, whose possible values form the child nodes in a parameter node.