Tax-benefit systems#

The policyengine_core.taxbenefitsystems module contains the definition of TaxBenefitSystem, the class that represents a country’s tax-benefit system: the logic, parameters and entities, not the input data.

TaxBenefitSystem#

class policyengine_core.taxbenefitsystems.tax_benefit_system.TaxBenefitSystem(entities: Sequence[Entity] = None, reform=None)#

Bases: object

Represents the legislation.

It stores parameters (values defined for everyone) and variables (values defined for some given entity e.g. a person).

parameters#: Directory containing the YAML parameter files.

Parameters:: entities – Entities used by the tax benefit system.

add_modelled_policy_metadata()#: Adds metadata to variables that are modelled by PolicyEngine.

add_variable(variable: Type[Variable]) → Variable#

Adds an OpenFisca variable to the tax and benefit system.

Parameters:: variable – The variable class to add. Must be a subclass of Variable.
Raises:: policyengine_core.errors.VariableNameConflictError – if a variable with the same name have previously been added to the tax and benefit system.

add_variable_metadata_from_folder(file_path: str) → None#: Adds metadata from a given README.md file to the tax and benefit system.

add_variables(*variables: Type[Variable]) → None#

Adds OpenFisca Variable classes to the TaxBenefitSystem.

See also add_variable

add_variables_from_directory(directory: str) → None#: Recursively explores a directory, and adds all OpenFisca variables found there to the tax and benefit system.

add_variables_from_file(file_path: str) → None#: Adds all OpenFisca variables contained in a given file to the tax and benefit system.

apply_reform(reform_path: str) → TaxBenefitSystem#

Generates a new tax and benefit system applying a reform to the tax and benefit system.

The current tax and benefit system is not mutated.

Parameters:: reform_path – The reform to apply. Must respect the format installed_package.sub_module.reform
Returns:: A reformed tax and benefit system.
Return type:: TaxBenefitSystem

Example

>>> self.apply_reform('openfisca_france.reforms.inversion_revenus')

get_package_metadata() → dict#

Gets metatada relative to the country package the tax and benefit system is built from.

Returns:: Country package metadata
Return type:: dict

Example:

>>> tax_benefit_system.get_package_metadata()
>>> {
>>>    'location': '/path/to/dir/containing/package',
>>>    'name': 'openfisca-france',
>>>    'repository_url': 'https://github.com/openfisca/openfisca-france',
>>>    'version': '17.2.0'
>>>    }

get_parameters_at_instant(instant: Instant) → ParameterNodeAtInstant#

Get the parameters of the legislation at a given instant

Parameters:: instant – str of the format ‘YYYY-MM-DD’ or Instant instance.
Returns:: The parameters of the legislation at a given instant.
Return type:: ParameterNodeAtInstant

get_variable(variable_name: str, check_existence: bool = False) → Variable#

Get a variable from the tax and benefit system.

Parameters:

variable_name – Name of the requested variable.
check_existence – If True, raise an error if the requested variable does not exist.

get_variables(entity: Entity = None) → dict#

Gets all variables contained in a tax and benefit system.

Parameters:: entity (Entity) – If set, returns only the variable defined for the given entity.
Returns:: A dictionary, indexed by variable names.
Return type:: dict

load_extension(extension: str) → None#

Loads an extension to the tax and benefit system.

Parameters:: extension (str) – The extension to load. Can be an absolute path pointing to an extension directory, or the name of an OpenFisca extension installed as a pip package.

load_parameters(path_to_yaml_dir: str) → None#

Loads the legislation parameter for a directory containing YAML parameters files.

Parameters:: path_to_yaml_dir – Absolute path towards the YAML parameter directory.

Example:

>>> self.load_parameters('/path/to/yaml/parameters/dir')

modify_parameters(modifier_function: Callable[[ParameterNode], ParameterNode]) → None#

Make modifications on the parameters of the legislation.

Call this function in apply() if the reform asks for legislation parameter modifications.

Parameters:: modifier_function – A function that takes a ParameterNode and should return an object of the same type.

neutralize_variable(variable_name: str) → None#

Neutralizes an OpenFisca variable existing in the tax and benefit system.

A neutralized variable always returns its default value when computed.

Trying to set inputs for a neutralized variable has no effect except raising a warning.

preprocess_situation(situation: dict, default_period=None) → dict#

Normalize entity-form input before the builder creates populations.

Country models can override this to fill missing entity definitions. SimulationBuilder.build_from_entities passes a deep copy of the caller’s situation, with any axes still present, and its default period as set (None, a string, an integer or a Period). Through build_from_dict and Simulation(situation=...), singular entity aliases are already expanded; a direct build_from_entities call passes the caller’s keys as given. The hook runs before the builder validates entities, so it may receive a situation with no persons. Return a dict holding an entity-form situation for the builder’s usual validation. A Reform runs its country system’s hook with the reform as the system, so the hook sees reformed parameters and variables. Only the country system’s hook runs: a Reform subclass that overrides this method is skipped when another reform wraps it, and a hook set on the country system instance itself stays bound to that instance, so it reads the baseline’s values. Dataset and variable-only inputs do not use this hook.

replace_variable(variable: Type[Variable]) → None#

Replaces an existing OpenFisca variable in the tax and benefit system by a new one.

The new variable must have the same name than the replaced one.

If no variable with the given name exists in the tax and benefit system, no error will be raised and the new variable will be simply added.

Parameters:: variable (Variable) – New variable class to add. Must be a subclass of Variable.

update_variable(variable: Type[Variable]) → Variable#

Updates an existing OpenFisca variable in the tax and benefit system.

All attributes of the updated variable that are not explicitely overridden by the new variable will stay unchanged.

The new variable must have the same name than the updated one.

If no variable with the given name exists in the tax and benefit system, no error will be raised and the new variable will be simply added.

Parameters:: variable (Variable) – Variable class to add. Must be a subclass of Variable.