Parameters#

The policyengine_core.parameters module contains the classes that define how parameters function. This mainly revolves around the ‘at-instant’ pattern: parameters are defined as a function of time, and are evaluated at a given instant.

Parameter#

class policyengine_core.parameters.parameter.Parameter(name: str, data: dict, file_path: Optional[str] = None)#

Bases: AtInstantLike

A parameter of the legislation.

Parameters can change over time.

values_list#

List of the values, in reverse chronological order.

Parameters:

  • name – Name of the parameter, e.g. “taxes.some_tax.some_param”.

  • data – Data loaded from a YAML file.

  • file_path – File the parameter was loaded from.

Instantiate a parameter without metadata:

>>>  Parameter('rate', data = {
        "2015-01-01": 550,
        "2016-01-01": 600
        })

Instantiate a parameter with metadata:

>>>  Parameter('rate', data = {
        'description': 'Income tax rate applied on salaries',
        'values': {
            "2015-01-01": {'value': 550, 'metadata': {'reference': 'http://taxes.gov/income_tax/2015'}},
            "2016-01-01": {'value': 600, 'metadata': {'reference': 'http://taxes.gov/income_tax/2016'}}
            }
        })
clone()#
get_descendants()#
mark_as_modified()#
relative_change(start_instant, end_instant)#
update(value=None, period=None, start=None, stop=None, remove_after: bool = False)#

Change the value for a given period.

Parameters:

  • period – Period where the value is modified. If set, start and stop should be None.

  • start – Start of the period. Instance of policyengine_core.Instant. If set, period should be None.

  • stop – Stop of the period. Instance of policyengine_core.Instant. If set, period should be None.

  • value – New value. If None, the parameter is removed from the legislation parameters for the given period.

  • remove_after – If True, the value given here becomes the last value in the parameter history (uprating will apply on the next interval if only start given, or after the period if period given).

ParameterNode#

class policyengine_core.parameters.parameter_node.ParameterNode(name: str = '', directory_path: str = None, data: dict = None, file_path: str = None)#

Bases: AtInstantLike

A node in the legislation parameter tree.

add_child(name: str, child: Union[ParameterNode, Parameter])#

Add a new child to the node.

Parameters:

  • name – Name of the child that must be used to access that child. Should not contain anything that could interfere with the operator . (dot).

  • child – The new child, an instance of ParameterScale or Parameter or ParameterNode.

attach_to_parent(parent: ParameterNode)#
clear_parent_cache()#
clone() → ParameterNode#
get_child(path: str) → ParameterNode#
get_descendants() → Iterable[Union[ParameterNode, Parameter]]#

Return a generator containing all the parameters and nodes recursively contained in this ParameterNode

mark_as_modified()#
merge(other: ParameterNode) → None#

Merges another ParameterNode into the current node.

In case of child name conflict, the other node child will replace the current node child.

parent: ParameterNode = None#

ParameterAtInstant#

class policyengine_core.parameters.parameter_at_instant.ParameterAtInstant(name: str, instant_str: str, data: dict = None, file_path: str = None, metadata: dict = None)#

Bases: object

A value of a parameter at a given instant.

clone() → ParameterAtInstant#
validate(data: dict) → None#

ParameterNodeAtInstant#

class policyengine_core.parameters.parameter_node_at_instant.ParameterNodeAtInstant(name: str, node: ParameterNode, instant_str: str)#

Bases: object

Parameter node of the legislation, at a given instant.

add_child(child_name: str, child_at_instant: ParameterNodeAtInstant)#

ParameterScale#

class policyengine_core.parameters.parameter_scale.ParameterScale(name: str, data: dict, file_path: str)#

Bases: AtInstantLike

A parameter scale (for instance a marginal scale).

clear_parent_cache()#
clone() → ParameterScale#
get_descendants() → Iterable#
mark_as_modified()#
propagate_units() → None#
propagate_uprating() → None#

ParameterScaleBracket#

class policyengine_core.parameters.parameter_scale_bracket.ParameterScaleBracket(name: str = '', directory_path: str = None, data: dict = None, file_path: str = None)[source]#

Bases: ParameterNode

A parameter scale bracket.

static allowed_unit_keys()[source]#
get_descendants() → Iterable[Parameter][source]#

Return a generator containing all the parameters and nodes recursively contained in this ParameterNode

propagate_uprating(uprating: str, threshold: bool = False, threshold_uprating: Optional[str] = None) → None[source]#

Route uprating metadata down onto the bracket’s component leaves.

Uprating is applied by reading each leaf Parameter’s metadata["uprating"]. Scale parameters carry their uprating intent on the scale, the bracket, or the individual component, so this method resolves all of those into per-leaf uprating entries. See issue #390.

Resolution order for a component (highest priority first):

  1. the component leaf’s own metadata.uprating (per-leaf form, e.g. brackets[i].threshold.metadata.uprating);

  2. a bracket-level per-component override (brackets[i].metadata.threshold.uprating);

  3. a bracket-level default: brackets[i].metadata.uprating for the value side, and for the threshold either brackets[i].metadata.threshold_uprating or the bare bracket uprating when brackets[i].metadata.uprate_thresholds is set;

  4. the scale-level default passed in by ParameterScale (uprating for the value side, gated by uprate_thresholds for the threshold; threshold_uprating for the threshold).

Parameters:

  • uprating – Scale-level default uprating for the value side (may be None).

  • threshold – Whether the scale-level uprating should also apply to thresholds (the scale’s uprate_thresholds flag).

  • threshold_uprating – Scale-level uprating dedicated to thresholds (may be None).

AtInstantLike#

class policyengine_core.parameters.at_instant_like.AtInstantLike[source]#

Bases: ABC

Base class for various types of parameters implementing the at instant protocol.

get_at_instant(instant: Instant) → Any[source]#

VectorialParameterNodeAtInstant#

class policyengine_core.parameters.vectorial_parameter_node_at_instant.VectorialParameterNodeAtInstant(name: str, vector: ArrayLike, instant_str: str)#

Bases: object

Parameter node of the legislation at a given instant which has been vectorized. Vectorized parameters allow requests such as parameters.housing_benefit[zipcode], where zipcode is a vector

static build_from_node(node: ParameterNode) → VectorialParameterNodeAtInstant#
static check_node_vectorisable(node: ParameterNode) → None#

Check that a node can be casted to a vectorial node, in order to be able to use fancy indexing.

contains_nan#

policyengine_core.parameters.helpers.contains_nan(vector)[source]#

load_parameter_file#

policyengine_core.parameters.helpers.load_parameter_file(file_path, name='')[source]#

Load parameters from a YAML file (or a directory containing YAML files).

Returns:

An instance of ParameterNode or ParameterScale or Parameter.