graphtoolbox.models.temporal

Temporal graph models built on PyG-Temporal recurrent cells.

The static architecture myGNN relies on ConvAdapter to expose every torch_geometric convolution behind a single (x, edge_index) interface. This module mirrors that design for the recurrent graph cells of torch_geometric_temporal: ConvAdapterTemporal absorbs the calling conventions of those cells and TemporalGNN plays the role of myGNN, turning a lag-augmented node feature vector into a horizon forecast through a genuine sequence unrolling.

graphtoolbox.models.temporal.lag_sequence_indices(features, target='load')

Split a feature list into a lag sequence and the remaining static columns.

The lag columns of target (named {target}_l{k}) form the temporal sequence, ordered from the oldest lag to the most recent one so that a recurrent cell consumes them in chronological order. Every other column is treated as a static side feature.

Parameters:

• features (list[str]) – Ordered feature names, as exposed by GraphDataset.features.

• target (str, optional) – Base name of the lagged target (default "load").

Returns:

(seq_idx, static_idx): column indices of the lag sequence (oldest first) and of the static features.

Return type:

tuple[list[int], list[int]]

class graphtoolbox.models.temporal.ConvAdapterTemporal(cell_class, in_channels, hidden_channels, seq_len=None, cell_kwargs=None)

Bases: Module

Wrap a PyG-Temporal recurrent graph cell for use inside TemporalGNN.

Analogous to ConvAdapter, this adapter hides the two calling conventions found in torch_geometric_temporal:

• step-recurrent cells (GConvGRU, DCRNN, TGCN) accept one step at a time as cell(x_t, edge_index, edge_weight, H) and carry the hidden state H across the sequence;

• windowed cells (A3TGCN) receive the whole window at once as cell(X, edge_index, edge_weight) with X shaped [N, C, periods] and therefore need the number of periods at construction time.

Both regimes are detected from the constructor signature, so callers only provide the cell class and its hyper-parameters.

Parameters:

• cell_class (type) – A torch_geometric_temporal.nn.recurrent cell class (not an instance).

• in_channels (int) – Number of features carried at each sequence step (1 for a plain load lag sequence).

• hidden_channels (int) – Hidden state dimension produced by the cell.

• seq_len (int, optional) – Sequence length, required for windowed cells to set periods when it is not already given in cell_kwargs.

• cell_kwargs (dict, optional) – Extra keyword arguments forwarded to the cell constructor (e.g. K).

forward(seq, edge_index, edge_weight=None)

Reduce a per-node sequence to a hidden representation.

Parameters:

• seq (torch.Tensor) – Sequence tensor of shape [N, T] (single channel) or [N, T, in_channels].

• edge_index (torch.LongTensor) – Graph connectivity in COO format.

• edge_weight (torch.Tensor, optional) – Optional edge weights.

Returns:

Hidden state of shape [N, hidden_channels].

Return type:

torch.Tensor

class graphtoolbox.models.temporal.TemporalGNN(in_channels, hidden_channels, out_channels, cell_class, seq_idx, static_idx, cell_kwargs=None, seq_channels=1, **kwargs)

Bases: Module

Recurrent spatio-temporal forecaster, the temporal counterpart of myGNN.

The lag columns of the target are unrolled through a ConvAdapterTemporal that carries a graph-aware hidden state across the sequence. The final hidden state is concatenated with the static features and projected to the forecast horizon by a linear head. The class exposes the attributes the GraphToolbox Trainer relies on (conv_class, conv_kwargs, hidden_channels, num_layers, heads) so it trains, reconciles and caches exactly like the static models.

Parameters:

• in_channels (int) – Total number of node features (kept for API symmetry with myGNN; the sequence/static split is driven by seq_idx / static_idx).

• hidden_channels (int) – Hidden state dimension of the recurrent cell.

• out_channels (int) – Forecast horizon (output dimension per node).

• cell_class (type) – A torch_geometric_temporal recurrent cell class.

• seq_idx (list[int]) – Column indices forming the temporal sequence, oldest lag first.

• static_idx (list[int]) – Column indices of the static side features.

• cell_kwargs (dict, optional) – Extra keyword arguments forwarded to the cell (e.g. K).

• seq_channels (int, optional) – Number of features per sequence step (default 1).

classmethod from_features(features, cell_class, hidden_channels, out_channels, target='load', cell_kwargs=None, **kwargs)

Build a TemporalGNN by deriving the lag split from feature names.

Parameters:

• features (list[str]) – Ordered feature names (GraphDataset.features).

• cell_class (type) – Recurrent cell class.

• hidden_channels (int) – Hidden and output dimensions.

• out_channels (int) – Hidden and output dimensions.

• target (str, optional) – Base name of the lagged target (default "load").

• cell_kwargs (dict, optional) – Extra keyword arguments forwarded to the cell.

Return type:

TemporalGNN

forward(x, edge_index, edge_weight=None, **kwargs)

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.