OpenFisca-Core-test 46.0.0__py3-none-any.whl

openfisca_core/commons/__init__.py

@@ -0,0 +1,18 @@
+"""Common tools for contributors and users."""
+
+from .dummy import Dummy
+from .formulas import apply_thresholds, concat, switch
+from .misc import empty_clone, eval_expression, stringify_array
+from .rates import average_rate, marginal_rate
+
+__all__ = [
+    "Dummy",
+    "apply_thresholds",
+    "average_rate",
+    "concat",
+    "empty_clone",
+    "eval_expression",
+    "marginal_rate",
+    "stringify_array",
+    "switch",
+]

openfisca_core/commons/dummy.py

@@ -0,0 +1,25 @@
+import warnings
+
+
+class Dummy:
+    """A class that did nothing.
+
+    Examples:
+        >>> Dummy()
+        <openfisca_core.commons.dummy.Dummy object...
+
+    .. deprecated:: 34.7.0
+        :class:`.Dummy` has been deprecated and it will be removed in the
+        future.
+
+    """
+
+    def __init__(self) -> None:
+        message = [
+            "The 'Dummy' class has been deprecated since version 34.7.0,",
+            "and will be removed in the future.",
+        ]
+        warnings.warn(" ".join(message), DeprecationWarning, stacklevel=2)
+
+
+__all__ = ["Dummy"]

openfisca_core/commons/formulas.py

@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy
+
+from openfisca_core import types as t
+
+
+def apply_thresholds(
+    input: t.FloatArray,
+    thresholds: t.ArrayLike[float],
+    choices: t.ArrayLike[float],
+) -> t.FloatArray:
+    """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``.
+
+    Args:
+        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:
+        ndarray[float32]: A list of the values chosen.
+
+    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])
+
+    """
+    condlist: list[t.Array[numpy.bool_] | bool]
+    condlist = [input <= threshold for threshold in thresholds]
+
+    if len(condlist) == len(choices) - 1:
+        # If a choice is provided for input > highest threshold, last condition
+        # must be true to return it.
+        condlist += [True]
+
+    msg = (
+        "'apply_thresholds' must be called with the same number of thresholds "
+        "than choices, or one more choice."
+    )
+    assert len(condlist) == len(choices), msg
+
+    return numpy.select(condlist, choices)
+
+
+def concat(
+    this: t.StrArray | t.ArrayLike[object],
+    that: t.StrArray | t.ArrayLike[object],
+) -> t.StrArray:
+    """Concatenate the values of two arrays.
+
+    Args:
+        this: An array to concatenate.
+        that: Another array to concatenate.
+
+    Returns:
+        ndarray[str_]: An array with the concatenated values.
+
+    Examples:
+        >>> this = ["this", "that"]
+        >>> that = numpy.array([1, 2.5])
+        >>> concat(this, that)
+        array(['this1.0', 'that2.5']...)
+
+    """
+    if not isinstance(this, numpy.ndarray):
+        this = numpy.array(this)
+
+    if not numpy.issubdtype(this.dtype, numpy.str_):
+        this = this.astype("str")
+
+    if not isinstance(that, numpy.ndarray):
+        that = numpy.array(that)
+
+    if not numpy.issubdtype(that.dtype, numpy.str_):
+        that = that.astype("str")
+
+    return numpy.char.add(this, that)
+
+
+def switch(
+    conditions: t.FloatArray | t.ArrayLike[float],
+    value_by_condition: Mapping[float, float],
+) -> t.FloatArray:
+    """Mimic a switch statement.
+
+    Given an array of conditions, returns an array of the same size,
+    replacing each condition item with the matching given value.
+
+    Args:
+        conditions: An array of conditions.
+        value_by_condition: Values to replace for each condition.
+
+    Returns:
+        ndarray[float32]: An array with the replaced values.
+
+    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])
+
+    """
+    assert len(value_by_condition) > 0, (
+        "'switch' must be called with at least one value."
+    )
+
+    condlist = [conditions == condition for condition in value_by_condition]
+
+    return numpy.select(condlist, tuple(value_by_condition.values()))
+
+
+__all__ = ["apply_thresholds", "concat", "switch"]

