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#: A single legislative value that can change over time.

Metadata for parameter nodes#

class policyengine_core.data_structures.ParameterNodeMetadata#: A collection of related parameters.

Specifying references#

class policyengine_core.data_structures.Reference#: A reference to a piece of legislation or other document.

Units#

class policyengine_core.data_structures.Unit#: The real-world meaning of a particular value.

Other specifications#

class policyengine_core.data_structures.parameter_metadata.SelfUprating#

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#

Bases: str

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

class policyengine_core.data_structures.parameter_metadata.UpratingRoundingConfig#: Bases: dict

class policyengine_core.data_structures.parameter_metadata.UpratingSchema#

Bases: dict

A schema for uprating a parameter node.

class policyengine_core.data_structures.parameter_node_metadata.DynamicBreakdown#

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#

Bases: str

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