How concentrated is capacity across stations? An equity / coverage lens.
Reports the Gini coefficient and Theil T index of value_col and the share held
by the top decile of stations (a system can claim wide coverage yet stash most bikes in a
few central hubs). Deliberately outside the published A1–A7 audit taxonomy; these are
descriptive metrics, not a feed-quality verdict. See lorenz_curve for the curve.
Returns:
| Type |
Description |
Series
|
n_stations, total_capacity, gini, theil, top_decile_share.
|
See Also
lorenz_curve : The curve behind these scalars.
theil_index : The decomposable Theil index alone.
palma_ratio : The tail-sensitive Palma ratio alone.
dynamic_gini_index : The same concentration over time.
Examples:
>>> import pandas as pd
>>> info = pd.DataFrame({"system_id": "s", "station_id": list("abcd"), "capacity": [10, 10, 10, 70]})
>>> round(float(concentration_metrics(info)["gini"]), 2)
0.45
Source code in src/gbfs_toolkit/analytics/distribution.py
| def concentration_metrics(info: pd.DataFrame, *, value_col: str = "capacity") -> pd.Series:
"""How concentrated is capacity across stations? An equity / coverage lens.
Reports the **Gini coefficient** and **Theil T index** of ``value_col`` and the share held
by the top decile of stations (a system can claim wide coverage yet stash most bikes in a
few central hubs). Deliberately *outside* the published A1–A7 audit taxonomy; these are
descriptive metrics, not a feed-quality verdict. See [`lorenz_curve`][gbfs_toolkit.lorenz_curve] for the curve.
Returns
-------
pandas.Series
``n_stations``, ``total_capacity``, ``gini``, ``theil``, ``top_decile_share``.
See Also
--------
[`lorenz_curve`][gbfs_toolkit.lorenz_curve] : The curve behind these scalars.
[`theil_index`][gbfs_toolkit.theil_index] : The decomposable Theil index alone.
[`palma_ratio`][gbfs_toolkit.palma_ratio] : The tail-sensitive Palma ratio alone.
[`dynamic_gini_index`][gbfs_toolkit.dynamic_gini_index] : The same concentration over time.
Examples
--------
>>> import pandas as pd
>>> info = pd.DataFrame({"system_id": "s", "station_id": list("abcd"), "capacity": [10, 10, 10, 70]})
>>> round(float(concentration_metrics(info)["gini"]), 2)
0.45
"""
require_columns(info, [value_col], what="concentration_metrics")
x = num(info, value_col).dropna().to_numpy()
x = np.sort(x[x > 0])
out: dict[str, float] = {"n_stations": int(x.size)}
if x.size == 0:
out["total_capacity"] = 0.0
out["gini"] = float("nan")
out["theil"] = float("nan")
out["top_decile_share"] = float("nan")
return pd.Series(out)
out["total_capacity"] = float(x.sum())
out["gini"] = round(gini(x), 4)
out["theil"] = round(_theil(x), 4)
k = max(1, int(np.ceil(0.1 * x.size)))
out["top_decile_share"] = round(float(x[-k:].sum() / x.sum()), 4)
return pd.Series(out)
|