Skip to content

lorenz_curve

lorenz_curve

lorenz_curve(info: DataFrame, *, value_col: str = 'capacity') -> DataFrame

Lorenz-curve points for plotting capacity inequality.

Returns the cumulative share of stations vs. cumulative share of value_col, starting at the origin (0, 0). The diagonal is perfect equality; the area between it and the curve is half the Gini. Pairs with concentration_metrics.

Returns:

Type Description
DataFrame

cum_population_share, cum_value_share (both in [0, 1], ascending).

See Also

concentration_metrics : The Gini/Theil scalars summarising this curve. theil_index : A decomposable inequality scalar.

Examples:

>>> import pandas as pd
>>> info = pd.DataFrame({"system_id": "s", "station_id": list("abcd"), "capacity": [10, 10, 10, 70]})
>>> lorenz_curve(info)["cum_value_share"].tolist()
[0.0, 0.1, 0.2, 0.3, 1.0]
Source code in src/gbfs_toolkit/analytics/distribution.py
def lorenz_curve(info: pd.DataFrame, *, value_col: str = "capacity") -> pd.DataFrame:
    """Lorenz-curve points for plotting capacity inequality.

    Returns the cumulative share of stations vs. cumulative share of ``value_col``, starting
    at the origin ``(0, 0)``. The diagonal is perfect equality; the area between it and the
    curve is half the Gini. Pairs with [`concentration_metrics`][gbfs_toolkit.concentration_metrics].

    Returns
    -------
    pandas.DataFrame
        ``cum_population_share``, ``cum_value_share`` (both in ``[0, 1]``, ascending).

    See Also
    --------
    [`concentration_metrics`][gbfs_toolkit.concentration_metrics] : The Gini/Theil scalars summarising this curve.
    [`theil_index`][gbfs_toolkit.theil_index] : A decomposable inequality scalar.

    Examples
    --------
    >>> import pandas as pd
    >>> info = pd.DataFrame({"system_id": "s", "station_id": list("abcd"), "capacity": [10, 10, 10, 70]})
    >>> lorenz_curve(info)["cum_value_share"].tolist()
    [0.0, 0.1, 0.2, 0.3, 1.0]
    """
    require_columns(info, [value_col], what="lorenz_curve")
    x = num(info, value_col).dropna().to_numpy()
    x = np.sort(x[x > 0])
    if x.size == 0:
        return pd.DataFrame({"cum_population_share": [0.0], "cum_value_share": [0.0]})
    cum_pop = np.arange(1, x.size + 1) / x.size
    cum_val = np.cumsum(x) / x.sum()
    return pd.DataFrame(
        {
            "cum_population_share": np.concatenate([[0.0], cum_pop]),
            "cum_value_share": np.concatenate([[0.0], cum_val]),
        }
    )