graphtoolbox.data.builder¶

Classes

GraphBuilder(graph_dataset_train, ...)

Constructs graph representations from tabular or temporal datasets, combining feature reduction and graph construction algorithms.

class graphtoolbox.data.builder.GraphBuilder(graph_dataset_train, graph_dataset_val, graph_dataset_test, **kwargs)[source][source]¶

Bases: object

Constructs graph representations from tabular or temporal datasets, combining feature reduction and graph construction algorithms.

This class provides a unified interface for transforming time series or feature datasets into adjacency matrices suitable for graph neural networks. It can:

Reduce temporal or feature signals (e.g., via SVD or RESITER)
Build graphs based on spatial distance, correlation, precision matrices, GL-3SR, or dynamic time warping (DTW)
Optionally reuse previously computed signals or graphs from disk

Parameters:

graph_dataset_train (Dataset) – Dataset containing training graph data (with features, nodes, etc.).
graph_dataset_val (Dataset) – Dataset for validation.
graph_dataset_test (Dataset) – Dataset for testing.
model_vgae (object, optional) – Pre-trained VGAE (Variational Graph AutoEncoder) model to initialize the graph builder.
load_graph (bool, default=False) – If True, load a previously saved adjacency matrix instead of recomputing it.
load_signal (bool, default=False) – If True, load a pre-computed reduced signal representation from disk.
reduce_method (str, default='svd') – Method to reduce the signal before graph construction. Options are 'svd' or 'resiter'.
folder_config (str, optional) – Path to a configuration folder (used to load positional data and parameters via load_kwargs).
**kwargs – Additional keyword arguments (e.g., algorithm hyperparameters or model options).

model_vgae¶

VGAE model instance, if provided.

Type:: object or None

load_graph¶

Whether an existing graph should be loaded instead of generated.

Type:: bool

load_signal¶

Whether to reuse a pre-computed reduced signal.

Type:: bool

reduce_method¶

Signal reduction strategy used by reduce_signal().

Type:: str

folder_config¶

Folder path containing saved positional or configuration data.

Type:: str or None

df_pos¶

Positional data for nodes (longitude, latitude) loaded from configuration.

Type:: pandas.DataFrame or None

graph_dataset_train¶

Dataset used for training.

Type:: Dataset

graph_dataset_val¶

Dataset used for validation.

Type:: Dataset

graph_dataset_test¶

Dataset used for testing.

Type:: Dataset

dataframe¶

The raw DataFrame from the training dataset.

Type:: pandas.DataFrame

data¶

The training dataset’s data container.

Type:: DataFrame-like

Notes

The build_graph() method always calls reduce_signal() before constructing an adjacency matrix, unless load_graph=True. The resulting graph can be fed into GNNs (e.g., GCN, GraphSAGE).

Examples

>>> gb = GraphBuilder(train_set, val_set, test_set, reduce_method='svd')
>>> W = gb.build_graph(algo='space', threshold=0.1)
>>> W.shape
torch.Size([N, N])

build_graph(algo, **kwargs)[source][source]¶

Build or load an adjacency matrix using a specified graph construction algorithm.

Parameters:

algo (str) – Graph construction method. Options: 'space', 'correlation', 'precision', 'gl3sr', or 'dtw'.
**kwargs (dict) – Algorithm-specific hyperparameters (e.g., threshold, alpha, beta).

Returns:

Adjacency matrix of shape (N, N).

Return type:

torch.Tensor

Raises:

NotImplementedError – If the specified algorithm is not supported.

reduce_signal(**kwargs)[source][source]¶

Compute or load a reduced signal representation from the dataset.

Parameters:: **kwargs (dict) – Method-specific parameters (e.g., k_max, model_base, num_epochs).
Returns:: Reduced feature matrix of shape (num_nodes, num_features).
Return type:: np.ndarray