Skip to content

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 build_availability_panel or a flat frame with on_time.

required
exogenous DataFrame

External series with a timestamp column (exo_time, defaults to on_time).

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 NaN).

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]
Source code in src/gbfs_toolkit/analytics/temporal.py
def join_exogenous_timeseries(
    panel: pd.DataFrame,
    exogenous: pd.DataFrame,
    *,
    on_time: str = "fetched_at",
    exo_time: str | None = None,
    tolerance: str = "1h",
    direction: str = "nearest",
) -> pd.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
    ----------
    panel : pandas.DataFrame
        From [`build_availability_panel`][gbfs_toolkit.build_availability_panel] or a flat frame with ``on_time``.
    exogenous : pandas.DataFrame
        External series with a timestamp column (``exo_time``, defaults to ``on_time``).
    tolerance : str, default "1h"
        Maximum gap to match across (a pandas offset alias).
    direction : {"nearest", "backward", "forward"}, default "nearest"
        Which neighbouring exogenous record to attach.

    Returns
    -------
    pandas.DataFrame
        The flattened panel with the exogenous columns merged in (unmatched rows carry ``NaN``).

    See Also
    --------
    [`temporal_context_features`][gbfs_toolkit.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]
    """
    df = panel_frame(panel)
    exo_time = exo_time or on_time
    require_columns(df, [on_time], what="join_exogenous_timeseries")
    require_columns(exogenous, [exo_time], what="join_exogenous_timeseries(exogenous)")
    left = df.copy()
    right = exogenous.copy()
    left[on_time] = pd.to_datetime(left[on_time])
    right[exo_time] = pd.to_datetime(right[exo_time])
    left = left.sort_values(on_time)
    right = right.sort_values(exo_time)
    return pd.merge_asof(
        left,
        right,
        left_on=on_time,
        right_on=exo_time,
        tolerance=pd.Timedelta(tolerance),
        direction=direction,
    )