Skip to content

resample_panel

resample_panel

resample_panel(panel: DataFrame, freq: str = '15min', *, time_col: str = 'fetched_at', by: tuple[str, ...] = ('system_id', 'station_id')) -> DataFrame

Resample each station series onto a fixed time grid, carrying the last state forward.

Availability is a step function (a station's count holds until the next change), so a panel polled at irregular instants must be aligned to a regular grid before clustering, correlation or plotting. Doing this per station with groupby().resample().ffill() is four brittle lines that routinely break nullable dtypes; this is the one-call, dtype-safe version. It carries the last observed state forward (it does not invent values), so it is alignment, not imputation.

Parameters:

Name Type Description Default
panel DataFrame

Panel/frame with the grouping columns in by and a time_col.

required
freq str

Target grid (a pandas offset alias).

"15min"
time_col str

Timestamp column.

"fetched_at"
by tuple of str

Grouping keys present in panel (missing keys are ignored).

("system_id", "station_id")

Returns:

Type Description
DataFrame

A flat panel on the freq grid, last-observation-carried-forward per group.

See Also

build_availability_panel : Read and resample a Parquet lake in one step. insert_explicit_gaps : Mark collection outages instead of filling them. extract_snapshot_asof : Take a single cross-section.

Examples:

>>> import pandas as pd
>>> panel = pd.DataFrame({
...     "station_id": "a",
...     "fetched_at": pd.to_datetime(["2026-01-01T00:00Z", "2026-01-01T00:30Z"]),
...     "num_bikes_available": [5, 8],
... })
>>> out = resample_panel(panel, "15min")
>>> out["num_bikes_available"].tolist()
[5, 5, 8]
Source code in src/gbfs_toolkit/io/timeseries.py
def resample_panel(
    panel: pd.DataFrame,
    freq: str = "15min",
    *,
    time_col: str = "fetched_at",
    by: tuple[str, ...] = ("system_id", "station_id"),
) -> pd.DataFrame:
    """Resample each station series onto a fixed time grid, carrying the last state forward.

    Availability is a step function (a station's count holds until the next change), so a
    panel polled at irregular instants must be aligned to a regular grid before clustering,
    correlation or plotting. Doing this per station with ``groupby().resample().ffill()``
    is four brittle lines that routinely break nullable dtypes; this is the one-call,
    dtype-safe version. It carries the last observed state forward (it does not invent
    values), so it is alignment, not imputation.

    Parameters
    ----------
    panel : pandas.DataFrame
        Panel/frame with the grouping columns in ``by`` and a ``time_col``.
    freq : str, default "15min"
        Target grid (a pandas offset alias).
    time_col : str, default "fetched_at"
        Timestamp column.
    by : tuple of str, default ("system_id", "station_id")
        Grouping keys present in ``panel`` (missing keys are ignored).

    Returns
    -------
    pandas.DataFrame
        A flat panel on the ``freq`` grid, last-observation-carried-forward per group.

    See Also
    --------
    [`build_availability_panel`][gbfs_toolkit.build_availability_panel] : Read and resample a Parquet lake in one step.
    [`insert_explicit_gaps`][gbfs_toolkit.insert_explicit_gaps] : Mark collection outages instead of filling them.
    [`extract_snapshot_asof`][gbfs_toolkit.extract_snapshot_asof] : Take a single cross-section.

    Examples
    --------
    >>> import pandas as pd
    >>> panel = pd.DataFrame({
    ...     "station_id": "a",
    ...     "fetched_at": pd.to_datetime(["2026-01-01T00:00Z", "2026-01-01T00:30Z"]),
    ...     "num_bikes_available": [5, 8],
    ... })
    >>> out = resample_panel(panel, "15min")
    >>> out["num_bikes_available"].tolist()
    [5, 5, 8]
    """
    df = panel_frame(panel)
    keys = [k for k in by if k in df.columns]
    require_columns(df, [*keys, time_col], what="resample_panel")
    out = df.copy()
    out[time_col] = pd.to_datetime(out[time_col], utc=True)
    if not keys:
        resampled = out.set_index(time_col).sort_index().resample(freq).ffill()
        return resampled.reset_index()
    parts = []
    for kv, g in out.groupby(keys, sort=False):
        block = g.drop(columns=keys).set_index(time_col).sort_index().resample(freq).ffill()
        block = block.reset_index()
        for key, value in zip(keys, kv if isinstance(kv, tuple) else (kv,), strict=True):
            block[key] = value
        parts.append(block)
    cols = [*keys, time_col, *[c for c in out.columns if c not in keys and c != time_col]]
    return pd.concat(parts, ignore_index=True)[cols]