Every variable is defined for a type of entity: for instance persons or households.
However, I may for instance:
in a formula defined for a person, want to know some property of their household.
in a formula defined for a household, want to know some property of the household members.
You can get the number of person with a given role in an entity with the nb_persons(role) method. If no role is given, it will return the numbers of people in the entity.
def formula(household, period):
nb_persons = household.nb_persons()
nb_adults = household.nb_persons(Household.ADULT)
nb_children = household.nb_persons(Household.CHILD)
Note that roles are constants that can be accessed from their entity with the notation Entity.ROLE (in uppercase).
You can know whether a person has a certain role with the has_role(role) method:
def formula(person, period):
is_adult = person.has_role(Household.ADULT)
is_child = person.has_role(Household.CHILD)
For an entity, several methods allow you to aggregate the values of a quantity defined for its members.
entity.members('variable_name', period) allows you to calculate the value of a variable for all members of an entity.
entity.sum(result) sums previously calculated results. Similar functions such as min, max, any, and all work the same way.
For instance, let’s imagine a basic income paid to households with the following rules:
Any household is entitled to 500€ a month per adult, and 200€ a month per children.
The sum of salaries from all household members are deducted from the amount of the benefit.
class basic_income(Variable):
value_type = float
entity = Household
label = u"Basic income paid to households"
definition_period = MONTH
def formula(household, period):
nb_adults = household.nb_persons(Household.ADULT)
nb_children = household.nb_persons(Household.CHILD)
salaries = household.members('salary', period)
sum_salaries = household.sum(salaries)
result = nb_adults * 500 + nb_children * 200 - sum_salaries
result = max_(result, 0)
return result
person.entity('variable_name', period) allows you to get the value of variable_name for the entity containing person.
Let’s for example consider that any college student whose family benefits from the basic income will also individually be granted a scholarship of 100€ per month:
class college_scholarship(Variable):
value_type = float
entity = Person
label = u"College Scholarship for basic income recipients."
definition_period = MONTH
def formula(person, period):
is_student = person('is_student', period)
has_household_basic_income = person.household('basic_income', period) > 0
return is_student * has_household_basic_income * 100
Similarly, entity.unique_role('variable_name', period) allows you to get the value of variable_name for person who has the role unique_role in entity.
For instance, let’s assume Household has two unique roles, main_declarant and partner.
def formula(household, period):
household.main_declarant('salary', period) # main declarant's salary
household.partner('salary', period) # partner's salary