Forecasting & uncertainty

Grid forecast

The next k values, with optional calibrated intervals.

The everyday forecast: from your recent history, predict the next k points on the same time grid. Add return_intervals='conformal' when you want a calibrated range to plan against instead of a single line.

model = APDTFlowForecaster(forecast_horizon=24)
model.fit(df, target_col='sales')

yhat = model.predict()                                   # next 24 steps
lower, yhat, upper = model.predict(return_intervals='conformal', alpha=0.1)

Forecast at any moment

Query arbitrary real-valued times — fractional steps, between observations, beyond the horizon.

Most models only score the fixed steps they trained on. APDTFlow integrates a continuous-time ODE, so you can ask for the value 3.6 steps out, at a timestamp that falls between samples, or past the trained horizon — useful for irregular reporting dates or "what will it be at 2pm Friday?".

model = APDTFlowForecaster(forecast_horizon=14, decoder_type='continuous',
                           use_conformal=True)
model.fit(df, target_col='value', date_col='date')

values, lower, upper = model.predict_at([3.5, 7.2, 18.0])

ℹ Enabled by decoder_type='continuous'.

When will it cross the line?

A calibrated time window on the crossing, plus an act_by edge to schedule against.

Flip the question from "what value" to "when does it reach this level". You get a point estimate (eta), a calibrated 90% window for the crossing time, and act_by — the early edge of that window — which is the number you actually schedule against. Use mode='risk' for the earliest plausible crossing when being early is safer than being exact.

r = model.predict_when(threshold=80, direction='above', alpha=0.1)
r.eta                 # point estimate (steps ahead)
r.earliest, r.latest  # calibrated 90% window
r.act_by              # schedule by this edge
r.censored            # True if no crossing within the horizon

# earliest plausible crossing, for safety-critical scheduling:
risk = model.predict_when(80, direction='above', mode='risk')

ℹ Enabled by decoder_type='continuous' + use_conformal=True.

Schedule a whole fleet

Turn a dict of asset histories into a maintenance schedule sorted by act-by date.

Apply predict_when across many assets in one call. The returned table is sorted by act_by, so whatever needs attention soonest sits at the top — ready to hand to a maintenance/CMMS system as CSV.

schedule = model.predict_when_fleet(assets, threshold=1.4, direction='below')
# DataFrame: asset_id, eta, earliest, latest, act_by, censored, confidence
schedule.to_csv('maintenance_schedule.csv')

Conformal intervals

Split and adaptive conformal calibration on every forecast.

Conformal prediction wraps a point forecast in an interval whose coverage you can verify on held-out data — split conformal is fast, adaptive adjusts as the distribution shifts. Switch it on at construction and predict() can hand back calibrated lower/upper bands.

model = APDTFlowForecaster(use_conformal=True, conformal_method='split')
model.fit(df, target_col='y')

lower, yhat, upper = model.predict(return_intervals='conformal', alpha=0.1)

Calibrated event-time windows

predict_when calibrates in time space, so its 90% windows actually hold.

For predict_when the window is calibrated on crossing-time errors in time space rather than on value bands — that is what keeps the 90% window honest. act_by is exposed as a first-class field so scheduling never rides on the (often optimistic) point estimate.