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()),
}
)
|