Skip to content

aliasing_vulnerability

aliasing_vulnerability

aliasing_vulnerability(panel: DataFrame) -> DataFrame

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)