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.
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
See also
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.
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.
A list of the values chosen.
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])
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.
The average rate for each target.
When trim is provided, values that are out of the provided bounds
are replaced by numpy.nan.
Examples
>>> target = numpy.array([1, 2, 3])
>>> varying = [2, 2, 2]
>>> trim = [-1, .25]
>>> average_rate(target, varying, trim)
array([ nan, 0. , -0.5])
Concatenates the values of two arrays.
An array with the concatenated values.
Examples
>>> this = ["this", "that"]
>>> that = numpy.array([1, 2.5])
>>> concat(this, that)
array(['this1.0', 'that2.5']...)
Creates an empty instance of the same class of the original object.
original (TypeVar(T)) – An object to clone.
TypeVar(T)
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
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.
The marginal rate for each target.
When trim is provided, values that are out of the provided bounds
are replaced by numpy.nan.
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])
Generates a clean string representation of a numpy array.
array (NDArray) – An array.
“None” if the array is None, the stringified array otherwise.
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...]"
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.
An array with the replaced values.
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])