insert_explicit_gaps¶
insert_explicit_gaps
¶
insert_explicit_gaps(panel: DataFrame, *, expected_freq: str = '5min', tolerance: str = '15min', time_col: str = 'fetched_at', by: tuple[str, ...] = ('system_id', 'station_id')) -> DataFrame
Insert NaN rows where collection stalled, so plots show the outage honestly.
When a scraper dies on Friday and resumes Monday, a line plot draws a misleading
straight segment across the gap. Inserting an explicit NaN row in each gap longer
than tolerance forces a visual break (and stops rolling statistics bridging the
hole). Purely descriptive: it makes missingness explicit, it does not fill it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
panel
|
DataFrame
|
Panel/frame with the grouping columns in |
required |
expected_freq
|
str
|
The intended cadence (documented for intent; the test is against |
"5min"
|
tolerance
|
str
|
Gaps strictly larger than this get a |
"15min"
|
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
|
A flat copy of |
See Also
coverage_report : Quantify the same gaps numerically.
resample_panel : Carry state across gaps instead of marking them.
Examples:
>>> import pandas as pd
>>> panel = pd.DataFrame({
... "station_id": "a",
... "fetched_at": pd.to_datetime(
... ["2026-01-01T00:00Z", "2026-01-01T00:05Z", "2026-01-01T02:00Z"]),
... "num_bikes_available": [5, 4, 6],
... })
>>> out = insert_explicit_gaps(panel)
>>> len(out), int(out["num_bikes_available"].isna().sum())
(4, 1)