Holders

policyengine_core.holders contains the definition of Holder, which is a class whose instances represent variable values in a specific time period.

Holder

class policyengine_core.holders.holder.Holder(variable: Variable, population: Population)

Bases: object

A holder keeps tracks of a variable values after they have been calculated, or set as an input.

clone(population: Population) → Holder

Copy the holder just enough to be able to run a new simulation without modifying the original simulation.

create_disk_storage(directory: Optional[str] = None, preserve: bool = False) → OnDiskStorage

default_array() → Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]

Return a new array of the appropriate length for the entity, filled with the variable default values.

delete_arrays(period: Optional[Period] = None, branch_name: str = 'default') → None

If period is None, remove all known values of the variable.

If period is not None, only remove all values for any period included in period (e.g. if period is “2017”, values for “2017-01”, “2017-07”, etc. would be removed)

get_array(period: Period, branch_name: str = 'default') → Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]]

Get the value of the variable for the given period.

If the value is not known, return None.

get_known_branch_periods() → List[Tuple[str, Period]]

Get the list of periods the variable value is known for.

get_known_periods() → List[Period]

Get the list of periods the variable value is known for.

get_memory_usage() → dict

Get data about the virtual memory usage of the holder.

Returns:

Memory usage data

Return type:

dict

Example:

>>> holder.get_memory_usage()
>>> {
>>>    'nb_arrays': 12,  # The holder contains the variable values for 12 different periods
>>>    'nb_cells_by_array': 100, # There are 100 entities (e.g. persons) in our simulation
>>>    'cell_size': 8,  # Each value takes 8B of memory
>>>    'dtype': dtype('float64')  # Each value is a float 64
>>>    'total_nb_bytes': 10400  # The holder uses 10.4kB of virtual memory
>>>    'nb_requests': 24  # The variable has been computed 24 times
>>>    'nb_requests_by_array': 2  # Each array stored has been on average requested twice
>>>    }

put_in_cache(value: Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], period: Period, branch_name: str = 'default') → None

set_input(period: Period, array: Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], branch_name: str = 'default') → None

Set a variable’s value (array) for a given period (period)

Parameters:

• array – the input value for the variable

• period – the period at which the value is setted

Example :

>>> holder.set_input([12, 14], '2018-04')
>>> holder.get_array('2018-04')
>>> [12, 14]

If a set_input property has been set for the variable, this method may accept inputs for periods not matching the definition_period of the variable. To read more about this, check the documentation.

set_input_dispatch_by_period

policyengine_core.holders.helpers.set_input_dispatch_by_period(holder: Holder, period: Period, array: Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]])

This function can be declared as a set_input attribute of a variable.

In this case, the variable will accept inputs on larger periods that its definition period, and the value for the larger period will be applied to all its subperiods.

To read more about set_input attributes, check the documentation.

set_input_divide_by_period

policyengine_core.holders.helpers.set_input_divide_by_period(holder: Holder, period: Period, array: Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]])

This function can be declared as a set_input attribute of a variable.

In this case, the variable will accept inputs on larger periods that its definition period, and the value for the larger period will be divided between its subperiods.

To read more about set_input attributes, check the documentation.