STGNN<T>

Models & Types · AiDotNet.Finance.Graph

STGNN (Spatio-Temporal Graph Neural Network) for forecasting on graph-structured time series data.

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

For Beginners

STGNN is designed for data where locations/entities are connected:

The Key Insight: Many real-world time series are not independent - they’re connected in space or by relationships. Traffic at one intersection affects nearby intersections; one stock’s movement affects related stocks. STGNN models both these spatial connections and temporal patterns simultaneously.

What Problems Does STGNN Solve?

  • Traffic forecasting (sensors connected by roads)
  • Financial network prediction (assets connected by correlations)
  • Weather forecasting (stations connected geographically)
  • Social network dynamics (users connected by relationships)

How STGNN Works:

  1. Graph Representation: Encode spatial relationships as an adjacency matrix
  2. Spatial Aggregation: Each node gathers information from neighbors via graph convolution
  3. Temporal Modeling: Capture time patterns using temporal convolutions
  4. ST Fusion: Alternate spatial and temporal processing for joint modeling
  5. Prediction: Output forecasts for all nodes in the network

STGNN Architecture:

  • ST-Conv Blocks: Sandwich structure (Temporal-Spatial-Temporal) for deep ST learning
  • Graph Convolution: Chebyshev spectral convolution for efficient neighbor aggregation
  • Gated Units: Control information flow between spatial and temporal paths
  • Residual Connections: Enable training of deep networks

Key Benefits:

  • Captures complex spatio-temporal dependencies
  • Scales to large graphs (hundreds of nodes)
  • Handles both directed and undirected graphs
  • Provides multi-step ahead forecasts for all nodes

How It Works

STGNN combines graph neural networks for spatial dependencies with temporal convolutions for time series patterns, enabling forecasting on interconnected entities.

Reference: Yu et al., “Spatio-Temporal Graph Convolutional Networks”, IJCAI 2018. https://arxiv.org/abs/1709.04875

Example

// Define architecture for spatio-temporal traffic forecasting (325 sensors, 12-step horizon)
var architecture = new NeuralNetworkArchitecture<double>(
    inputType: InputType.OneDimensional,
    taskType: NeuralNetworkTaskType.Regression,
    inputHeight: 12, inputWidth: 325, inputDepth: 1, outputSize: 12);
            
// Training mode: sandwich temporal-spatial-temporal convolutional blocks
var model = new STGNN<double>(architecture);
            
// ONNX inference mode: load pre-trained ST-GCN model
var onnxModel = new STGNN<double>(architecture, "stgnn_traffic.onnx");

Constructors

Constructor Summary
STGNN(NeuralNetworkArchitecture<T> architecture, STGNNOptions<T> options, Tensor<T> adjacencyMatrix, IGradientBasedOptimizer<T, Tensor<T>, Tensor<T>> optimizer, ILossFunction<T> lossFunction) Initializes a new instance of the STGNN model in native mode for training.
STGNN(NeuralNetworkArchitecture<T> architecture, string onnxModelPath, STGNNOptions<T> options, Tensor<T> adjacencyMatrix) Initializes a new instance of the STGNN model in ONNX mode for inference.

Properties

Property Summary
bool IsChannelIndependent { get; }
bool SupportsTraining { get; } Gets whether the model supports training (native mode only).
bool UseNativeMode { get; }
int ForecastHorizon { get; } Gets the forecast horizon.
int NumFeatures { get; }
int NumNodes { get; } Gets the number of nodes in the graph.
int NumSamples { get; } Gets the number of samples for uncertainty estimation.
int PatchSize { get; }
int PredictionHorizon { get; }
int SequenceLength { get; }
int Stride { get; }
string GraphConvType { get; } Gets the type of graph convolution used.

Methods

Method Summary
Dictionary<string, T> Evaluate(Tensor<T> predictions, Tensor<T> actuals) Evaluates forecast quality against actual values.
Dictionary<string, T> GetFinancialMetrics() Gets financial-specific metrics.
ModelMetadata<T> GetModelMetadata() Gets metadata about the STGNN model.
Tensor<T> ApplyInstanceNormalization(Tensor<T> input) Applies instance normalization (identity for STGNN).
Tensor<T> AutoregressiveForecast(Tensor<T> input, int steps) Performs autoregressive forecasting for extended horizons.
Tensor<T> Forward(Tensor<T> input) Performs the forward pass through all layers.
ValueTuple<Tensor<T>, Tensor<T>, Tensor<T>> ForecastWithIntervals(Tensor<T> input, double confidenceLevel) Generates forecasts with prediction intervals.