DiffusionTS<T>

Models & Types · AiDotNet.Finance.Probabilistic

DiffusionTS (Interpretable Diffusion for Time Series) for probabilistic forecasting with seasonal-trend decomposition.

Inheritance: NeuralNetworkBase<T> → FinancialModelBase<T> → ForecastingModelBase<T> → DiffusionTS<T>

For Beginners

DiffusionTS makes diffusion models more interpretable by decomposing time series into understandable components:

The Key Insight: Time series often have clear structure (trends, seasonality) that gets lost in “black box” models. DiffusionTS preserves this structure by generating each component separately and combining them.

How DiffusionTS Works:

  1. Window: The history and the horizon form one window, standardised per series
  2. Denoiser: A transformer predicts the clean window from a noisy one and the noise level
  3. Decomposition: Its decoder writes each prediction as a trend (a low-order polynomial)

plus seasonality (the strongest Fourier components) plus a residual

  1. Forecasting: Starting from noise, each denoising step keeps the observed history

in place, so the horizon is generated to continue it

Training: The model learns to recover the clean window, with an extra loss on its Fourier coefficients so that periodic structure is learned explicitly.

Key Benefits:

  • Interpretable decomposition of forecasts
  • Can enforce structural constraints (smooth trends, periodic seasons)
  • Better uncertainty quantification per component
  • Enables “what-if” analysis by modifying components

How It Works

DiffusionTS is an interpretable diffusion model that uses seasonal-trend decomposition to generate forecasts with clear interpretable components.

Reference: Yuan and Qiao, “Diffusion-TS: Interpretable Diffusion for General Time Series Generation”, 2024. https://arxiv.org/abs/2403.01742

Example

// Create a Diffusion-TS model for interpretable time series generation
var architecture = new NeuralNetworkArchitecture<double>(
    inputType: InputType.OneDimensional,
    taskType: NeuralNetworkTaskType.Regression,
    inputHeight: 100, inputWidth: 1, inputDepth: 1, outputSize: 24);
var model = new DiffusionTS<double>(architecture);
            
// Or load a pre-trained ONNX model for diffusion time series generation
var onnxModel = new DiffusionTS<double>(architecture, "diffusionts.onnx");

Constructors

Constructor Summary
DiffusionTS(NeuralNetworkArchitecture<T> architecture, DiffusionTSOptions<T> options, IGradientBasedOptimizer<T, Tensor<T>, Tensor<T>> optimizer, ILossFunction<T> lossFunction) Creates a native DiffusionTS model that can be trained.
DiffusionTS(NeuralNetworkArchitecture<T> architecture, string onnxModelPath, DiffusionTSOptions<T> options, IGradientBasedOptimizer<T, Tensor<T>, Tensor<T>> optimizer, ILossFunction<T> lossFunction) Creates a DiffusionTS model that runs a pretrained ONNX graph.

Properties

Property Summary
bool IsChannelIndependent { get; }
bool SupportsTraining { get; }
bool UseNativeMode { get; }
int ForecastHorizon { get; } Gets the number of future steps forecast.
int NumDiffusionSteps { get; } Gets the number of diffusion steps T.
int NumFeatures { get; }
int NumSamples { get; } Gets how many generated windows a forecast averages.
int PatchSize { get; }
int PredictionHorizon { get; }
int SequenceLength { get; }
int Stride { get; }

Methods

Method Summary
Dictionary<string, T> Evaluate(Tensor<T> predictions, Tensor<T> actuals)
Dictionary<string, T> GetFinancialMetrics()
Dictionary<string, Tensor<T>> GetNamedLayerActivations(Tensor<T> input)
ModelMetadata<T> GetModelMetadata()
Tensor<T> ApplyInstanceNormalization(Tensor<T> input)
Tensor<T> AutoregressiveForecast(Tensor<T> input, int steps)
Tensor<T> ForwardForTraining(Tensor<T> input) x_0-hat for a pair from PrepareTrainingPair, laid out as the objective row [x_0-hat | w_F Re F x_0-hat | w_F Im F x_0-hat] times the row’s scale.
ValueTuple<Tensor<T>, Tensor<T>, Tensor<T>> ForecastWithIntervals(Tensor<T> input, double confidenceLevel) The forecast with a central prediction interval at confidenceLevel.