Occupancy ratio: bikes / (bikes + docks) per station.
The quantity everyone recomputes by hand. Returns NaN where there are no bikes and
no docks (a virtual/dead station), so the divide-by-zero is handled once, consistently.
See Also
station_state : A categorical state instead of a ratio.
system_profile : The system-wide occupancy summary.
capacity_utilization : Occupancy normalised by capacity.
Examples:
>>> import pandas as pd
>>> from gbfs_toolkit import occupancy
>>> av = pd.DataFrame({"num_bikes_available": [3, 0], "num_docks_available": [1, 0]})
>>> occupancy(av).round(2).tolist()
[0.75, nan]
Source code in src/gbfs_toolkit/analytics/frames.py
| def occupancy(availability: pd.DataFrame) -> pd.Series:
"""Occupancy ratio: bikes / (bikes + docks) per station.
The quantity everyone recomputes by hand. Returns ``NaN`` where there are no bikes *and*
no docks (a virtual/dead station), so the divide-by-zero is handled once, consistently.
See Also
--------
[`station_state`][gbfs_toolkit.station_state] : A categorical state instead of a ratio.
[`system_profile`][gbfs_toolkit.system_profile] : The system-wide occupancy summary.
[`capacity_utilization`][gbfs_toolkit.capacity_utilization] : Occupancy normalised by capacity.
Examples
--------
>>> import pandas as pd
>>> from gbfs_toolkit import occupancy
>>> av = pd.DataFrame({"num_bikes_available": [3, 0], "num_docks_available": [1, 0]})
>>> occupancy(av).round(2).tolist()
[0.75, nan]
"""
require_columns(availability, ["num_bikes_available", "num_docks_available"], what="occupancy")
bikes = pd.to_numeric(availability["num_bikes_available"], errors="coerce")
docks = pd.to_numeric(availability["num_docks_available"], errors="coerce")
denom = bikes + docks
return (bikes / denom).where(denom > 0).rename("occupancy")
|