Merge pull request #75 from sjsrey/schutz

Schutz inequality measures

docs/_static/references.bib

@@ -1,3 +1,33 @@
+@article{schutz1951MeasurementIncome,
+  title = {On the {{Measurement}} of {{Income Inequality}}},
+  author = {Schutz, Robert R.},
+  year = {1951},
+  journal = {The American Economic Review},
+  volume = {41},
+  number = {1},
+  eprint = {1815968},
+  eprinttype = {jstor},
+  pages = {107--122},
+  publisher = {American Economic Association},
+  issn = {0002-8282},
+  urldate = {2024-07-22},
+  file = {/home/serge/Zotero/storage/B54Q8IH7/Schutz - 1951 - On the Measurement of Income Inequality.pdf}
+}
+
+
+@Article{Atkinson_1970_Measurement,
+  title = {On the Measurement of Inequality},
+  author = {Atkinson, Anthony B},
+  year = {1970},
+  journal = {Journal of Economic Theory},
+  volume = {2},
+  number = {3},
+  pages = {244--263},
+  issn = {00220531},
+  doi = {10.1016/0022-0531(70)90039-6},
+  urldate = {2024-08-09},
+}
+
 @article{care_2012,
   author = {Care, David C. and Pinkerton, Ruth M. and Poot, Jacques and Coleman, Andrew},
   title = {{Residential sorting across Auckland neighbourhoods}},

docs/api.rst

@@ -7,17 +7,15 @@ API reference
 
 .. _inequality_api:
 
-Theil Inequality Measures
--------------------------
+
+Atkinson Inequality Measures
+----------------------------
 
 .. autosummary::
    :toctree: generated/
 
-    inequality.theil.Theil 
-    inequality.theil.TheilD
-    inequality.theil.TheilDSim
-
-
+    inequality.atkinson.Atkinson
+
 Gini Inequality Measures
 ------------------------
 
@@ -27,6 +25,26 @@ Gini Inequality Measures
     inequality.gini.Gini
     inequality.gini.Gini_Spatial
 
+Schutz Inequality Measures
+--------------------------
+
+.. autosummary::
+   :toctree: generated/
+
+    inequality.schutz.Schutz
+
+
+Theil Inequality Measures
+-------------------------
+
+.. autosummary::
+   :toctree: generated/
+
+    inequality.theil.Theil 
+    inequality.theil.TheilD
+    inequality.theil.TheilDSim
+
+
 Pengram
 -------
 

inequality/__init__.py

@@ -7,7 +7,7 @@
 import contextlib
 from importlib.metadata import PackageNotFoundError, version
 
-from . import gini, theil
+from . import atkinson, gini, schutz, theil
 from ._indices import (
     abundance,
     ellison_glaeser_egg,

inequality/atkinson.py

@@ -0,0 +1,112 @@
+import numpy as np
+
+__all__ = ["Atkinson", "atkinson"]
+
+
+def atkinson(y, epsilon):
+    """Compute the Atkinson index for a given distribution of income or wealth.
+
+    The Atkinson index is a measure of economic inequality that takes
+    into account the social aversion to inequality. It is sensitive to
+    changes in different parts of the income distribution depending on
+    the value of the parameter epsilon.
+
+    Parameters
+    ----------
+    y : array-like
+        An array of income or wealth values.
+    epsilon : float
+        The inequality aversion parameter. Higher values of epsilon
+        give more weight to the lower end of the distribution, making
+        the index more sensitive to changes in the lower tail.
+
+    Returns
+    -------
+    float
+        The Atkinson index, which ranges from 0 (perfect equality) to
+        1 (maximum inequality).
+
+    Notes
+    -----
+    - If epsilon equals 0, the Atkinson index is 0 regardless of the
+      distribution, as it implies no aversion to inequality.
+    - If epsilon equals 1, the Atkinson index is calculated using the
+      geometric mean.
+    - The input array y should contain positive values for a
+      meaningful calculation.
+
+    Example
+    -------
+    >>> import numpy as np
+    >>> incomes = np.array([10, 20, 30, 40, 50])
+    >>> float(round(atkinson(incomes, 0.5), 5))
+    0.06315
+    >>> float(round(atkinson(incomes, 1),5))
+    0.13161
+
+    """
+    y = np.asarray(y)
+    if epsilon == 1:
+        geom_mean = np.exp(np.mean(np.log(y)))
+        return 1 - geom_mean / y.mean()
+    else:
+        ye = y ** (1 - epsilon)
+        ye_bar = ye.mean()
+        ye_bar = ye_bar ** (1 / (1 - epsilon))
+        return 1 - ye_bar / y.mean()
+
+
+class Atkinson:
+    """A class to calculate and store the Atkinson index and the equally
+    distributed equivalent(EDE).
+
+    The Atkinson index is a measure of economic inequality that takes
+    into account the social aversion to inequality. The equally
+    distributed equivalent (EDE) represents the level of income that,
+    if equally distributed, would give the same level of social
+    welfare as the actual distribution.
+
+    See: cite: `Atkinson_1970_Measurement`.
+
+    Parameters
+    ----------
+    y: array-like
+        An array of income or wealth values.
+    epsilon: float
+        The inequality aversion parameter. Higher values of epsilon
+        give more weight to the lower end of the distribution, making
+        the index more sensitive to changes in the lower tail.
+
+    Attributes
+    ----------
+    y: array-like
+        The input array of income or wealth values.
+    epsilon: float
+        The inequality aversion parameter.
+    A: float
+        The calculated Atkinson index.
+    EDE: float
+        The equally distributed equivalent(EDE) of the income or
+        wealth distribution.
+
+    Example
+    -------
+    >> > incomes = np.array([10, 20, 30, 40, 50])
+    >> > atkinson = Atkinson(incomes, 0.5)
+    >> > float(round(atkinson.A, 5))
+    0.06315
+    >> > float(round(atkinson.EDE, 5))
+    28.1054
+    >> > atkinson = Atkinson(incomes, 1)
+    >> > float(round(atkinson.A, 5))
+    0.13161
+    >> > float(round(atkinson.EDE, 5))
+    26.05171
+
+    """
+
+    def __init__(self, y, epsilon):
+        self.y = np.asarray(y)
+        self.epsilon = epsilon
+        self.A = atkinson(y, epsilon)
+        self.EDE = y.mean() * (1 - self.A)