Skip to content

occupancy

occupancy

occupancy(availability: DataFrame) -> 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 : 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")