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