Per-station risk that the polling cadence misses short-timescale dynamics.
A diagnostic for the polling Nyquist limit (see calculate_net_flow). For each station
it measures how often consecutive non-zero net-flow steps reverse sign: frequent reversals at
the sampling scale signal even faster reversals (rent-and-return round trips) being aliased
away. Report it to justify, or caution against, a chosen polling cadence in a study.
Returns:
| Type |
Description |
DataFrame
|
system_id, station_id, high_frequency_loss_risk (the sign-reversal rate in [0, 1],
NaN when there are too few moves) and n_intervals.
|
See Also
calculate_net_flow : The flow whose sampling limit this probes.
fleet_turnover_proxy : The turnover proxy this cautions about.
Examples:
>>> import pandas as pd
>>> panel = pd.DataFrame({
... "system_id": "s", "station_id": "a",
... "fetched_at": pd.to_datetime(
... ["2026-01-01T08:00Z", "2026-01-01T09:00Z", "2026-01-01T10:00Z"]),
... "num_bikes_available": [10, 7, 9],
... })
>>> float(aliasing_vulnerability(panel)["high_frequency_loss_risk"].iloc[0])
1.0
Source code in src/gbfs_toolkit/analytics/dynamics.py
| def aliasing_vulnerability(panel: pd.DataFrame) -> pd.DataFrame:
"""Per-station risk that the polling cadence misses short-timescale dynamics.
A diagnostic for the polling Nyquist limit (see [`calculate_net_flow`][gbfs_toolkit.calculate_net_flow]). For each station
it measures how often consecutive non-zero net-flow steps reverse sign: frequent reversals at
the sampling scale signal even faster reversals (rent-and-return round trips) being aliased
away. Report it to justify, or caution against, a chosen polling cadence in a study.
Returns
-------
pandas.DataFrame
``system_id, station_id, high_frequency_loss_risk`` (the sign-reversal rate in ``[0, 1]``,
``NaN`` when there are too few moves) and ``n_intervals``.
See Also
--------
[`calculate_net_flow`][gbfs_toolkit.calculate_net_flow] : The flow whose sampling limit this probes.
[`fleet_turnover_proxy`][gbfs_toolkit.fleet_turnover_proxy] : The turnover proxy this cautions about.
Examples
--------
>>> import pandas as pd
>>> panel = pd.DataFrame({
... "system_id": "s", "station_id": "a",
... "fetched_at": pd.to_datetime(
... ["2026-01-01T08:00Z", "2026-01-01T09:00Z", "2026-01-01T10:00Z"]),
... "num_bikes_available": [10, 7, 9],
... })
>>> float(aliasing_vulnerability(panel)["high_frequency_loss_risk"].iloc[0])
1.0
"""
flow = calculate_net_flow(panel).dropna(subset=["net_flow"])
rows = []
for (sid, stid), g in flow.groupby(["system_id", "station_id"], sort=False):
nf = g["net_flow"].to_numpy()
nonzero = nf[nf != 0]
if len(nonzero) < 2:
rate = np.nan
else:
signs = np.sign(nonzero)
rate = float((signs[1:] != signs[:-1]).sum()) / (len(nonzero) - 1)
rows.append(
{
"system_id": sid,
"station_id": stid,
"high_frequency_loss_risk": rate,
"n_intervals": int(len(nf)),
}
)
return pd.DataFrame(rows)
|