Skip to content

capacity_utilization

capacity_utilization

capacity_utilization(panel: DataFrame, info: DataFrame) -> 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:

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