Skip to content

reclassify_overcapacity

reclassify_overcapacity

reclassify_overcapacity(info: DataFrame, *, a3_ratio: float = A3_RATIO_THRESHOLD, n_min: int = 20) -> DataFrame

Relabel over-capacity systems as free_floating (the audit protocol's S3 step).

Sets station_type = "free_floating" on every station of a system whose overcapacity_ratio exceeds a3_ratio, so a subsequent audit_static flags A3 by the over-capacity mechanism rather than by the type a feed happens to declare. Returns a copy; the input is unchanged.

See Also

overcapacity_ratio : The ratio this thresholds. classify_from_virtual_station : Feed-intrinsic free-floating tag (spec signal). audit_static : The A1-A7 audit that consumes the relabelled types.

Examples:

>>> import pandas as pd
>>> info = pd.DataFrame({
...     "system_id": "ff", "station_id": [str(i) for i in range(20)],
...     "station_type": "docked_bike",
...     "capacity": [12.0] + [0.0] * 19,
... })
>>> reclassify_overcapacity(info)["station_type"].unique().tolist()
['free_floating']
Source code in src/gbfs_toolkit/audit/static.py
def reclassify_overcapacity(
    info: pd.DataFrame, *, a3_ratio: float = A3_RATIO_THRESHOLD, n_min: int = 20
) -> pd.DataFrame:
    """Relabel over-capacity systems as ``free_floating`` (the audit protocol's S3 step).

    Sets ``station_type = "free_floating"`` on every station of a system whose
    [`overcapacity_ratio`][gbfs_toolkit.overcapacity_ratio] exceeds ``a3_ratio``, so a subsequent
    [`audit_static`][gbfs_toolkit.audit_static] flags A3 by the over-capacity mechanism rather than by
    the type a feed happens to declare. Returns a copy; the input is unchanged.

    See Also
    --------
    [`overcapacity_ratio`][gbfs_toolkit.overcapacity_ratio] : The ratio this thresholds.
    [`classify_from_virtual_station`][gbfs_toolkit.classify_from_virtual_station] : Feed-intrinsic free-floating tag (spec signal).
    [`audit_static`][gbfs_toolkit.audit_static] : The A1-A7 audit that consumes the relabelled types.

    Examples
    --------
    >>> import pandas as pd
    >>> info = pd.DataFrame({
    ...     "system_id": "ff", "station_id": [str(i) for i in range(20)],
    ...     "station_type": "docked_bike",
    ...     "capacity": [12.0] + [0.0] * 19,
    ... })
    >>> reclassify_overcapacity(info)["station_type"].unique().tolist()
    ['free_floating']
    """
    ratio = overcapacity_ratio(info, n_min=n_min)
    over = set(ratio.index[ratio > a3_ratio])
    out = info.copy()
    out.loc[out["system_id"].isin(over), "station_type"] = "free_floating"
    return out