join_exogenous_timeseries¶
join_exogenous_timeseries
¶
join_exogenous_timeseries(panel: DataFrame, exogenous: DataFrame, *, on_time: str = 'fetched_at', exo_time: str | None = None, tolerance: str = '1h', direction: str = 'nearest') -> DataFrame
Align an external time series (weather, traffic, air quality) onto the panel.
Almost every cycling-usage study correlates demand with weather. Doing the time alignment by
hand (unequal cadences, clock offsets, time zones) is a frequent source of methodological error.
This wraps merge_asof to attach each exogenous record to the nearest panel
timestamp within tolerance, safely. No network calls: bring your own exogenous frame.
Both timestamp columns must share time-zone awareness (both tz-aware, ideally UTC, or both
naive); convert first otherwise, since merge_asof will not mix them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
panel
|
DataFrame
|
From |
required |
exogenous
|
DataFrame
|
External series with a timestamp column ( |
required |
tolerance
|
str
|
Maximum gap to match across (a pandas offset alias). |
"1h"
|
direction
|
('nearest', 'backward', 'forward')
|
Which neighbouring exogenous record to attach. |
"nearest"
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
The flattened panel with the exogenous columns merged in (unmatched rows carry |
See Also
temporal_context_features : Add calendar context columns.
Examples:
>>> import pandas as pd
>>> panel = pd.DataFrame({
... "station_id": "a",
... "fetched_at": pd.to_datetime(["2026-01-01T08:00Z", "2026-01-01T09:00Z"]),
... "num_bikes_available": [5, 3],
... })
>>> weather = pd.DataFrame({
... "fetched_at": pd.to_datetime(["2026-01-01T08:05Z", "2026-01-01T09:10Z"]),
... "temp_c": [4.0, 6.0],
... })
>>> join_exogenous_timeseries(panel, weather)["temp_c"].tolist()
[4.0, 6.0]