Forecasting Models

These guides explain the forecasting model classes. Use this section when you need to pick, configure, or compare a model. Use Forecasting when you need ForecastFrame, rolling-origin backtesting, artifacts, CLI workflows, or shared evidence rules.

Start with seasonal naive. Add the simplest model that represents a pattern you actually see—trend, autocorrelation, intermittent demand, shared panel lags, spatial proximity, or graph flow—and compare it on the same rolling origins.

Try Models In The Browser

Forecast modelCartoBoost AutoForecastCartoBoost LagCartoBoost DirectRectified RecursiveLag PlusScaled CartoBoost LagLog1p CartoBoost LagNeural PanelClassical Expert BankAutoStats BankIntermittent DemandCrostonSBATSBSTL + ARIMAMSTL + ARIMASeasonal NaiveWindow AverageSeasonal Window AverageThetaAuto ETSETSSeasonal ETSAuto ARIMAARIMAKalmanLocal Level KalmanAuto KalmanAuto Local Level KalmanPiecewise Linear SeasonalKrigingSpatial Piecewise KrigingOptimized ThetaNaive

Choose any forecast model and run the same route-demand example.

This control reads the available model list and runs the selected model against a bundled taxi-style coordinate panel sample.

Choose A Model

Model guide	Best first use	Notes
Naive And Seasonal Naive	Establish transparent last-value and last-season baselines.	Start here for every forecast comparison.
Theta	Extrapolate level and trend with a lightweight deterministic model.	Includes manual and optimized theta examples.
ETS	Model additive level, trend, and seasonality.	Useful when the series has smooth components and repeatable seasonal structure.
ARIMA And AutoARIMA	Use differencing and autocorrelation in a bounded search.	Covers fixed-order ARIMA, AutoARIMA candidate selection, visual smoke checks, and benchmark notes.
Kalman	Track noisy local level and local trend over time.	Includes state diagnostics and visualization examples.
Piecewise Linear Seasonal	Fit interpretable trend, changepoint, seasonality, event, and regressor components.	Includes an interactive example for piecewise_linear_seasonal.
Kriging	Borrow signal across nearby coordinates.	Useful for coordinate-aware panel forecasting.
Spatial Piecewise Kriging	Combine interpretable temporal components with spatial borrowing.	Includes an interactive coordinate-panel example for spatial_piecewise_kriging.
CartoBoost Lag	Learn one supervised lag model across many related series.	Use when many aligned panels should share lag structure.
Graph Spatiotemporal Forecasting	Forecast sensor, route, road, or zone-flow panels on a directed graph.	Use when upstream/downstream graph structure should improve forecasts beyond panel-only baselines.
Market Structure Forecasting	Learn sparse directional relationships with hierarchy-aware smoothing and analyst-visible kernels.	Use when distance alone misses connected market structure and reviewers need shift explanations.
Probabilistic And Conformal	Add calibrated uncertainty to regressors, spatial models, residual hybrids, and forecasts.	Use when interval coverage and width matter alongside point accuracy.
N-BEATS And N-HiTS	Fit deterministic neural window experts for regular forecast windows.	Use as neural baselines against seasonal naive, local statistical models, and CartoBoostLagForecaster.
Neural Panel	Fit a neural panel forecaster with direct multi-horizon output for related series.	Includes an interactive example for neural_panel.
AutoStatsBank	Validate a deterministic statistical expert bank.	Useful when a local statistical selector is the model being tested.
Intermittent Demand	Forecast sparse non-negative demand with fixed Croston, SBA, or TSB methods.	Use when zeros are meaningful demand periods rather than missing rows.
Croston	Fit the basic Croston decomposition for sparse non-negative demand.	Includes an interactive example for croston.
SBA	Fit the Syntetos-Boylan bias-adjusted Croston method.	Includes an interactive example for sba.
TSB	Smooth demand size and occurrence probability separately.	Includes an interactive example for tsb.
AutoForecaster	Use the guarded default selector over lag, direct, residual-corrected, intermittent, and classical candidates.	Includes diagrams for validation, gating, prediction, and metadata inspection.
Weighted Ensembles	Combine fitted forecasters with explicit weights.	Components and weights must be named explicitly.

Match The Model To The Pattern

Choose the model whose assumptions match the signal you can defend:

