Skip to content

theil_index

theil_index

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:

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})