Lag features: prove each input existed at forecast time

Last updated: 7 Oct 20265 min read

tutorial

A forecasting feature is valid only if the production system can know its value at the prediction cutoff.

State the forecast origin

Suppose a staffing forecast is issued at 18:00 for tomorrow’s receipt count. Yesterday’s finalized count may be available, while today’s final count is not. Define the origin timestamp, target window and availability delay for every source. Calendar policy separates event time from ingestion time.

Build causal lags

A lag of seven days is a value observed seven calendar positions before the target; it is not the seventh previous nonmissing row. Reindex to the declared calendar first. Rolling means should exclude the target period and any recent period still incomplete at the origin. A shift after rolling can work, but inspect actual timestamps rather than trusting a pipeline name.

Treat external signals

A promotion plan may be known in advance; realized promotion clicks are not. A weather forecast available at issue time can be a feature, whereas realized weather for tomorrow leaks the answer period. Keep a version or availability timestamp for external values. Time-aware validation must replay those same feature availability rules.

Run a leakage test

Give a sequence with a sharp final spike and request a forecast before that spike occurred. Changing the spike must not change features for earlier origins. Also test a missing date, because a naive row shift can turn an eight-day-old observation into a supposed seven-day lag when one row is absent.

Implementation

def lag_seven_at_origin(values_by_day, ordered_days, origin_index):
    if not 0 <= origin_index < len(ordered_days):
        raise ValueError("invalid forecast origin")
    lag_index = origin_index - 7
    if lag_index < 0:
        return None
    return values_by_day.get(ordered_days[lag_index])

Performance and operating cost

A direct indexed lag lookup is O(1) after an ordered calendar is built; creating all L lags for D origins is O(DL) time and space if materialized. The hard constraint is temporal availability, which needs audit metadata rather than faster arithmetic.

Common Mistakes

Do not compute a rolling statistic that includes the target day.
Do not treat previous nonmissing row as a fixed calendar lag.
Do not train on realized external values unavailable at issue time.