Variables#

The policyengine_core.variables module contains the definition of Variable, which can have a value for each entity instance in a simulation, for each period in a simulation, dependent on the parameters in that period, as well as other entity instances.

Variable#

class policyengine_core.variables.variable.Variable(baseline_variable=None)#

Bases: object

A variable of the legislation.

check_defined_for_variable(defined_for_variable: Variable) → None#

Reject a defined_for variable that cannot be compared with zero.

calculate keeps this variable’s formula result where the defined_for variable is greater than zero, and uses the default value elsewhere. That needs a bool, int or float variable: an Enum array allows only == and !=, and str and date arrays cannot be compared with a number, so the comparison raised a TypeError in the middle of a calculation. For an Enum condition, define a bool variable that compares it with a member and name that variable instead.

check_uprating_value_type()#

Reject uprating on a variable whose values cannot be multiplied.

Uprating multiplies the latest earlier input by a ratio of index values. Enum arrays allow only == and !=, and str and date arrays cannot be multiplied by a float, so uprating on such a variable raised a TypeError the first time a later period was uprated. The check covers an uprating inherited from a baseline variable too, since the inherited one is what calculate uses.

It runs when the variable is defined and when uprating is assigned. A class that declares uprating itself (even as None) replaces the property that checks assignments, so calculate runs it again before it uprates.

clone()#

Return a copy that preserves the variable’s merged state.

Uses empty_clone + a __dict__ copy (the TaxBenefitSystem.clone pattern) rather than re-running __init__, so a variable registered via a reform’s update_variable keeps the attributes it inherited from its baseline (value_type, entity, formulas, baseline_variable, …). formulas and metadata are copied so mutating them on the clone does not affect the original; other containers (adds/subtracts) are shared, as they were before.

get_explicit_computation_modes()#

Computation modes the class declares itself.

Excludes attributes inherited from a baseline variable when a reform updates it: a reform may, for example, redeclare a formula variable with adds, and the inherited baseline formulas keep their runtime precedence rather than constituting a mixed-mode authoring error.

get_formula(period=None)#

Returns the formula used to compute the variable at the given period.

If no period is given and the variable has several formula, return the oldest formula.

Returns:

Formula used to compute the variable

classmethod get_introspection_data(tax_benefit_system)#

Get instrospection data about the code of the variable.

Returns:

(comments, source file path, source code, start line number)

Return type:

tuple

is_input_variable()#

Returns True if the variable is an input variable.

parse_formula_name(attribute_name)#

Returns the starting date of a formula based on its name.

Valid dated name formats are : ‘formula’, ‘formula_YYYY’, ‘formula_YYYY_MM’ and ‘formula_YYYY_MM_DD’ where YYYY, MM and DD are a year, month and day.

By convention, the starting date of:

  • formula is 0001-01-01 (minimal date in Python)

  • formula_YYYY is YYYY-01-01

  • formula_YYYY_MM is YYYY-MM-01