Skip to content

dynamic_gini_index

dynamic_gini_index

dynamic_gini_index(panel: DataFrame, *, value_col: str = 'num_bikes_available', time_col: str = 'fetched_at', target_col: str | None = None) -> DataFrame

Gini coefficient of available bikes across stations, as a time series.

Capacity-based concentration (see concentration_metrics) measures a network's static design. This measures the dynamic inequality of where the bikes actually are: a system with evenly distributed capacity can still become deeply unequal at 18:00, when the fleet piles into one district. A rising curve over the day objectifies that loss of equity.

Parameters:

Name Type Description Default
panel DataFrame

From build_availability_panel or a flat frame with station_id, time_col and value_col.

required
value_col str

The per-station quantity whose distribution is measured.

"num_bikes_available"
time_col str

Snapshot timestamp.

"fetched_at"
target_col str

Deprecated alias for value_col (emits a FutureWarning).

None

Returns:

Type Description
DataFrame

<time_col>, gini, n_stations (one row per snapshot).

See Also

concentration_metrics : Static capacity concentration. temporal_concentration : The temporal (per-station) analogue. theil_index : A decomposable inequality scalar.

Examples:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "station_id": ["a", "b", "a", "b"],
...     "fetched_at": pd.to_datetime(
...         ["2026-01-01T08:00Z"] * 2 + ["2026-01-01T18:00Z"] * 2),
...     "num_bikes_available": [5, 5, 10, 0],
... })
>>> out = dynamic_gini_index(panel)
>>> bool(out["gini"].iloc[0] < out["gini"].iloc[1])
True
Source code in src/gbfs_toolkit/analytics/distribution.py
def dynamic_gini_index(
    panel: pd.DataFrame,
    *,
    value_col: str = "num_bikes_available",
    time_col: str = "fetched_at",
    target_col: str | None = None,
) -> pd.DataFrame:
    """Gini coefficient of available bikes across stations, as a time series.

    Capacity-based concentration (see [`concentration_metrics`][gbfs_toolkit.concentration_metrics]) measures a network's static
    design. This measures the *dynamic* inequality of where the bikes actually are: a system with
    evenly distributed capacity can still become deeply unequal at 18:00, when the fleet piles into
    one district. A rising curve over the day objectifies that loss of equity.

    Parameters
    ----------
    panel : pandas.DataFrame
        From [`build_availability_panel`][gbfs_toolkit.build_availability_panel] or a flat frame with ``station_id``, ``time_col`` and
        ``value_col``.
    value_col : str, default "num_bikes_available"
        The per-station quantity whose distribution is measured.
    time_col : str, default "fetched_at"
        Snapshot timestamp.
    target_col : str, optional
        Deprecated alias for ``value_col`` (emits a ``FutureWarning``).

    Returns
    -------
    pandas.DataFrame
        ``<time_col>, gini, n_stations`` (one row per snapshot).

    See Also
    --------
    [`concentration_metrics`][gbfs_toolkit.concentration_metrics] : Static capacity concentration.
    [`temporal_concentration`][gbfs_toolkit.temporal_concentration] : The temporal (per-station) analogue.
    [`theil_index`][gbfs_toolkit.theil_index] : A decomposable inequality scalar.

    Examples
    --------
    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "station_id": ["a", "b", "a", "b"],
    ...     "fetched_at": pd.to_datetime(
    ...         ["2026-01-01T08:00Z"] * 2 + ["2026-01-01T18:00Z"] * 2),
    ...     "num_bikes_available": [5, 5, 10, 0],
    ... })
    >>> out = dynamic_gini_index(panel)
    >>> bool(out["gini"].iloc[0] < out["gini"].iloc[1])
    True
    """
    if target_col is not None:
        value_col = deprecated_kwarg(target_col, old="target_col", new="value_col")
    df = panel_frame(panel)
    require_columns(df, [time_col, value_col], what="dynamic_gini_index")
    vals = pd.to_numeric(df[value_col], errors="coerce")
    rows = []
    for t, idx in df.groupby(time_col, sort=True).groups.items():
        v = vals.loc[idx].dropna().to_numpy()
        rows.append({time_col: t, "gini": gini(v), "n_stations": int(v.size)})
    return pd.DataFrame(rows)