Forecasting Configuration

All forecasting configuration lives in scenario.config_parameters under parameter_type = ''forecasting'' (and per-pipeline overrides in config_forecast_parameter_set). It is loaded at runtime by ParameterResolver and can be edited through Pipelines → Forecast tab → Forecast Params.

---

Forecast Horizon

Key	Current default	Description
horizon	78	Weekly periods ahead (78 weeks ≈ 18 months)
frequency	W	Aggregation frequency: W weekly
min_obs	12	Series with fewer observations are skipped

The horizon is stored per parameter set. All existing parameter sets use 78 weeks. Changing to a larger value increases run time and chart width.

---

Confidence Levels

Prediction-interval bands are configured in one place only: the Method Selection expand row (settings_param_sets[].params.confidence_levels). This is the only key merged into config['forecasting']['confidence_levels'] at pipeline runtime.

Key	Default	Description
confidence_levels	[80, 95]	Prediction interval coverage levels (%). Each level L produces a lower bound at quantile (100-L)/200 and an upper bound at 1-(100-L)/200.

Available values: 50, 60, 70, 80, 90, 95, 99.

How they flow

confidence_levels: [80, 95]
  → StatsForecast level=[80,95] / ML quantile targets / Neural MQLoss
  → ForecastResult.quantiles = {0.025, 0.10, 0.50, 0.90, 0.975}
  → distribution fitting (quantile-matching) → PIPE_fitted_distributions
  → MEIO service-level quantiles → safety stock (PIPE_meio_results.committed_buffer)

More levels (e.g. [10, 25, 50, 75, 90, 95, 99]) = more quantile points for the distribution fitter = a better-parametrized distribution, especially in the tails where safety stock lives. With only [80, 95] the fitter has just 5 points.

V3 bootstrap note

When MEIO V3 empirical distributions are active (meio.use_empirical_distributions=true), confidence levels are bypassed for safety-stock computation — V3 builds demand-over-lead-time distributions directly from observed master.demand_actuals rows with received_date. Confidence levels still drive: - Shaded prediction-interval bands on forecast charts - PIPE_fitted_distributions (V3 fallback when empirical is disabled/unavailable)

---

Demand Horizon Limits (min/max periods gate)

A forecasting-eligibility gate that controls how many demand periods a series must have to be forecast, and what to do when the minimum is not met.

Key	Default	Description
demand_horizon_limits.min_periods	0	Series with fewer distinct demand periods → below_min_policy applied. 0 = no minimum.
demand_horizon_limits.max_periods	0	Series with more periods → truncate to the most recent max_periods rows. 0 = no maximum. Global only (no per-method override).
demand_horizon_limits.below_min_policy	skip	skip = do not forecast the series (writes a min_periods_not_met row to PIPE_series_exceptions); zero_fill = reindex the series to a complete date range, filling missing periods with 0 (observed-span anchor only).

Per-method override

Each method in METHOD_HYPERPARAMS gains optional min_periods and below_min_policy fields. When absent (or min_periods=0 / below_min_policy=""), the global defaults apply. Per-method max_periods is not allowed (to avoid conflicting with ML/DL input_size).

Resolution order: per-series override (Hyperparameters tab) → per-method override (Method Selection HyperparamModal) → global default (demand_horizon_limits).

Relationship to existing gates

Gate	Scope	Relationship
etl.min_observations (default 12)	ETL ingest — drops series entirely	Separate concern (data quality). Demand Horizon Limits runs after ETL.
characterization.data_sufficiency.min_for_ml / min_for_deep_learning	Method-family eligibility (ML ≥100, DL ≥200)	The new min_periods is more general (applies to all methods). min_for_ml/min_for_dl remain as method-family defaults.

Key files

• files/utils/demand_horizon_limits.py — resolve_limits(), apply_limits(), zero-fill reindex
• files/utils/orchestrator.py — forecast_batch() gate + _flush_demand_horizon_skips()

---

Enabled Models

Statistical Models (StatsForecast)

