AI Forecast (TS)

The AI Forecast (TS) activity uses Singular Spectrum Analysis (SSA) to forecast future values of a time series, producing point forecasts and confidence interval bounds.

Purpose

Use the AI Forecast (TS) activity to:

• Predict future periods of a numeric time series (revenue, cost, volume, headcount)
• Generate confidence intervals around forecasts for scenario planning
• Produce forecasts that account for seasonality automatically

Algorithm

Uses ML.NET ForecastBySsa (Singular Spectrum Analysis):

1. The historical time series is decomposed into trend and seasonal components.
2. The decomposition is extrapolated forward for the requested number of periods (Horizon).
3. Confidence bounds are computed at the configured confidence level.

Configuration

Input Staging Table

The staging table containing the historical time series. Must have at least one numeric column (the value to forecast) and one sort column (to order the series chronologically).

Sort Column

The name of the column used to sort rows into time order before forecasting. Typically a date, period key, or sequence number.

Output Staging Table

The staging table where forecast results are written.

Transforms

Pre-processing pipeline. Use Convert Type to ensure the input value column is Single (float) type, which is required by the forecasting algorithm.

Train Model step settings (configured in the Transforms editor):

Setting	Description
Forecasted Column	The name of the column containing the historical values to forecast
Output Column Name	Column name for the point forecast values (default: Forecast)
Lower Bound Column Name	Column name for the lower confidence bound (default: LowerBound)
Upper Bound Column Name	Column name for the upper confidence bound (default: UpperBound)
Horizon	Number of future periods to forecast (default: 50, min: 3)
Confidence Level	Confidence level for the interval bounds (default: 0.95, range: 0.1–0.99)
Seasonality Enabled	When checked, the activity auto-detects the seasonal period. If detection fails or returns negative, defaults to a period of 12

Row Filter (optional)

Filter the input data before forecasting (e.g. filter to a specific entity or product).

Output Schema

Column	Description
Index	Row number (0-based)
Forecast (or configured name)	Point forecast value
LowerBound (or configured name)	Lower confidence bound
UpperBound (or configured name)	Upper confidence bound
RowNumber	Row sequence number

The first sample forecasted values (up to 3) are logged to the workflow run log.

Usage Notes

• The window size (number of historical periods used for the SSA model) is auto-adjusted if Seasonality Enabled is on. If the auto-detected period would produce a window size exceeding half the row count, the window size is capped and a warning is logged.
• The input series must be sorted chronologically by the Sort Column. The activity will sort by this column before forecasting.
• The value column must be of type Single (float). Use a Convert Type transform if it is stored as Double or Int32.

Best Practices

• Enable Seasonality Enabled for data with regular patterns (monthly, quarterly). Disable it for trend-only series without seasonal patterns.
• Set Horizon to the number of periods you actually need — forecasting too far ahead increases uncertainty rapidly.
• A Confidence Level of 0.95 means 95% of actual future values are expected to fall within the bounds, assuming the historical pattern continues.
• Use a Row Filter to restrict the input to a single entity/product if the staging table contains data for multiple series.

Needs Review

Confirm whether the window size and series length parameters can be configured directly, or only through the seasonality auto-detection path.

JSON Reference

{
  "discriminator": "ForecastBySsaWorkflowActivity",
  "activityId": "<uuid>",
  "name": "AI Forecast (TS)",
  "positionX": 0,
  "positionY": 0,
  "advanceRule": 2,
  "inputStagingTable": "StagingTimeSeries",
  "outputStagingTable": "StagingForecast",
  "fsoPath": "",
  "mode": 0,
  "transforms": [],
  "filter": null,
  "sortColumnName": "Period",
  "inputColumnName": "Value",
  "outputColumnName": "Forecast",
  "lowerBoundOutputColumnName": "LowerBound",
  "upperBoundOutputColumnName": "UpperBound",
  "windowSize": 12,
  "horizon": 10,
  "confidenceLevel": 0.95,
  "windowSizeEstimator": false
}

Property	Type	Description
inputStagingTable	string	Corresponds to the Input Staging Table field. The staging table containing the historical time series.
outputStagingTable	string	Corresponds to the Output Staging Table field. The staging table where forecast results are written.
fsoPath	string	File system path. Not used by this activity but present as an inherited field.
mode	integer	0 = TrainModel, 1 = RunModel. Not applicable — this activity trains and applies in a single pass.
transforms	array	Corresponds to the Transforms editor. Array of transform objects for pre-processing (e.g. Convert Type to Single).
filter	object | null	Corresponds to the Row Filter field. An optional filter applied to input rows before forecasting. null means no filter.
sortColumnName	string	Corresponds to the Sort Column field. Column used to sort rows into chronological order.
inputColumnName	string	Corresponds to the Forecasted Column setting. The column containing the historical values to forecast.
outputColumnName	string	Corresponds to the Output Column Name setting. Column name for point forecast values in the output table. Default: "Forecast".
lowerBoundOutputColumnName	string	Corresponds to the Lower Bound Column Name setting. Column name for the lower confidence bound. Default: "LowerBound".
upperBoundOutputColumnName	string	Corresponds to the Upper Bound Column Name setting. Column name for the upper confidence bound. Default: "UpperBound".
windowSize	integer	The SSA window size (number of historical periods). Overridden by auto-detection when windowSizeEstimator is true. Default: 12.
horizon	integer	Corresponds to the Horizon setting. Number of future periods to forecast. Default: 10.
confidenceLevel	float	Corresponds to the Confidence Level setting. Confidence level for interval bounds (0.1–0.99). Default: 0.95.
windowSizeEstimator	boolean	Corresponds to the Seasonality Enabled setting. When true, the seasonal period is auto-detected and used as the window size.