Add utilization_rate = available bikes / station capacity.
Normalising by capacity makes stations and whole networks comparable: ten bikes in a 15-dock
station (67%) is not ten bikes in a 40-dock station (25%). This is the standard step before a
cross-city ANOVA or regression. Virtual or zero-capacity stations yield pd.NA rather than a
divide-by-zero.
Parameters:
| Name |
Type |
Description |
Default |
panel
|
DataFrame
|
Panel or snapshot with station_id and num_bikes_available (and capacity if
already present).
|
required
|
info
|
DataFrame
|
Canonical station inventory providing capacity (joined on the shared id columns) when
panel does not already carry it.
|
required
|
Returns:
| Type |
Description |
DataFrame
|
A copy of panel with a nullable utilization_rate column in [0, 1].
|
See Also
occupancy : Bikes / (bikes + docks) without capacity.
service_reliability_index : Level of service on the normalised panel.
Examples:
>>> import pandas as pd
>>> panel = pd.DataFrame({
... "system_id": "s", "station_id": ["a", "b"], "num_bikes_available": [10, 10]})
>>> info = pd.DataFrame({
... "system_id": "s", "station_id": ["a", "b"], "capacity": [15, 40]})
>>> [round(float(x), 2) for x in capacity_utilization(panel, info)["utilization_rate"]]
[0.67, 0.25]
Source code in src/gbfs_toolkit/analytics/service.py
| def capacity_utilization(panel: pd.DataFrame, info: pd.DataFrame) -> pd.DataFrame:
"""Add ``utilization_rate`` = available bikes / station capacity.
Normalising by capacity makes stations and whole networks comparable: ten bikes in a 15-dock
station (67%) is not ten bikes in a 40-dock station (25%). This is the standard step before a
cross-city ANOVA or regression. Virtual or zero-capacity stations yield ``pd.NA`` rather than a
divide-by-zero.
Parameters
----------
panel : pandas.DataFrame
Panel or snapshot with ``station_id`` and ``num_bikes_available`` (and ``capacity`` if
already present).
info : pandas.DataFrame
Canonical station inventory providing ``capacity`` (joined on the shared id columns) when
``panel`` does not already carry it.
Returns
-------
pandas.DataFrame
A copy of ``panel`` with a nullable ``utilization_rate`` column in ``[0, 1]``.
See Also
--------
[`occupancy`][gbfs_toolkit.occupancy] : Bikes / (bikes + docks) without capacity.
[`service_reliability_index`][gbfs_toolkit.service_reliability_index] : Level of service on the normalised panel.
Examples
--------
>>> import pandas as pd
>>> panel = pd.DataFrame({
... "system_id": "s", "station_id": ["a", "b"], "num_bikes_available": [10, 10]})
>>> info = pd.DataFrame({
... "system_id": "s", "station_id": ["a", "b"], "capacity": [15, 40]})
>>> [round(float(x), 2) for x in capacity_utilization(panel, info)["utilization_rate"]]
[0.67, 0.25]
"""
out = panel_frame(panel)
require_columns(out, ["station_id", "num_bikes_available"], what="capacity_utilization")
if "capacity" not in out.columns:
require_columns(info, ["station_id", "capacity"], what="capacity_utilization(info)")
keys = [k for k in ("system_id", "station_id") if k in out.columns and k in info.columns]
out = out.merge(info[[*keys, "capacity"]].drop_duplicates(keys), on=keys, how="left")
cap = pd.to_numeric(out["capacity"], errors="coerce")
bikes = pd.to_numeric(out["num_bikes_available"], errors="coerce")
out["utilization_rate"] = (bikes / cap.where(cap > 0)).astype("Float64")
return out
|