Join a status snapshot onto the station inventory: the analysis-ready availability frame.
A pure function on canonical frames (no feed object needed), so it works equally on live
data and on frames read back from a Parquet lake. Uses an outer join (operators
routinely add/drop a station from one endpoint mid-sync) with a presence indicator
(Categorical both / info_only / status_only) so orphaned rows stay visible
instead of being silently dropped.
Parameters:
| Name |
Type |
Description |
Default |
info
|
DataFrame
|
Canonical station information (STATION_INFO_COLUMNS).
|
required
|
status
|
DataFrame
|
Canonical station status (STATION_STATUS_COLUMNS).
|
required
|
See Also
occupancy : Occupancy ratio on the joined frame.
station_state : Classify each joined station.
system_profile : Summarise the joined snapshot.
Examples:
>>> import pandas as pd
>>> info = pd.DataFrame({"station_id": ["a", "b"], "capacity": [20, 10]})
>>> status = pd.DataFrame({"station_id": ["a"], "num_bikes_available": [5]})
>>> out = join_availability(info, status)
>>> out.sort_values("station_id")["presence"].tolist()
['both', 'info_only']
Source code in src/gbfs_toolkit/analytics/frames.py
| def join_availability(info: pd.DataFrame, status: pd.DataFrame) -> pd.DataFrame:
"""Join a status snapshot onto the station inventory: the analysis-ready availability frame.
A pure function on canonical frames (no feed object needed), so it works equally on live
data and on frames read back from a Parquet lake. Uses an **outer** join (operators
routinely add/drop a station from one endpoint mid-sync) with a ``presence`` indicator
(Categorical ``both`` / ``info_only`` / ``status_only``) so orphaned rows stay visible
instead of being silently dropped.
Parameters
----------
info : pandas.DataFrame
Canonical station information (`STATION_INFO_COLUMNS`).
status : pandas.DataFrame
Canonical station status (`STATION_STATUS_COLUMNS`).
See Also
--------
[`occupancy`][gbfs_toolkit.occupancy] : Occupancy ratio on the joined frame.
[`station_state`][gbfs_toolkit.station_state] : Classify each joined station.
[`system_profile`][gbfs_toolkit.system_profile] : Summarise the joined snapshot.
Examples
--------
>>> import pandas as pd
>>> info = pd.DataFrame({"station_id": ["a", "b"], "capacity": [20, 10]})
>>> status = pd.DataFrame({"station_id": ["a"], "num_bikes_available": [5]})
>>> out = join_availability(info, status)
>>> out.sort_values("station_id")["presence"].tolist()
['both', 'info_only']
"""
require_columns(info, ["station_id"], what="join_availability(info)")
require_columns(status, ["station_id"], what="join_availability(status)")
info_cols = info.drop(columns=["system_id"]) if "system_id" in info.columns else info
merged = status.merge(
info_cols, on="station_id", how="outer", suffixes=("", "_info"), indicator="presence"
)
mapped = merged["presence"].map(
{"both": "both", "left_only": "status_only", "right_only": "info_only"}
)
merged["presence"] = pd.Categorical(mapped, categories=list(PRESENCE_STATES))
return merged
|