openfisca_core/commons/misc.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+import numexpr
+
+from openfisca_core import types as t
+
+
+def empty_clone(original: object) -> object:
+    """Create an empty instance of the same class of the original object.
+
+    Args:
+        original: An object to clone.
+
+    Returns:
+        object: 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
+
+    """
+
+    def __init__(_: object) -> None: ...
+
+    Dummy = type(
+        "Dummy",
+        (original.__class__,),
+        {"__init__": __init__},
+    )
+
+    new = Dummy()
+    new.__class__ = original.__class__
+    return new
+
+
+def stringify_array(array: None | t.VarArray) -> str:
+    """Generate a clean string representation of a numpy array.
+
+    Args:
+        array: An array.
+
+    Returns:
+        str: ``"None"`` if the ``array`` is ``None``.
+        str: The stringified ``array`` otherwise.
+
+    Examples:
+        >>> import numpy
+        >>> stringify_array(None)
+        'None'
+
+        >>> array = numpy.array([10, 20.0])
+        >>> 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...]"
+
+    """
+    if array is None:
+        return "None"
+
+    return f"[{', '.join(str(cell) for cell in array)}]"
+
+
+def eval_expression(
+    expression: str,
+) -> str | t.BoolArray | t.IntArray | t.FloatArray:
+    """Evaluate a string expression to a numpy array.
+
+    Args:
+        expression: An expression to evaluate.
+
+    Returns:
+        ndarray: The result of the evaluation.
+        str: The expression if it couldn't be evaluated.
+
+    Examples:
+        >>> eval_expression("1 + 2")
+        array(3, dtype=int32)
+
+        >>> eval_expression("salary")
+        'salary'
+
+        >>> eval_expression("date of birth")
+        'date of birth'
+
+    """
+    try:
+        return numexpr.evaluate(expression)
+
+    except (KeyError, TypeError, SyntaxError):
+        return expression
+
+
+__all__ = ["empty_clone", "eval_expression", "stringify_array"]

openfisca_core/commons/rates.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+import numpy
+
+from openfisca_core import types as t
+
+
+def average_rate(
+    target: t.FloatArray,
+    varying: t.FloatArray | t.ArrayLike[float],
+    trim: None | t.ArrayLike[float] = None,
+) -> t.FloatArray:
+    """Compute 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.
+
+    Args:
+        target: The targeted net income.
+        varying: The varying gross income.
+        trim: The lower and upper bounds of the average rate.
+
+    Returns:
+        ndarray[float32]: The average rate for each target. When ``trim``
+            is provided, values that are out of the provided bounds are
+            replaced by :obj:`numpy.nan`.
+
+    Examples:
+        >>> target = numpy.array([1, 2, 3])
+        >>> varying = [2, 2, 2]
+        >>> trim = [-1, 0.25]
+        >>> average_rate(target, varying, trim)
+        array([ nan,  0. , -0.5])
+
+    """
+    if not isinstance(varying, numpy.ndarray):
+        varying = numpy.array(varying, dtype=numpy.float32)
+
+    average_rate = 1 - target / varying
+
+    if trim is not None:
+        average_rate = numpy.where(
+            average_rate <= max(trim),
+            average_rate,
+            numpy.nan,
+        )
+
+        average_rate = numpy.where(
+            average_rate >= min(trim),
+            average_rate,
+            numpy.nan,
+        )
+
+    return average_rate
+
+
+def marginal_rate(
+    target: t.FloatArray,
+    varying: t.FloatArray | t.ArrayLike[float],
+    trim: None | t.ArrayLike[float] = None,
+) -> t.FloatArray:
+    """Compute 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.
+
+    Args:
+        target: The targeted net income.
+        varying: The varying gross income.
+        trim: The lower and upper bounds of the marginal rate.
+
+    Returns:
+        ndarray[float32]: The marginal rate for each target. When ``trim``
+            is provided, values that are out of the provided bounds are
+            replaced by :class:`numpy.nan`.
+
+    Examples:
+        >>> target = numpy.array([1, 2, 3])
+        >>> varying = numpy.array([1, 2, 4])
+        >>> trim = [0.25, 0.75]
+        >>> marginal_rate(target, varying, trim)
+        array([nan, 0.5])
+
+    """
+    if not isinstance(varying, numpy.ndarray):
+        varying = numpy.array(varying, dtype=numpy.float32)
+
+    marginal_rate = +1 - (target[:-1] - target[1:]) / (varying[:-1] - varying[1:])
+
+    if trim is not None:
+        marginal_rate = numpy.where(
+            marginal_rate <= max(trim),
+            marginal_rate,
+            numpy.nan,
+        )
+
+        marginal_rate = numpy.where(
+            marginal_rate >= min(trim),
+            marginal_rate,
+            numpy.nan,
+        )
+
+    return marginal_rate
+
+
+__all__ = ["average_rate", "marginal_rate"]

