Holders

class openfisca_core.holders.Holder(variable, population)

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

clone(population)

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

Return type:

Holder

default_array()

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

delete_arrays(period=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)

Return type:

None

get_array(period)

Get the value of the variable for the given period.

If the value is not known, return None.

get_known_periods()

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

get_memory_usage()

Get data about the virtual memory usage of the Holder.

Returns:

Memory usage data.

Return type:

MemoryUsage

Examples

>>> from pprint import pprint

>>> from openfisca_core import (
...     entities,
...     populations,
...     simulations,
...     taxbenefitsystems,
...     variables,
... )

>>> entity = entities.Entity("", "", "", "")

>>> class MyVariable(variables.Variable):
...     definition_period = periods.DateUnit.YEAR
...     entity = entity
...     value_type = int

>>> population = populations.Population(entity)
>>> variable = MyVariable()
>>> holder = Holder(variable, population)

>>> tbs = taxbenefitsystems.TaxBenefitSystem([entity])
>>> entities = {entity.key: population}
>>> simulation = simulations.Simulation(tbs, entities)
>>> holder.simulation = simulation

>>> pprint(holder.get_memory_usage(), indent=3)
{  'cell_size': nan,
   'dtype': <class 'numpy.int32'>,
   'nb_arrays': 0,
   'nb_cells_by_array': 0,
   'total_nb_bytes': 0...

set_input(period, array)

Set a Variable’s array of values of a given Period.

Parameters:

• period (Period) – The period at which the value is set.

• array (ndarray | Sequence[Any]) – The input value for the variable.

Returns:

The set input array.

Return type:

ndarray | None

Note

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.

Examples

>>> from openfisca_core import entities, populations, variables

>>> entity = entities.Entity("", "", "", "")

>>> class MyVariable(variables.Variable):
...     definition_period = periods.DateUnit.YEAR
...     entity = entity
...     value_type = float

>>> variable = MyVariable()

>>> population = populations.Population(entity)
>>> population.count = 2

>>> holder = Holder(variable, population)
>>> holder.set_input("2018", numpy.array([12.5, 14]))
>>> holder.get_array("2018")
array([12.5, 14. ], dtype=float32)

>>> holder.set_input("2018", [12.5, 14])
>>> holder.get_array("2018")
array([12.5, 14. ], dtype=float32)

openfisca_core.holders.helpers.set_input_dispatch_by_period(holder, period, array)

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.

Return type:

None

openfisca_core.holders.helpers.set_input_divide_by_period(holder, period, array)

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.

Return type:

None