Skip to content

concentration_metrics

concentration_metrics

concentration_metrics(info: DataFrame, *, value_col: str = 'capacity') -> 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 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)