openfisca_core/commons/tests/test_dummy.py

@@ -0,0 +1,9 @@
+import pytest
+
+from openfisca_core.commons import Dummy
+
+
+def test_dummy_deprecation() -> None:
+    """Dummy throws a deprecation warning when instantiated."""
+    with pytest.warns(DeprecationWarning):
+        assert Dummy()

openfisca_core/commons/tests/test_formulas.py

@@ -0,0 +1,75 @@
+import numpy
+import pytest
+from numpy.testing import assert_array_equal
+
+from openfisca_core import commons
+
+
+def test_apply_thresholds_when_several_inputs() -> None:
+    """Make a choice for any given input."""
+    input_ = numpy.array([4, 5, 6, 7, 8, 9, 10])
+    thresholds = [5, 7, 9]
+    choices = [10, 15, 20, 25]
+
+    result = commons.apply_thresholds(input_, thresholds, choices)
+
+    assert_array_equal(result, [10, 10, 15, 15, 20, 20, 25])
+
+
+def test_apply_thresholds_when_too_many_thresholds() -> None:
+    """Raise an AssertionError when thresholds > choices."""
+    input_ = numpy.array([6])
+    thresholds = [5, 7, 9, 11]
+    choices = [10, 15, 20]
+
+    with pytest.raises(AssertionError):
+        assert commons.apply_thresholds(input_, thresholds, choices)
+
+
+def test_apply_thresholds_when_too_many_choices() -> None:
+    """Raise an AssertionError when thresholds < choices - 1."""
+    input_ = numpy.array([6])
+    thresholds = [5, 7]
+    choices = [10, 15, 20, 25]
+
+    with pytest.raises(AssertionError):
+        assert commons.apply_thresholds(input_, thresholds, choices)
+
+
+def test_concat_when_this_is_array_not_str() -> None:
+    """Cast ``this`` to ``str`` when it is a NumPy array other than string."""
+    this = numpy.array([1, 2])
+    that = numpy.array(["la", "o"])
+
+    result = commons.concat(this, that)
+
+    assert_array_equal(result, ["1la", "2o"])
+
+
+def test_concat_when_that_is_array_not_str() -> None:
+    """Cast ``that`` to ``str`` when it is a NumPy array other than string."""
+    this = numpy.array(["ho", "cha"])
+    that = numpy.array([1, 2])
+
+    result = commons.concat(this, that)
+
+    assert_array_equal(result, ["ho1", "cha2"])
+
+
+def test_concat_when_args_not_str_array_like() -> None:
+    """Cast ``this`` and ``that`` to a NumPy array or strings."""
+    this = (1, 2)
+    that = (3, 4)
+
+    result = commons.concat(this, that)
+
+    assert_array_equal(result, ["13", "24"])
+
+
+def test_switch_when_values_are_empty() -> None:
+    """Raise an AssertionError when the values are empty."""
+    conditions = [1, 1, 1, 2]
+    value_by_condition = {}
+
+    with pytest.raises(AssertionError):
+        assert commons.switch(conditions, value_by_condition)

openfisca_core/commons/tests/test_rates.py

@@ -0,0 +1,26 @@
+import math
+
+import numpy
+from numpy.testing import assert_array_equal
+
+from openfisca_core import commons
+
+
+def test_average_rate_when_varying_is_zero() -> None:
+    """Yield infinity when the varying gross income crosses zero."""
+    target = numpy.array([1, 2, 3])
+    varying = [0, 0, 0]
+
+    result = commons.average_rate(target, varying)
+
+    assert_array_equal(result, numpy.array([-math.inf, -math.inf, -math.inf]))
+
+
+def test_marginal_rate_when_varying_is_zero() -> None:
+    """Yield infinity when the varying gross income crosses zero."""
+    target = numpy.array([1, 2, 3])
+    varying = numpy.array([0, 0, 0])
+
+    result = commons.marginal_rate(target, varying)
+
+    assert_array_equal(result, numpy.array([math.inf, math.inf]))

openfisca_core/data_storage/__init__.py

@@ -0,0 +1,7 @@
+"""Different storage backends for the data of a simulation."""
+
+from . import types
+from .in_memory_storage import InMemoryStorage
+from .on_disk_storage import OnDiskStorage
+
+__all__ = ["InMemoryStorage", "OnDiskStorage", "types"]