Implementing legislation parameters
Legislation parameters can be found in the
parameters directory of your country package.
The parameters are organized with in a tree structure.
tax_on_salary.public_sector.ratecan be found in
Example of a
In this file structure:
universal_income.amountare parameters (or scales).
How to write a new parameter
if you wish to update a parameter, read our legislation evolution page.
- Find where the parameter fits
A parameter is located inside a node, that has the same name as the directory it is contained in.
tax_on_salary.public_sectoris the node that contains the
- Create a new parameter YAML file
A legislative parameter is defined by a YAML file of the same name. Possible attributes are:
reference(optional) Legislative reference;
unit(optional) Can be:
year: The values are years;
currency: The values are in the unit of currency of the country;
/1: The values are percentages, with
values: Value of the parameter for several dates.
description: Universal income unit: currency values: 1993-01-01: value: 1000 2010-01-01: value: 1500 reference: http://law.reference.org/universal_income 2020-01-01: expected: 1700
In this example, the parameter
- undefined before 1993;
- equal to 1000 from 1993 to 2010;
- equal to 1500 in 2010
- expected to be raised to 1700 "local currency" in 2020.
The ordering of the dates has no effect. It is recommended to add legislative references for every value?
- Use the parameter in a variable
Naming conventions and reserved words
Names should begin with a lowercase letter and should contain only lowercase letters and the underscore (
The following keywords are reserved and should not be used as names :
YAML parameter files should not be name
Use a YAML files to define nodes
A node can be defined with a YAML file instead of a directory. In such a case, the name of the file defines the name of the node. Such a file can define children nodes (which can define grandchildren...).
description: Tax on salaries reference: http://fiscaladministration.government/tax_on_salaries.html tax_scale: bracket: ... public_sector: description: Tax on salaries for public sector rate: values: ...
Scales are constituted of brackets. Brackets are defined by amounts, bases, rates, average rates and thresholds.
description: Scale for tax on salaries brackets: - rate: 1950-01-01: value: 0.0 2010-01-01: value: 0.02 threshold: 1950-01-01: value: 0.0 - rate: 1950-01-01: value: 0.2 threshold: 1950-01-01: value: 2000
Example: the french tax scale on income
Import parameters from IPP tables
This section applies only to OpenFisca-France.
The IPP is a French centre in economics which produces tax and benefit tables in the
XLSX format, with parameters history.
The OpenFisca team works on importing those data into the YAML parameter files of OpenFisca-France.
See this README for more information.
Computing a parameter that depends on a variable (fancy indexing)
Sometimes, the value of a parameter depends on a variable (e.g. a housing benefit that depends on the zone the house is built on).
To be more specific, let's assume that:
- Households who rent their accomodation can get a
- The amount of this benefit depends on which
zonethe household lives in. The
zonecan take only three values:
- The amount also depends on the composition of the household.
The parameters of this benefit can be defined in a
zone_1: single: description: "Amount of housing benefit for a single person, in zone 1" values: 2015-01-01: value: 150 couple: description: "Amount of housing benefit for a couple, in zone 1" values: 2015-01-01: value: 250 per_child: description: "Amount of housing benefit per child, in zone 1" values: 2015-01-01: value: 80 zone_2: single: description: "Amount of housing benefit for a single person, in zone 2" values: 2015-01-01: value: 120 couple: description: "Amount of housing benefit for a couple, in zone 2" values: 2015-01-01: value: 220 per_child: description: "Amount of housing benefit per child, in zone 2" values: 2015-01-01: value: 60 zone_3: single: description: "Amount of housing benefit for a single person, in zone 3" values: 2015-01-01: value: 100 couple: description: "Amount of housing benefit for a couple, in zone 3" values: 2015-01-01: value: 180 per_child: description: "Amount of housing benefit per child, in zone 3" values: 2015-01-01: value: 50
Then the formula calculting
housing_benefit can be implemented with:
def formula(household, period, parameters): is_couple = household('couple', period) nb_children = household('nb_children', period) zone = household('zone', period) P = parameters(period).housing_benefit[zone] return where(is_couple, P.couple, P.single) + nb_children * P.per_children
parameters(period).housing_benefit[zone] return the parameters for the zone corresponding to the household.
If there are many households in your simulation, this parameter will be vectorial : it may have a different value for each household of your entity.
To be able to use this notation, all the children node of the parameter node
housing_benefit must be homogenous. In the previous example,
housing_benefit.zone_3 are homogenous, as they have the same subnodes.
However, let's imagine that
housing_benefit.yaml had another subnode named
coeff_furnished, which described a coefficient to apply to the benefit is the accomodation is rented furnished:
coeff_furnished: description: "Coefficient to apply if the accomodation is rented furnished" values: 2015-01-01: value: 0.75 zone_1: single: description: "Amount of housing benefit for a single person, in zone 1" values: 2015-01-01: value: 150 (...)
In this case,
parameters(period).housing_benefit[zone] would raise en error, whatever
zone contains, as the homogeneity condition is not respected:
housing_benefit.zone_1 is a node, while
housing_benefit.coeff_furnished is a parameter.
To solve this issue, the good practice would be to create an intermediate node
coeff_furnished: description: "Coefficient to apply if the accomodation is rented furnished" values: 2015-01-01: value: 0.75 amount_by_zone: zone_1: single: description: "Amount of housing benefit for a single person, in zone 1" values: 2015-01-01: value: 150 (...)
And then to get
How to navigate the parameters in Python
Set-up your python file by importing a
country package and building the
tax and benefits system
import openfisca_country_template tax_benefit_system = openfisca_country_template.CountryTaxBenefitSystem()
Access a parameter for all periods
To access a point in the parameter tree, call
Example : Access the
benefitbranch of the
basic_income: 2015-12-01: 600.0 housing_allowance: 2016-12-01: None 2010-01-01: 0.25
basic_income, a parameter of the
Access a parameter for a specific period
Request a branch of a parameter at a given date with the
How to update parameters in python
To add an entry to an existing parameter, use
tax_benefit_system.parameters.benefits.basic_bro.update("2017-01", value = 2000) tax_benefit_system.parameters.benefits.basic_bro
2017-01-01: 2000 2015-12-01: 600.0