Skip to content

join_availability

join_availability

join_availability(info: DataFrame, status: DataFrame) -> 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:

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