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:
- Window: The history and the horizon form one window, standardised per series
- Denoiser: A transformer predicts the clean window from a noisy one and the noise level
- Decomposition: Its decoder writes each prediction as a trend (a low-order polynomial)
plus seasonality (the strongest Fourier components) plus a residual
- 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. |