Commons

Common tools for contributors and users.

The tools in this sub-package are intended, to help both contributors to OpenFisca Core and to country packages.

Official Public API:
Deprecated:

Note

The deprecated imports are transitional, in order to ensure non-breaking changes, and could be removed from the codebase in the next major release.

Note

How imports are being used today:

from openfisca_core.commons import *  # Bad
from openfisca_core.commons.formulas import switch  # Bad
from openfisca_core.commons.decorators import deprecated  # Bad

The previous examples provoke cyclic dependency problems, that prevent us from modularizing the different components of the library, which would make them easier to test and to maintain.

How they could be used in a future release:

from openfisca_core import commons from openfisca_core.commons import deprecated

deprecated() # Good: import classes as publicly exposed commons.switch() # Good: use functions as publicly exposed

class openfisca_core.commons.Dummy → None[source]

A class that did nothing.

Examples

>>> Dummy()
<openfisca_core.commons.dummy.Dummy object...

Deprecated since version 34.7.0: Dummy has been deprecated and it will be removed in the future.

openfisca_core.commons.average_rate(target: nptyping.types._ndarray.NDArray, varying: typing.Union[nptyping.types._ndarray.NDArray, typing.Sequence[float]], trim: typing.Union[nptyping.types._ndarray.NDArray, typing.Sequence[float], NoneType] = None) → nptyping.types._ndarray.NDArray[source]

Computes the average rate of a target net income.

Given a target net income, and according to the varying gross income. Optionally, a trim can be applied consisting of the lower and upper bounds of the average rate to be computed.

Note

Usually, target and varying are the same size.

Parameters:
  • target – The targeted net income.
  • varying – The varying gross income.
  • trim – The lower and upper bounds of the average rate.
Returns:

The average rate for each target.

When trim is provided, values that are out of the provided bounds are replaced by numpy.nan.

Return type:

numpy.ndarray of float

Examples

>>> target = numpy.array([1, 2, 3])
>>> varying = [2, 2, 2]
>>> trim = [-1, .25]
>>> average_rate(target, varying, trim)
array([ nan,  0. , -0.5])
openfisca_core.commons.marginal_rate(target: nptyping.types._ndarray.NDArray, varying: nptyping.types._ndarray.NDArray, trim: typing.Union[nptyping.types._ndarray.NDArray, typing.Sequence[float], NoneType] = None) → nptyping.types._ndarray.NDArray[source]

Computes the marginal rate of a target net income.

Given a target net income, and according to the varying gross income. Optionally, a trim can be applied consisting of the lower and upper bounds of the marginal rate to be computed.

Note

Usually, target and varying are the same size.

Parameters:
  • target – The targeted net income.
  • varying – The varying gross income.
  • trim – The lower and upper bounds of the marginal rate.
Returns:

The marginal rate for each target.

When trim is provided, values that are out of the provided bounds are replaced by numpy.nan.

Return type:

numpy.ndarray of float

Examples

>>> target = numpy.array([1, 2, 3])
>>> varying = numpy.array([1, 2, 4])
>>> trim = [.25, .75]
>>> marginal_rate(target, varying, trim)
array([nan, 0.5])
openfisca_core.commons.empty_clone(original: T) → T[source]

Creates an empty instance of the same class of the original object.

Parameters:original – An object to clone.
Returns:The cloned, empty, object.

Examples

>>> Foo = type("Foo", (list,), {})
>>> foo = Foo([1, 2, 3])
>>> foo
[1, 2, 3]
>>> bar = empty_clone(foo)
>>> bar
[]
>>> isinstance(bar, Foo)
True
openfisca_core.commons.stringify_array(array: nptyping.types._ndarray.NDArray) → str[source]

Generates a clean string representation of a numpy array.

Parameters:array – An array.
Returns:“None” if the array is None, the stringified array otherwise.
Return type:str

Examples

>>> import numpy
>>> stringify_array(None)
'None'
>>> array = numpy.array([10, 20.])
>>> stringify_array(array)
'[10.0, 20.0]'
>>> array = numpy.array(["10", "Twenty"])
>>> stringify_array(array)
'[10, Twenty]'
>>> array = numpy.array([list, dict(), stringify_array])
>>> stringify_array(array)
"[<class 'list'>, {}, <function stringify_array...]"
openfisca_core.commons.apply_thresholds(input: nptyping.types._ndarray.NDArray, thresholds: typing.Union[nptyping.types._ndarray.NDArray, typing.Sequence[float]], choices: typing.Union[nptyping.types._ndarray.NDArray, typing.Sequence[float]]) → nptyping.types._ndarray.NDArray[source]

Makes a choice based on an input and thresholds.

From a list of choices, this function selects one of these values based on a list of inputs, depending on the value of each input within a list of thresholds.

Parameters:
  • input – A list of inputs to make a choice from.
  • thresholds – A list of thresholds to choose.
  • choices – A list of the possible values to choose from.
Returns:

A list of the values chosen.

Return type:

numpy.ndarray of float

Raises:

AssertionError – When the number of thresholds (t) and the number of choices (c) are not either t == c or t == c - 1.

Examples

>>> input = numpy.array([4, 5, 6, 7, 8])
>>> thresholds = [5, 7]
>>> choices = [10, 15, 20]
>>> apply_thresholds(input, thresholds, choices)
array([10, 10, 15, 15, 20])
openfisca_core.commons.concat(this: typing.Union[nptyping.types._ndarray.NDArray, typing.Sequence[str]], that: typing.Union[nptyping.types._ndarray.NDArray, typing.Sequence[str]]) → nptyping.types._ndarray.NDArray[source]

Concatenates the values of two arrays.

Parameters:
  • this – An array to concatenate.
  • that – Another array to concatenate.
Returns:

An array with the concatenated values.

Return type:

numpy.ndarray of float

Examples

>>> this = ["this", "that"]
>>> that = numpy.array([1, 2.5])
>>> concat(this, that)
array(['this1.0', 'that2.5']...)
openfisca_core.commons.switch(conditions: nptyping.types._ndarray.NDArray, value_by_condition: typing.Dict[float, ~T]) → nptyping.types._ndarray.NDArray[source]

Mimicks a switch statement.

Given an array of conditions, returns an array of the same size, replacing each condition item with the matching given value.

Parameters:
  • conditions – An array of conditions.
  • value_by_condition – Values to replace for each condition.
Returns:

An array with the replaced values.

Return type:

numpy.ndarray

Raises:

AssertionError – When value_by_condition is empty.

Examples

>>> conditions = numpy.array([1, 1, 1, 2])
>>> value_by_condition = {1: 80, 2: 90}
>>> switch(conditions, value_by_condition)
array([80, 80, 80, 90])