Skip to content

overcapacity_ratio

overcapacity_ratio

overcapacity_ratio(info: DataFrame, *, n_min: int = 20) -> Series

Per-system A3 over-capacity ratio from declared station capacity.

A free-floating fleet that advertises virtual stations reports a capacity profile by conditional averaging over currently-occupied anchors, which overstates the physical dock count. The signature (Fossé & Pallares) compares that conditional mean to the unconditional mean::

ratio = mean(c_i : c_i > 0) / (sum(c_i, NaN as 0) / N)

A genuine docked network sits near 1; a conditionally-averaged free-floating fleet trips ratio >> 1. Computed from station_information alone (no realised-capacity status needed).

Parameters:

Name Type Description Default
info DataFrame

Canonical station information; requires system_id and capacity.

required
n_min int

Systems with fewer than n_min stations return NaN (ratio not meaningful on a tiny inventory).

20

Returns:

Type Description
Series

The ratio indexed by system_id (NaN where undefined).

See Also

reclassify_overcapacity : Relabel the systems this ratio flags as free-floating. capacity_convention : Classify the capacity-field semantics behind the ratio. audit_static : Run the full A1-A7 audit, of which A3 uses this mechanism.

Examples:

A free-floating fleet of 20 anchors, one currently occupied (capacity 12), nineteen empty (capacity 0), trips a high ratio:

>>> import pandas as pd
>>> info = pd.DataFrame({
...     "system_id": "ff", "station_id": [str(i) for i in range(20)],
...     "capacity": [12.0] + [0.0] * 19,
... })
>>> round(float(overcapacity_ratio(info)["ff"]), 1)
20.0
Source code in src/gbfs_toolkit/audit/static.py
def overcapacity_ratio(info: pd.DataFrame, *, n_min: int = 20) -> pd.Series:
    """Per-system A3 over-capacity ratio from declared station capacity.

    A free-floating fleet that advertises virtual stations reports a capacity
    profile by *conditional averaging* over currently-occupied anchors, which
    overstates the physical dock count. The signature (Fossé & Pallares) compares
    that conditional mean to the unconditional mean::

        ratio = mean(c_i : c_i > 0) / (sum(c_i, NaN as 0) / N)

    A genuine docked network sits near ``1``; a conditionally-averaged
    free-floating fleet trips ``ratio >> 1``. Computed from
    ``station_information`` alone (no realised-capacity status needed).

    Parameters
    ----------
    info : pandas.DataFrame
        Canonical station information; requires ``system_id`` and ``capacity``.
    n_min : int, default 20
        Systems with fewer than ``n_min`` stations return ``NaN`` (ratio not
        meaningful on a tiny inventory).

    Returns
    -------
    pandas.Series
        The ratio indexed by ``system_id`` (``NaN`` where undefined).

    See Also
    --------
    [`reclassify_overcapacity`][gbfs_toolkit.reclassify_overcapacity] : Relabel the systems this ratio flags as free-floating.
    [`capacity_convention`][gbfs_toolkit.capacity_convention] : Classify the capacity-field semantics behind the ratio.
    [`audit_static`][gbfs_toolkit.audit_static] : Run the full A1-A7 audit, of which A3 uses this mechanism.

    Examples
    --------
    A free-floating fleet of 20 anchors, one currently occupied (capacity 12),
    nineteen empty (capacity 0), trips a high ratio:

    >>> import pandas as pd
    >>> info = pd.DataFrame({
    ...     "system_id": "ff", "station_id": [str(i) for i in range(20)],
    ...     "capacity": [12.0] + [0.0] * 19,
    ... })
    >>> round(float(overcapacity_ratio(info)["ff"]), 1)
    20.0
    """
    require_columns(info, ["system_id", "capacity"], what="overcapacity_ratio")

    def _ratio(cap: pd.Series) -> float:
        c = cap.to_numpy(dtype="float64")
        n = c.size
        if n < n_min:
            return float("nan")
        positive = c[np.isfinite(c) & (c > 0)]
        if positive.size == 0:
            return float("nan")
        c_profile = float(positive.mean())
        c_actual = float(np.where(np.isnan(c), 0.0, c).sum() / n)
        if c_actual <= 0:
            return float("nan")
        return c_profile / c_actual

    return info.groupby("system_id")["capacity"].apply(_ratio)