Signal in the series	First model to try	Why
The latest observed level is the best short-horizon summary.	Naive	Tests whether any model adds information beyond persistence.
The same hour yesterday or same weekday last week dominates.	Seasonal naive	Tests repeatable seasonality without estimated parameters.
Level and trend are smooth, with optional simple seasonality.	Theta or ETS	Estimates a low-dimensional local structure that is easy to inspect.
Recent autocorrelation and differencing explain the series.	ARIMA or AutoARIMA	Models local serial dependence after bounded non-seasonal differencing.
The measured series is noisy and the latent level/trend should update gradually.	Kalman	Separates observation noise from latent state movement.
You need interpretable changepoints, Fourier seasonalities, event windows, known future regressors, quantiles, and component decomposition in one local model.	Piecewise linear seasonal	Estimates additive or multiplicative component paths and keeps the result inspectable.
You need a forecast figure that matches Prophet's plotting surface for a Prophet-shaped result.	Plotting	Uses the same observed-point, forecast-line, capacity, floor, interval, axis, and legend behavior as prophet.plot.plot.
Nearby zones, route midpoints, or residual surfaces should be spatially related.	Kriging	Uses coordinate distance and a variogram to borrow cross-series signal.
Panels have both temporal changepoints and spatial residual structure.	Spatial Piecewise Kriging	Separates the temporal forecast, spatial correction, kriging variance, neighbors, metadata, and components so the spatial claim can be checked.
Many related series share lag, rolling, calendar, or trend structure.	CartoBoost lag	Learns one supervised model from many aligned panel examples.
Roads, lanes, sensors, or zone flows diffuse over a directed graph.	Graph spatiotemporal forecasting	Applies diffusion convolution over directed CSR adjacency and reports horizon, node, and graph-distance errors.
Geo model quality must include calibrated uncertainty.	Probabilistic and conformal models	Separates base fitting from calibration and reports coverage, width, PIT bins, horizon/block coverage, and residual Moran's I.
Fixed regular windows should be tested with a compact neural expert.	N-BEATS or N-HiTS	Provides deterministic neural baselines for direct window learning before moving to richer panel or graph models.
Directional series need direct multi-horizon neural forecasts with id direction preserved.	Neural Panel	Builds leak-free lag windows from ForecastFrame, keeps directional ids distinct, injects generated lane embedding/graph covariates, and stores component, normalization, quantile, series-id, and train-cutoff metadata.
Pickup demand is sparse with many true zero periods.	Croston, SBA, or TSB	Uses intermittent-demand smoothing instead of generic trend extrapolation.
A local statistical bank should choose among reusable non-benchmark candidates.	AutoStatsBank	Runs validation over a deterministic statistical expert bank.
A production panel needs a deterministic guarded default with auditable candidate weights.	AutoForecaster	Validates a fixed roster, protects the lag baseline, and stores global, horizon, and series weights.
Validated models capture complementary errors.	Weighted ensemble	Averages explicit components after each member proves useful.

Do not choose a richer model only because it is available. Be explicit about the pattern it is meant to capture, what it ignores, and whether it improves a time-ordered holdout enough to justify extra complexity.

Shared Input Patterns

For quick checks, local forecasters can fit a plain numeric sequence:

from cartoboost.forecasting import SeasonalNaiveForecaster

model = SeasonalNaiveForecaster(season_length=24)
model.fit(zone_hourly_counts)
forecast = model.predict(12)

For production demand or time-series workflows, prefer a validated ForecastFrame:

from cartoboost.forecasting import ForecastFrame

frame = ForecastFrame.from_pandas(
    hourly_zone_demand,
    timestamp_col="timestamp",
    target_col="demand",
    series_id_col="zone_id",
    freq="h",
)

ForecastFrame validates timestamps, duplicate rows within each series, finite targets by default, regular frequency, panel ids, and covariate role metadata. Use allow_missing_targets=True only when missing target rows represent known calendar slots that should be skipped during fitting while still anchoring the future schedule after the latest input timestamp. This Prophet-style behavior is supported by PiecewiseLinearSeasonalForecaster, NaiveForecaster, and non-seasonal window averages; models that require dense regular targets reject missing targets with a clear error.

Use allow_missing_covariates=True when declared covariate columns contain NaN values and you want each model to validate only the covariates it actually uses. Infinite covariates are always rejected. Models that consume a missing covariate still fail clearly at fit or predict time.

Additional Models

AutoStatsBank is a public wrapper for the reusable statistical expert bank. AutoForecaster also considers direct, rectified-recursive, intermittent, classical, and decomposition-style candidates. Use the dedicated guide pages for the model-specific use cases:

• Piecewise Linear Seasonal
• N-BEATS And N-HiTS
• Neural Panel
• Graph Spatiotemporal Forecasting
• Spatial Piecewise Kriging

The browser roster also exposes stl_cartoboost and mstl_cartoboost. These models use LOESS-based STL decomposition, fit their downstream model to the seasonally adjusted target, and repeat the final fitted seasonal cycle when reseasoning. STL needs two complete cycles of its configured period; MSTL needs two complete cycles of every configured period.

Keep benchmark-specific candidate names and scoring labels in benchmark harnesses and reports.

Shared Result Shape

Forecasting models return a ForecastResult object. Use predictions() for row tuples:

forecast = model.predict(3)
rows = forecast.predictions()

for series_id, timestamp, horizon, model_name, mean in rows:
    print(series_id, timestamp, horizon, model_name, mean)

The tuple columns are also available from forecast.columns(). Use forecast.to_json() for portable artifact roundtrips and downstream reporting.

Validation Order

For forecast claims, compare models under the same rolling-origin split:

1. Start with naive and seasonal naive baselines.
2. Add a local model that matches the series structure, such as theta, ETS, ARIMA, or Kalman.
3. Use CartoBoostLagForecaster when many related series should share lag, rolling, calendar, or trend features.
4. Use kriging when stable coordinates are part of the forecast signal.
5. Use weighted ensembles only after component models have been validated.

Report RMSE, MAE, horizon, split dates, training time, prediction time, model settings, sample size, and whether the input data is real, generated acceptance data, or synthetic.