Model	Default	Notes
AutoARIMA	enabled	Best general-purpose
AutoETS	enabled	Exponential smoothing; robust and fast
AutoTheta	enabled	Decomposition; excellent for trend+season
MSTL	enabled	Multi-seasonal decomposition
CrostonOptimized	enabled	Intermittent demand only

Neural Models (NeuralForecast)

Require neuralforecast. Minimum 104 observations enforced by characterisation.

Model	Notes
NHITS	Hierarchical interpolation
NBEATS	Interpretable decomposition
PatchTST	Transformer; strong on long series
TFT	Temporal Fusion Transformer; covariate-aware
DeepAR	Probabilistic; good for intermittent

Foundation Model (TimesFM)

Zero-shot model requiring the timesfm-1.0-200m checkpoint. Loaded once per run, reused across all series.

ML Models (LightGBM / XGBoost)

Tree-based gradient boosting with engineered lag features. Require sufficient_for_ml = True (default ≥ 52 observations). These are the only methods that produce feature_importance values.

Key	Default	Description
ml_models	["LightGBM", "XGBoost"]	Which ML models to run
ml.n_lags	13	Lag feature count
ml.n_estimators	200	Trees per model

When LightGBM or XGBoost runs, the feature_importance field in PIPE_forecast_point_values is populated with a JSON dict mapping feature names to importance weights (normalised to sum to 1). This drives the third dot in the Dashboard Features column.

---

External Features

External covariate time-series are managed via:

• master_feature_registry — defines each feature (name, type, future_available, granularity)
• master_feature_values — stores the actual values (date, unique_id for series-type, value)
• pipe_feature_reliability — per-pipeline, per-feature reliability scores (correlation, MAPE, bias)

Feature Types

Type	Description	Availability
global	Applies to all series (e.g. Holiday Index, Weather Index)	Future values can be known in advance
series	Per-series values (e.g. Customer Backlog ratio)	Historical only

Feature Status in Dashboard

The Features column in the series table shows up to three dots:

1. Green — feature data exists (global feature registry has rows, or this series has series-type values)
2. Blue — reliability assessed (pipe_feature_reliability row exists for this pipeline)
3. Emerald — feature used in forecast (feature_importance non-empty in CH for this pipeline)

Reliability Gating

The FeatureLoader reads pipe_feature_reliability for the current pipeline. Features whose reliability_score is below min_reliability (default 0.0 = accept all) are excluded from the model input.

---

Method Selection Strategy

Value	Behaviour
auto	Routes each series to appropriate methods based on characterisation
fixed_set	Runs only the methods in best_fit_methods for all series

Auto routing rules: - is_intermittent = True → CrostonOptimized; skip MSTL - has_seasonality = True → MSTL, AutoETS - has_trend = True → AutoARIMA, AutoTheta - sufficient_for_ml = True + ML enabled → LightGBM / XGBoost - sufficient_for_deep_learning = True + neural enabled → NHITS etc. - Baseline: AutoARIMA and AutoETS always run

---

Backtesting

{
  "backtesting": {
    "n_windows": 3,
    "window_size": 12,
    "step_size": 1,
    "metrics": ["mae", "rmse", "mase", "bias", "coverage_90"]
  }
}

---

Parallelisation (Dask)

{
  "dask": {
    "n_workers": 4,
    "threads_per_worker": 1,
    "chunk_size": 50,
    "scheduler": "distributed"
  }
}

---

Per-Pipeline Parameter Sets

config_forecast_parameter_set stores per-pipeline forecast + outlier parameter overrides. Managed from Pipelines → Forecast tab → Forecast Params panel. Supports drag-drop reorder, multi-segment assignment, and inline editing.

{
  "outlier": {
    "enabled": true,
    "detection_method": "iqr",
    "correction_method": "clip",
    "iqr_multiplier": 1.5
  },
  "forecast": {
    "horizon": 78,
    "methods": ["AutoARIMA", "AutoETS", "MSTL"]
  }
}

Note: Confidence levels (confidence_levels) are configured in Method Selection, not in Forecast Parameter Sets. The legacy forecast.confidence_intervals key has been removed (it was never merged into the live forecaster config).