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:
- Graph Representation: Encode spatial relationships as an adjacency matrix
- Spatial Aggregation: Each node gathers information from neighbors via graph convolution
- Temporal Modeling: Capture time patterns using temporal convolutions
- ST Fusion: Alternate spatial and temporal processing for joint modeling
- 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. |