Spektral

Spektral is a Python library for graph deep learning built on the Keras API and TensorFlow 2. It provides a framework for creating Graph Neural Networks (GNNs) for tasks such as social network user classification, molecular property prediction, graph generation (GANs), node clustering, and link prediction.

Key components include:

Convolutional Layers

Spektral implements several popular graph convolution operations, including:

• Graph Convolutional Networks (GCN)
• Chebyshev convolutions
• GraphSAGE
• ARMA convolutions
• Edge-Conditioned Convolutions (ECC)
• Graph attention networks (GAT)
• Approximated Personalized Propagation of Neural Predictions (APPNP)
• Graph Isomorphism Networks (GIN)
• Diffusional Convolutions

Pooling Layers

For graph pooling tasks, Spektral provides:

• MinCut pooling
• DiffPool
• Top-K pooling
• Self-Attention Graph (SAG) pooling
• Global pooling
• Global gated attention pooling
• SortPool

Utilities

The library includes utilities for representing, manipulating, and transforming graphs.

Spektral uses four distinct data modes to represent one or more graphs by grouping their x (node features), a (adjacency matrix), and e (edge features) into single tensors X, A, and E. Choosing the right mode depends on whether you are working with a single graph, a collection of graphs of different sizes, or multiple signals on a single graph.

Note: batch is the batch size, nodes is the number of nodes, edges is the number of edges, n_feat is the number of node features, and e_feat is the number of edge features.

In Spektral, graphs are represented using spektral.data.Graph objects. A graph is defined by four main attributes:

• a: The adjacency matrix. Can be a dense np.array or a Scipy sparse matrix of shape [n_nodes, n_nodes]. Sparse matrices are generally preferred for memory efficiency.
• x: The node features. Represented as a dense np.array of shape [n_nodes, n_node_features].
• e: The edge features. Represented as a dense np.array of shape [n_edges, n_edge_features].
  • Important: Spektral assumes edge features are sorted in row-major ordering (sorted by row, then by column). Use spektral.utils.sparse.reorder to ensure your edge features match the order of the edges in the adjacency matrix.
• y: The labels. Can be graph-level (scalars or 1D arrays of shape [n_labels, ]) or node-level (1D arrays of shape [n_nodes, ] or 2D arrays of shape [n_nodes, n_labels]).

To create a custom dataset in Spektral 1.0, you must subclass spektral.data.Dataset. The implementation relies on two primary methods:

1. read(): This is the core method. It is called during instantiation and must return a list of spektral.data.Graph objects. This is where you load your data into memory (from files or generated on the fly).
2. download(): This method is called by __init__ if the dataset's path does not exist on disk. Use this to define operations for saving raw data to a directory.

Key Lifecycle Rules:

• __init__ calls download() (if needed) and then read().
• If you override __init__, you must call super().__init__(**kwargs) (ideally as the last line) to ensure the dataset is correctly initialized.
• The path property defaults to ~/spektral/datasets/[ClassName].

from spektral.data import Dataset, Graph

class MyDataset(Dataset):
    def __init__(self, nodes, feats, **kwargs):
        self.nodes = nodes
        self.feats = feats
        super().__init__(**kwargs)

    def download(self):
        # Logic to save data to self.path
        pass

    def read(self):
        # Must return a list of Graph objects
        return [Graph(x=..., a=..., y=...) for _ in range(n)]

The 1.0 release introduced several architectural improvements to standardize data handling and model building:

• Standardized Data Containers: New Graph and Dataset containers standardize how data is handled (this does not impact existing models but improves data usability).
• Simplified Batching: The new Loader class manages the complexity of creating graph batches, allowing users to focus on training logic whether using custom loops or model.fit().
• Graph Transformations: A new transforms module allows applying common graph operations via the apply() method on datasets.
• General Architectures: New GeneralConv and GeneralGNN classes provide flexible model building with sensible defaults based on state-of-the-art literature.
• Expanded Datasets: Includes QM7, ModelNet10/40, and a new wrapper for OGB datasets.
• API Change Note: The primary breaking change for existing users is the new datasets API.