Theil's T inequality index, optionally decomposed between and within groups.
Theil, unlike the Gini, is additively decomposable: with a group label per value
it splits total inequality into a between-group term (e.g. centre versus
periphery) and a within-group term, so a researcher can attribute service
inequality to the right spatial scale. Bring your own group column (BYOD).
Parameters:
| Name |
Type |
Description |
Default |
values
|
array - like
|
Non-negative quantities (capacity, available bikes, ...); non-positive
entries are dropped (ln is undefined at 0).
|
required
|
groups
|
array - like
|
Group label per value. When given, returns the decomposition.
|
None
|
Returns:
| Type |
Description |
float or Series
|
The scalar Theil T, or a Series {total, between, within} (total ==
between + within).
|
See Also
palma_ratio : A tail-sensitive inequality alternative.
concentration_metrics : Gini + Theil + top-decile share in one call.
dynamic_gini_index : The same inequality over time.
Examples:
>>> round(float(theil_index([1, 1, 10, 10])), 3)
0.389
>>> theil_index([5, 5, 5, 5]) # perfect equality
0.0
Source code in src/gbfs_toolkit/analytics/distribution.py
| def theil_index(values, *, groups=None):
"""Theil's T inequality index, optionally decomposed between and within groups.
Theil, unlike the Gini, is additively decomposable: with a group label per value
it splits total inequality into a *between-group* term (e.g. centre versus
periphery) and a *within-group* term, so a researcher can attribute service
inequality to the right spatial scale. Bring your own group column (BYOD).
Parameters
----------
values : array-like
Non-negative quantities (capacity, available bikes, ...); non-positive
entries are dropped (``ln`` is undefined at 0).
groups : array-like, optional
Group label per value. When given, returns the decomposition.
Returns
-------
float or pandas.Series
The scalar Theil T, or a Series ``{total, between, within}`` (``total ==
between + within``).
See Also
--------
[`palma_ratio`][gbfs_toolkit.palma_ratio] : A tail-sensitive inequality alternative.
[`concentration_metrics`][gbfs_toolkit.concentration_metrics] : Gini + Theil + top-decile share in one call.
[`dynamic_gini_index`][gbfs_toolkit.dynamic_gini_index] : The same inequality over time.
Examples
--------
>>> round(float(theil_index([1, 1, 10, 10])), 3)
0.389
>>> theil_index([5, 5, 5, 5]) # perfect equality
0.0
"""
x = np.asarray(values, dtype="float64")
if groups is None:
return _theil(x)
g = np.asarray(groups)
mask = np.isfinite(x) & (x > 0)
x, g = x[mask], g[mask]
if x.size == 0:
return pd.Series({"total": float("nan"), "between": float("nan"), "within": float("nan")})
n = x.size
grand = x.sum()
between = 0.0
within = 0.0
for grp in pd.unique(g):
xs = x[g == grp]
s = xs.sum() / grand # share of total quantity
p = xs.size / n # share of population
if s > 0 and p > 0:
between += s * np.log(s / p)
within += s * _theil(xs)
return pd.Series({"total": between + within, "between": between, "within": within})
|