extract_snapshot_asof¶
extract_snapshot_asof
¶
extract_snapshot_asof(panel: DataFrame, target_time: str | Timestamp, *, tolerance: str = '10min', time_col: str = 'fetched_at', by: tuple[str, ...] = ('system_id', 'station_id')) -> DataFrame
Extract the city's state at one instant: each station's last reading at or before T.
Stations answer at slightly different seconds, so "the state at 08:00" is not a clean
slice. This returns, per station, the most recent observation in
[target_time - tolerance, target_time], the cross-section a snapshot map or a
point-in-time comparison needs, without a hand-rolled merge_asof.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
panel
|
DataFrame
|
Panel/frame with the grouping columns in |
required |
target_time
|
str or Timestamp
|
The instant to reconstruct (naive is read as UTC). |
required |
tolerance
|
str
|
How far before |
"10min"
|
time_col
|
see [`resample_panel`][gbfs_toolkit.resample_panel].
|
|
'fetched_at'
|
by
|
see [`resample_panel`][gbfs_toolkit.resample_panel].
|
|
'fetched_at'
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
One row per group: its latest reading within the window (empty if none qualify). |
See Also
resample_panel : Align the whole panel to a grid instead.
to_wide_matrix : Pivot the panel to a station-by-time matrix.
Examples:
>>> import pandas as pd
>>> panel = pd.DataFrame({
... "station_id": ["a", "a", "b"],
... "fetched_at": pd.to_datetime(
... ["2026-01-01T07:59Z", "2026-01-01T08:30Z", "2026-01-01T08:00Z"]),
... "num_bikes_available": [3, 9, 7],
... })
>>> snap = extract_snapshot_asof(panel, "2026-01-01T08:00Z").set_index("station_id")
>>> int(snap.loc["a", "num_bikes_available"])
3