Skip to content

censored_time_ratio

censored_time_ratio

censored_time_ratio(panel: DataFrame, *, bikes_col: str = 'num_bikes_available', docks_col: str = 'num_docks_available') -> Series

Fraction of station-time at a saturation boundary, where demand is unobservable.

When a station is empty (0 bikes) a would-be rider leaves no trace; when it is full (0 docks) a would-be returner leaves no trace. This reports the share of station-time in each censored state, and their union, as a measure of how much of the system's demand signal is lost to observation. It is strictly descriptive: it quantifies the observability gap and never infers the missing flows (that would be latent-demand imputation, out of scope).

Returns:

Type Description
Series

{empty_ratio, full_ratio, censored_ratio} where censored_ratio is the union (empty or full).

See Also

station_outage_rates : Per-station empty/full rates. service_reliability_index : Level-of-service probabilities.

Examples:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "num_bikes_available": [0, 5, 5, 10],
...     "num_docks_available": [10, 0, 5, 5],
... })
>>> float(censored_time_ratio(panel)["censored_ratio"])
0.5
Source code in src/gbfs_toolkit/analytics/service.py
def censored_time_ratio(
    panel: pd.DataFrame,
    *,
    bikes_col: str = "num_bikes_available",
    docks_col: str = "num_docks_available",
) -> pd.Series:
    """Fraction of station-time at a saturation boundary, where demand is unobservable.

    When a station is empty (0 bikes) a would-be rider leaves no trace; when it is
    full (0 docks) a would-be returner leaves no trace. This reports the share of
    station-time in each censored state, and their union, as a measure of how much of
    the system's demand signal is *lost to observation*. It is strictly descriptive:
    it quantifies the observability gap and never infers the missing flows (that would
    be latent-demand imputation, out of scope).

    Returns
    -------
    pandas.Series
        ``{empty_ratio, full_ratio, censored_ratio}`` where ``censored_ratio`` is the
        union (empty or full).

    See Also
    --------
    [`station_outage_rates`][gbfs_toolkit.station_outage_rates] : Per-station empty/full rates.
    [`service_reliability_index`][gbfs_toolkit.service_reliability_index] : Level-of-service probabilities.

    Examples
    --------
    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "num_bikes_available": [0, 5, 5, 10],
    ...     "num_docks_available": [10, 0, 5, 5],
    ... })
    >>> float(censored_time_ratio(panel)["censored_ratio"])
    0.5
    """
    require_columns(panel, [bikes_col, docks_col], what="censored_time_ratio")
    bikes = num(panel, bikes_col)
    docks = num(panel, docks_col)
    valid = bikes.notna() & docks.notna()
    if not valid.any():
        return pd.Series(
            {
                "empty_ratio": float("nan"),
                "full_ratio": float("nan"),
                "censored_ratio": float("nan"),
            }
        )
    empty = bikes[valid] <= 0
    full = docks[valid] <= 0
    return pd.Series(
        {
            "empty_ratio": float(empty.mean()),
            "full_ratio": float(full.mean()),
            "censored_ratio": float((empty | full).mean()),
        }
    )