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)
|