Implementation:Dotnet Machinelearning ForecastBySsa
| Knowledge Sources | |
|---|---|
| Domains | Machine Learning, Time Series, .NET |
| Last Updated | 2026-02-09 00:00 GMT |
Overview
The ForecastBySsa extension method creates an SsaForecastingEstimator configured with Singular Spectrum Analysis parameters for time series forecasting in ML.NET.
Description
ForecastBySsa is an extension method on ForecastingCatalog that constructs an SsaForecastingEstimator. This estimator encapsulates all SSA hyperparameters — window size, series length, training size, forecast horizon, rank selection, adaptive behavior, and confidence interval settings — into a single estimator object that implements IEstimator<SsaForecastingTransformer>.
The method serves as the entry point for the SSA forecasting pipeline. It validates parameter constraints (e.g., windowSize must be between 2 and seriesLength, trainSize must be at least 2 * windowSize) and passes them to the underlying SsaForecastingEstimator, which holds the SsaForecastingEstimator.Options configuration record.
The estimator supports optional confidence interval columns: when confidenceLowerBoundColumn and confidenceUpperBoundColumn are specified, the fitted model will produce lower and upper prediction bounds alongside point forecasts.
Usage
Call ForecastBySsa on mlContext.Forecasting to create the estimator. Then call .Fit() on the estimator with training data to produce the fitted transformer.
Code Reference
Source Location
- Repository: ML.NET
- File:
src/Microsoft.ML.TimeSeries/ExtensionsCatalog.cs:L475-482(extension method) - File:
src/Microsoft.ML.TimeSeries/SSaForecasting.cs:L232-356(SsaForecastingEstimator) - File:
src/Microsoft.ML.TimeSeries/SSaForecasting.cs:L36-92(SsaForecastingEstimator.Options)
Signature
public static SsaForecastingEstimator ForecastBySsa(
this ForecastingCatalog catalog,
string outputColumnName,
string inputColumnName,
int windowSize,
int seriesLength,
int trainSize,
int horizon,
bool isAdaptive = false,
float discountFactor = 1f,
RankSelectionMethod rankSelectionMethod = RankSelectionMethod.Exact,
int? rank = null,
int? maxRank = null,
bool shouldStabilize = true,
bool shouldMaintainInfo = false,
GrowthRatio? maxGrowth = null,
string confidenceLowerBoundColumn = null,
string confidenceUpperBoundColumn = null,
float confidenceLevel = 0.95f,
bool variableHorizon = false)
Import
using Microsoft.ML;
using Microsoft.ML.Transforms.TimeSeries;
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| outputColumnName | string | Yes | Name of the output column that will contain the forecast values. |
| inputColumnName | string | Yes | Name of the input column containing the time series data (Single/float). |
| windowSize | int | Yes | Trajectory matrix width (L). Must be in range [2, seriesLength]. Controls decomposition resolution. |
| seriesLength | int | Yes | Internal buffer length (N). Must be >= windowSize. Determines how much history the model retains. |
| trainSize | int | Yes | Number of initial observations used for fitting. Must be >= 2 * windowSize. |
| horizon | int | Yes | Number of future time steps to forecast. |
| isAdaptive | bool | No | Enable adaptive (online) updates. Default: false. |
| discountFactor | float | No | Weight decay for older observations when adaptive. Range [0, 1]. Default: 1 (no decay). |
| rankSelectionMethod | RankSelectionMethod | No | How to select the number of retained singular components. Default: Exact. |
| rank | int? | No | Exact number of singular components to retain (when method is Exact). Default: null (auto). |
| maxRank | int? | No | Maximum rank for automatic selection. Default: null. |
| shouldStabilize | bool | No | Whether to stabilize the recurrence coefficients. Default: true. |
| shouldMaintainInfo | bool | No | Whether to maintain information during updates. Default: false. |
| maxGrowth | GrowthRatio? | No | Maximum growth ratio for adaptive updates. Default: null. |
| confidenceLowerBoundColumn | string | No | Output column for lower confidence bounds. Default: null (not produced). |
| confidenceUpperBoundColumn | string | No | Output column for upper confidence bounds. Default: null (not produced). |
| confidenceLevel | float | No | Confidence level for prediction intervals. Default: 0.95. |
| variableHorizon | bool | No | Whether to allow variable-length forecast horizons at prediction time. Default: false. |
Outputs
| Name | Type | Description |
|---|---|---|
| (return) | SsaForecastingEstimator | An estimator implementing IEstimator<SsaForecastingTransformer>. Call .Fit() with training data to produce the transformer.
|
Usage Examples
Basic Example
using Microsoft.ML;
using Microsoft.ML.Transforms.TimeSeries;
var mlContext = new MLContext(seed: 42);
// Load time series data
IDataView dataView = mlContext.Data.LoadFromTextFile<MonthlySales>(
path: "monthly_sales.csv",
separatorChar: ',',
hasHeader: true);
// Configure SSA forecasting estimator
var estimator = mlContext.Forecasting.ForecastBySsa(
outputColumnName: "ForecastedSales",
inputColumnName: "Sales",
windowSize: 12, // one year of monthly data
seriesLength: 36, // three years of buffer
trainSize: 24, // two years for training
horizon: 6, // forecast 6 months ahead
confidenceLowerBoundColumn: "LowerBound",
confidenceUpperBoundColumn: "UpperBound",
confidenceLevel: 0.95f);
Adaptive Forecasting Example
// Configure an adaptive SSA model that adjusts to recent patterns
var adaptiveEstimator = mlContext.Forecasting.ForecastBySsa(
outputColumnName: "Forecast",
inputColumnName: "Value",
windowSize: 7,
seriesLength: 30,
trainSize: 30,
horizon: 3,
isAdaptive: true,
discountFactor: 0.95f, // gradual forgetting of old observations
variableHorizon: true); // allow overriding horizon at predict time
Dependencies
- Microsoft.ML.TimeSeries NuGet package
- Microsoft.ML.Mkl.Redist (Intel MKL for FFT and linear algebra operations)