{"cells": [{"cell_type": "markdown", "id": "d7d80d1d", "metadata": {"papermill": {"duration": 0.010924, "end_time": "2025-04-03T19:21:54.421357", "exception": false, "start_time": "2025-04-03T19:21:54.410433", "status": "completed"}, "tags": []}, "source": ["\n", "# Tutorial 6: Basics of Graph Neural Networks\n", "\n", "* **Author:** Phillip Lippe\n", "* **License:** CC BY-SA\n", "* **Generated:** 2025-04-03T19:21:47.666045\n", "\n", "In this tutorial, we will discuss the application of neural networks on graphs.\n", "Graph Neural Networks (GNNs) have recently gained increasing popularity in both applications and research,\n", "including domains such as social networks, knowledge graphs, recommender systems, and bioinformatics.\n", "While the theory and math behind GNNs might first seem complicated,\n", "the implementation of those models is quite simple and helps in understanding the methodology.\n", "Therefore, we will discuss the implementation of basic network layers of a GNN,\n", "namely graph convolutions, and attention layers.\n", "Finally, we will apply a GNN on semi-supervised node classification and molecule categorization.\n", "This notebook is part of a lecture series on Deep Learning at the University of Amsterdam.\n", "The full list of tutorials can be found at https://uvadlc-notebooks.rtfd.io.\n", "\n", "\n", "---\n", "Open in [{height=\"20px\" width=\"117px\"}](https://colab.research.google.com/github/PytorchLightning/lightning-tutorials/blob/publication/.notebooks/course_UvA-DL/06-graph-neural-networks.ipynb)\n", "\n", "Give us a \u2b50 [on Github](https://www.github.com/Lightning-AI/lightning/)\n", "| Check out [the documentation](https://lightning.ai/docs/)\n", "| Join us [on Discord](https://discord.com/invite/tfXFetEZxv)"]}, {"cell_type": "markdown", "id": "2dfb1b05", "metadata": {"papermill": {"duration": 0.009962, "end_time": "2025-04-03T19:21:54.440719", "exception": false, "start_time": "2025-04-03T19:21:54.430757", "status": "completed"}, "tags": []}, "source": ["## Setup\n", "This notebook requires some packages besides pytorch-lightning."]}, {"cell_type": "code", "execution_count": 1, "id": "547763be", "metadata": {"colab": {}, "colab_type": "code", "execution": {"iopub.execute_input": "2025-04-03T19:21:54.460267Z", "iopub.status.busy": "2025-04-03T19:21:54.459963Z", "iopub.status.idle": "2025-04-03T19:21:55.663186Z", "shell.execute_reply": "2025-04-03T19:21:55.662317Z"}, "id": "LfrJLKPFyhsK", "lines_to_next_cell": 0, "papermill": {"duration": 1.216165, "end_time": "2025-04-03T19:21:55.666016", "exception": false, "start_time": "2025-04-03T19:21:54.449851", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["\u001b[33mWARNING: Running pip as the 'root' user can result in broken permissions and conflicting behaviour with the system package manager, possibly rendering your system unusable.It is recommended to use a virtual environment instead: https://pip.pypa.io/warnings/venv. Use the --root-user-action option if you know what you are doing and want to suppress this warning.\u001b[0m\u001b[33m\r\n", "\u001b[0m"]}, {"name": "stdout", "output_type": "stream", "text": ["\r\n", "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m A new release of pip is available: \u001b[0m\u001b[31;49m24.2\u001b[0m\u001b[39;49m -> \u001b[0m\u001b[32;49m25.0.1\u001b[0m\r\n", "\u001b[1m[\u001b[0m\u001b[34;49mnotice\u001b[0m\u001b[1;39;49m]\u001b[0m\u001b[39;49m To update, run: \u001b[0m\u001b[32;49mpython -m pip install --upgrade pip\u001b[0m\r\n"]}], "source": ["! pip install --quiet \"torch-sparse ==0.6.*\" \"matplotlib\" \"torch >=1.8.1,<2.7\" \"numpy <2.0\" \"torchmetrics >=1.0,<1.8\" \"torch-cluster ==1.6.*\" \"torch ==2.1.2\" \"pytorch-lightning >=2.0,<2.6\" \"seaborn\" \"numpy <3.0\" \"torch-geometric ==2.1.*\" \"torch-spline-conv ==1.2.*\" \"torch-scatter ==2.1.*\" \"torchvision\""]}, {"cell_type": "markdown", "id": "8f04aabe", "metadata": {"papermill": {"duration": 0.015019, "end_time": "2025-04-03T19:21:55.697050", "exception": false, "start_time": "2025-04-03T19:21:55.682031", "status": "completed"}, "tags": []}, "source": ["\n", "We start by importing our standard libraries below."]}, {"cell_type": "code", "execution_count": 2, "id": "02eb07b3", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:21:55.725798Z", "iopub.status.busy": "2025-04-03T19:21:55.725623Z", "iopub.status.idle": "2025-04-03T19:21:58.927620Z", "shell.execute_reply": "2025-04-03T19:21:58.926660Z"}, "papermill": {"duration": 3.217105, "end_time": "2025-04-03T19:21:58.929222", "exception": false, "start_time": "2025-04-03T19:21:55.712117", "status": "completed"}, "tags": []}, "outputs": [{"name": "stderr", "output_type": "stream", "text": ["Seed set to 42\n"]}], "source": ["# Standard libraries\n", "import os\n", "\n", "# For downloading pre-trained models\n", "import urllib.request\n", "from urllib.error import HTTPError\n", "\n", "# PyTorch Lightning\n", "import pytorch_lightning as pl\n", "\n", "# PyTorch\n", "import torch\n", "import torch.nn as nn\n", "import torch.nn.functional as F\n", "import torch.optim as optim\n", "\n", "# PyTorch geometric\n", "import torch_geometric\n", "import torch_geometric.data as geom_data\n", "import torch_geometric.nn as geom_nn\n", "\n", "# PL callbacks\n", "from pytorch_lightning.callbacks import ModelCheckpoint\n", "from torch import Tensor\n", "\n", "AVAIL_GPUS = min(1, torch.cuda.device_count())\n", "BATCH_SIZE = 256 if AVAIL_GPUS else 64\n", "# Path to the folder where the datasets are/should be downloaded\n", "DATASET_PATH = os.environ.get(\"PATH_DATASETS\", \"data/\")\n", "# Path to the folder where the pretrained models are saved\n", "CHECKPOINT_PATH = os.environ.get(\"PATH_CHECKPOINT\", \"saved_models/GNNs/\")\n", "\n", "# Setting the seed\n", "pl.seed_everything(42)\n", "\n", "# Ensure that all operations are deterministic on GPU (if used) for reproducibility\n", "torch.backends.cudnn.deterministic = True\n", "torch.backends.cudnn.benchmark = False"]}, {"cell_type": "markdown", "id": "2703b965", "metadata": {"papermill": {"duration": 0.00672, "end_time": "2025-04-03T19:21:58.942988", "exception": false, "start_time": "2025-04-03T19:21:58.936268", "status": "completed"}, "tags": []}, "source": ["We also have a few pre-trained models we download below."]}, {"cell_type": "code", "execution_count": 3, "id": "ce8f1a1d", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:21:58.957785Z", "iopub.status.busy": "2025-04-03T19:21:58.957438Z", "iopub.status.idle": "2025-04-03T19:21:59.378294Z", "shell.execute_reply": "2025-04-03T19:21:59.377043Z"}, "papermill": {"duration": 0.429926, "end_time": "2025-04-03T19:21:59.379644", "exception": false, "start_time": "2025-04-03T19:21:58.949718", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Downloading https://raw.githubusercontent.com/phlippe/saved_models/main/tutorial7/NodeLevelMLP.ckpt...\n", "Downloading https://raw.githubusercontent.com/phlippe/saved_models/main/tutorial7/NodeLevelGNN.ckpt...\n"]}, {"name": "stdout", "output_type": "stream", "text": ["Downloading https://raw.githubusercontent.com/phlippe/saved_models/main/tutorial7/GraphLevelGraphConv.ckpt...\n"]}], "source": ["# Github URL where saved models are stored for this tutorial\n", "base_url = \"https://raw.githubusercontent.com/phlippe/saved_models/main/tutorial7/\"\n", "# Files to download\n", "pretrained_files = [\"NodeLevelMLP.ckpt\", \"NodeLevelGNN.ckpt\", \"GraphLevelGraphConv.ckpt\"]\n", "\n", "# Create checkpoint path if it doesn't exist yet\n", "os.makedirs(CHECKPOINT_PATH, exist_ok=True)\n", "\n", "# For each file, check whether it already exists. If not, try downloading it.\n", "for file_name in pretrained_files:\n", " file_path = os.path.join(CHECKPOINT_PATH, file_name)\n", " if \"/\" in file_name:\n", " os.makedirs(file_path.rsplit(\"/\", 1)[0], exist_ok=True)\n", " if not os.path.isfile(file_path):\n", " file_url = base_url + file_name\n", " print(f\"Downloading {file_url}...\")\n", " try:\n", " urllib.request.urlretrieve(file_url, file_path)\n", " except HTTPError as e:\n", " print(\n", " \"Something went wrong. Please try to download the file from the GDrive folder,\"\n", " \" or contact the author with the full output including the following error:\\n\",\n", " e,\n", " )"]}, {"cell_type": "markdown", "id": "bd67c270", "metadata": {"papermill": {"duration": 0.006965, "end_time": "2025-04-03T19:21:59.393756", "exception": false, "start_time": "2025-04-03T19:21:59.386791", "status": "completed"}, "tags": []}, "source": ["## Graph Neural Networks"]}, {"cell_type": "markdown", "id": "b2d1935f", "metadata": {"papermill": {"duration": 0.006798, "end_time": "2025-04-03T19:21:59.407389", "exception": false, "start_time": "2025-04-03T19:21:59.400591", "status": "completed"}, "tags": []}, "source": ["### Graph representation\n", "\n", "Before starting the discussion of specific neural network operations on graphs, we should consider how to represent a graph.\n", "Mathematically, a graph $\\mathcal{G}$ is defined as a tuple of a set of nodes/vertices $V$, and a set of edges/links $E$: $\\mathcal{G}=(V,E)$.\n", "Each edge is a pair of two vertices, and represents a connection between them.\n", "For instance, let's look at the following graph:\n", "\n", "![](\"https://github.com/Lightning-AI/lightning-tutorials/raw/main/course_UvA-DL/06-graph-neural-networks/example_graph.svg\")
\n", "\n", "The vertices are $V=\\{1,2,3,4\\}$, and edges $E=\\{(1,2), (2,3), (2,4), (3,4)\\}$.\n", "Note that for simplicity, we assume the graph to be undirected and hence don't add mirrored pairs like $(2,1)$.\n", "In application, vertices and edge can often have specific attributes, and edges can even be directed.\n", "The question is how we could represent this diversity in an efficient way for matrix operations.\n", "Usually, for the edges, we decide between two variants: an adjacency matrix, or a list of paired vertex indices.\n", "\n", "The **adjacency matrix** $A$ is a square matrix whose elements indicate whether pairs of vertices are adjacent,\n", "i.e. connected, or not.\n", "In the simplest case, $A_{ij}$ is 1 if there is a connection from node $i$ to $j$, and otherwise 0.\n", "If we have edge attributes or different categories of edges in a graph, this information can be added to the matrix as well.\n", "For an undirected graph, keep in mind that $A$ is a symmetric matrix ($A_{ij}=A_{ji}$).\n", "For the example graph above, we have the following adjacency matrix:\n", "\n", "$$\n", "A = \\begin{bmatrix}\n", " 0 & 1 & 0 & 0\\\\\n", " 1 & 0 & 1 & 1\\\\\n", " 0 & 1 & 0 & 1\\\\\n", " 0 & 1 & 1 & 0\n", "\\end{bmatrix}\n", "$$\n", "\n", "While expressing a graph as a list of edges is more efficient in terms of memory and (possibly) computation,\n", "using an adjacency matrix is more intuitive and simpler to implement.\n", "In our implementations below, we will rely on the adjacency matrix to keep the code simple.\n", "However, common libraries use edge lists, which we will discuss later more.\n", "Alternatively, we could also use the list of edges to define a sparse adjacency matrix with which we can work\n", "as if it was a dense matrix, but allows more memory-efficient operations.\n", "PyTorch supports this with the sub-package `torch.sparse`\n", "([documentation](https://pytorch.org/docs/stable/sparse.html)) which is however still in a beta-stage\n", "(API might change in future)."]}, {"cell_type": "markdown", "id": "9925346f", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.00675, "end_time": "2025-04-03T19:21:59.420952", "exception": false, "start_time": "2025-04-03T19:21:59.414202", "status": "completed"}, "tags": []}, "source": ["### Graph Convolutions\n", "\n", "Graph Convolutional Networks have been introduced by [Kipf et al. ](https://openreview.net/pdf?id=SJU4ayYgl)\n", "in 2016 at the University of Amsterdam.\n", "He also wrote a great [blog post](https://tkipf.github.io/graph-convolutional-networks/) about this topic,\n", "which is recommended if you want to read about GCNs from a different perspective.\n", "GCNs are similar to convolutions in images in the sense that the \"filter\" parameters are typically shared over all locations in the graph.\n", "At the same time, GCNs rely on message passing methods, which means that vertices exchange information with the neighbors,\n", "and send \"messages\" to each other.\n", "Before looking at the math, we can try to visually understand how GCNs work.\n", "The first step is that each node creates a feature vector that represents the message it wants to send to all its neighbors.\n", "In the second step, the messages are sent to the neighbors, so that a node receives one message per adjacent node.\n", "Below we have visualized the two steps for our example graph.\n", "\n", "![](\"https://github.com/Lightning-AI/lightning-tutorials/raw/main/course_UvA-DL/06-graph-neural-networks/graph_message_passing.svg\")
\n", "\n", "If we want to formulate that in more mathematical terms, we need to first decide how to combine\n", "all the messages a node receives.\n", "As the number of messages vary across nodes, we need an operation that works for any number.\n", "Hence, the usual way to go is to sum or take the mean.\n", "Given the previous features of nodes $H^{(l)}$, the GCN layer is defined as follows:\n", "\n", "$$H^{(l+1)} = \\sigma\\left(\\hat{D}^{-1/2}\\hat{A}\\hat{D}^{-1/2}H^{(l)}W^{(l)}\\right)$$\n", "\n", "$W^{(l)}$ is the weight parameters with which we transform the input features into messages ($H^{(l)}W^{(l)}$).\n", "To the adjacency matrix $A$ we add the identity matrix so that each node sends its own message also to itself:\n", "$\\hat{A}=A+I$.\n", "Finally, to take the average instead of summing, we calculate the matrix $\\hat{D}$ which is a diagonal\n", "matrix with $D_{ii}$ denoting the number of neighbors node $i$ has.\n", "$\\sigma$ represents an arbitrary activation function, and not necessarily the sigmoid (usually a ReLU-based\n", "activation function is used in GNNs).\n", "\n", "When implementing the GCN layer in PyTorch, we can take advantage of the flexible operations on tensors.\n", "Instead of defining a matrix $\\hat{D}$, we can simply divide the summed messages by the number of neighbors afterward.\n", "Additionally, we replace the weight matrix with a linear layer, which additionally allows us to add a bias.\n", "Written as a PyTorch module, the GCN layer is defined as follows:"]}, {"cell_type": "code", "execution_count": 4, "id": "b6a4e131", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:21:59.436271Z", "iopub.status.busy": "2025-04-03T19:21:59.435883Z", "iopub.status.idle": "2025-04-03T19:21:59.443345Z", "shell.execute_reply": "2025-04-03T19:21:59.442526Z"}, "papermill": {"duration": 0.016839, "end_time": "2025-04-03T19:21:59.444584", "exception": false, "start_time": "2025-04-03T19:21:59.427745", "status": "completed"}, "tags": []}, "outputs": [], "source": ["class GCNLayer(nn.Module):\n", " def __init__(self, c_in, c_out):\n", " super().__init__()\n", " self.projection = nn.Linear(c_in, c_out)\n", "\n", " def forward(self, node_feats, adj_matrix):\n", " \"\"\"Forward.\n", "\n", " Args:\n", " node_feats: Tensor with node features of shape [batch_size, num_nodes, c_in]\n", " adj_matrix: Batch of adjacency matrices of the graph. If there is an edge from i to j,\n", " adj_matrix[b,i,j]=1 else 0. Supports directed edges by non-symmetric matrices.\n", " Assumes to already have added the identity connections.\n", " Shape: [batch_size, num_nodes, num_nodes]\n", "\n", " \"\"\"\n", " # Num neighbours = number of incoming edges\n", " num_neighbours = adj_matrix.sum(dim=-1, keepdims=True)\n", " node_feats = self.projection(node_feats)\n", " node_feats = torch.bmm(adj_matrix, node_feats)\n", " node_feats = node_feats / num_neighbours\n", " return node_feats"]}, {"cell_type": "markdown", "id": "a9f5d93d", "metadata": {"papermill": {"duration": 0.006811, "end_time": "2025-04-03T19:21:59.458251", "exception": false, "start_time": "2025-04-03T19:21:59.451440", "status": "completed"}, "tags": []}, "source": ["To further understand the GCN layer, we can apply it to our example graph above.\n", "First, let's specify some node features and the adjacency matrix with added self-connections:"]}, {"cell_type": "code", "execution_count": 5, "id": "6dbc7cb5", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:21:59.473234Z", "iopub.status.busy": "2025-04-03T19:21:59.472888Z", "iopub.status.idle": "2025-04-03T19:21:59.505067Z", "shell.execute_reply": "2025-04-03T19:21:59.504055Z"}, "papermill": {"duration": 0.041318, "end_time": "2025-04-03T19:21:59.506382", "exception": false, "start_time": "2025-04-03T19:21:59.465064", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Node features:\n", " tensor([[[0., 1.],\n", " [2., 3.],\n", " [4., 5.],\n", " [6., 7.]]])\n", "\n", "Adjacency matrix:\n", " tensor([[[1., 1., 0., 0.],\n", " [1., 1., 1., 1.],\n", " [0., 1., 1., 1.],\n", " [0., 1., 1., 1.]]])\n"]}], "source": ["node_feats = torch.arange(8, dtype=torch.float32).view(1, 4, 2)\n", "adj_matrix = Tensor([[[1, 1, 0, 0], [1, 1, 1, 1], [0, 1, 1, 1], [0, 1, 1, 1]]])\n", "\n", "print(\"Node features:\\n\", node_feats)\n", "print(\"\\nAdjacency matrix:\\n\", adj_matrix)"]}, {"cell_type": "markdown", "id": "50f6d0df", "metadata": {"papermill": {"duration": 0.006886, "end_time": "2025-04-03T19:21:59.520307", "exception": false, "start_time": "2025-04-03T19:21:59.513421", "status": "completed"}, "tags": []}, "source": ["Next, let's apply a GCN layer to it.\n", "For simplicity, we initialize the linear weight matrix as an identity matrix so that the input features are equal to the messages.\n", "This makes it easier for us to verify the message passing operation."]}, {"cell_type": "code", "execution_count": 6, "id": "b4db73ba", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:21:59.535545Z", "iopub.status.busy": "2025-04-03T19:21:59.535199Z", "iopub.status.idle": "2025-04-03T19:21:59.546319Z", "shell.execute_reply": "2025-04-03T19:21:59.545367Z"}, "papermill": {"duration": 0.020414, "end_time": "2025-04-03T19:21:59.547626", "exception": false, "start_time": "2025-04-03T19:21:59.527212", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Adjacency matrix tensor([[[1., 1., 0., 0.],\n", " [1., 1., 1., 1.],\n", " [0., 1., 1., 1.],\n", " [0., 1., 1., 1.]]])\n", "Input features tensor([[[0., 1.],\n", " [2., 3.],\n", " [4., 5.],\n", " [6., 7.]]])\n", "Output features tensor([[[1., 2.],\n", " [3., 4.],\n", " [4., 5.],\n", " [4., 5.]]])\n"]}], "source": ["layer = GCNLayer(c_in=2, c_out=2)\n", "layer.projection.weight.data = Tensor([[1.0, 0.0], [0.0, 1.0]])\n", "layer.projection.bias.data = Tensor([0.0, 0.0])\n", "\n", "with torch.no_grad():\n", " out_feats = layer(node_feats, adj_matrix)\n", "\n", "print(\"Adjacency matrix\", adj_matrix)\n", "print(\"Input features\", node_feats)\n", "print(\"Output features\", out_feats)"]}, {"cell_type": "markdown", "id": "d8ba2efa", "metadata": {"papermill": {"duration": 0.006979, "end_time": "2025-04-03T19:21:59.561656", "exception": false, "start_time": "2025-04-03T19:21:59.554677", "status": "completed"}, "tags": []}, "source": ["As we can see, the first node's output values are the average of itself and the second node.\n", "Similarly, we can verify all other nodes.\n", "However, in a GNN, we would also want to allow feature exchange between nodes beyond its neighbors.\n", "This can be achieved by applying multiple GCN layers, which gives us the final layout of a GNN.\n", "The GNN can be build up by a sequence of GCN layers and non-linearities such as ReLU.\n", "For a visualization, see below (figure credit - [Thomas Kipf, 2016](https://tkipf.github.io/graph-convolutional-networks/)).\n", "\n", "![](\"https://github.com/Lightning-AI/lightning-tutorials/raw/main/course_UvA-DL/06-graph-neural-networks/gcn_network.png\")
\n", "\n", "However, one issue we can see from looking at the example above is that the output features for nodes 3 and 4 are\n", "the same because they have the same adjacent nodes (including itself).\n", "Therefore, GCN layers can make the network forget node-specific information if we just take a mean over all messages.\n", "Multiple possible improvements have been proposed.\n", "While the simplest option might be using residual connections, the more common approach is to either weigh\n", "the self-connections higher or define a separate weight matrix for the self-connections.\n", "Alternatively, we can use a well-known concept: attention."]}, {"cell_type": "markdown", "id": "325d6c13", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.007025, "end_time": "2025-04-03T19:21:59.575676", "exception": false, "start_time": "2025-04-03T19:21:59.568651", "status": "completed"}, "tags": []}, "source": ["### Graph Attention\n", "\n", "Attention describes a weighted average of multiple elements with the weights dynamically computed based on an input\n", "query and elements' keys (if you don't know what attention is, it is recommended to at least go through\n", "the very first section called [What is Attention?](https://uvadlc-notebooks.readthedocs.io/en/latest/tutorial_notebooks/tutorial6/Transformers_and_MHAttention.html#What-is-Attention?)).\n", "This concept can be similarly applied to graphs, one of such is the Graph Attention Network\n", "(called GAT, proposed by [Velickovic et al., 2017](https://arxiv.org/abs/1710.10903)).\n", "Similarly to the GCN, the graph attention layer creates a message for each node using a linear layer/weight matrix.\n", "For the attention part, it uses the message from the node itself as a query, and the messages to average as both\n", "keys and values (note that this also includes the message to itself).\n", "The score function $f_{attn}$ is implemented as a one-layer MLP which maps the query and key to a single value.\n", "The MLP looks as follows (figure credit - [Velickovic et al. ](https://arxiv.org/abs/1710.10903)):\n", "\n", "![](\"https://github.com/Lightning-AI/lightning-tutorials/raw/main/course_UvA-DL/06-graph-neural-networks/graph_attention_MLP.svg\")
\n", "\n", "$h_i$ and $h_j$ are the original features from node $i$ and $j$ respectively, and represent the messages\n", "of the layer with $\\mathbf{W}$ as weight matrix.\n", "$\\mathbf{a}$ is the weight matrix of the MLP, which has the shape $[1,2\\times d_{\\text{message}}]$,\n", "and $\\alpha_{ij}$ the final attention weight from node $i$ to $j$.\n", "The calculation can be described as follows:\n", "\n", "$$\\alpha_{ij} = \\frac{\\exp\\left(\\text{LeakyReLU}\\left(\\mathbf{a}\\left[\\mathbf{W}h_i||\\mathbf{W}h_j\\right]\\right)\\right)}{\\sum_{k\\in\\mathcal{N}_i} \\exp\\left(\\text{LeakyReLU}\\left(\\mathbf{a}\\left[\\mathbf{W}h_i||\\mathbf{W}h_k\\right]\\right)\\right)}$$\n", "\n", "The operator $||$ represents the concatenation, and $\\mathcal{N}_i$ the indices of the neighbors of node $i$.\n", "Note that in contrast to usual practice, we apply a non-linearity (here LeakyReLU) before the softmax over elements.\n", "Although it seems like a minor change at first, it is crucial for the attention to depend on the original input.\n", "Specifically, let's remove the non-linearity for a second, and try to simplify the expression:\n", "\n", "$$\n", "\\begin{split}\n", " \\alpha_{ij} & = \\frac{\\exp\\left(\\mathbf{a}\\left[\\mathbf{W}h_i||\\mathbf{W}h_j\\right]\\right)}{\\sum_{k\\in\\mathcal{N}_i} \\exp\\left(\\mathbf{a}\\left[\\mathbf{W}h_i||\\mathbf{W}h_k\\right]\\right)}\\\\[5pt]\n", " & = \\frac{\\exp\\left(\\mathbf{a}_{:,:d/2}\\mathbf{W}h_i+\\mathbf{a}_{:,d/2:}\\mathbf{W}h_j\\right)}{\\sum_{k\\in\\mathcal{N}_i} \\exp\\left(\\mathbf{a}_{:,:d/2}\\mathbf{W}h_i+\\mathbf{a}_{:,d/2:}\\mathbf{W}h_k\\right)}\\\\[5pt]\n", " & = \\frac{\\exp\\left(\\mathbf{a}_{:,:d/2}\\mathbf{W}h_i\\right)\\cdot\\exp\\left(\\mathbf{a}_{:,d/2:}\\mathbf{W}h_j\\right)}{\\sum_{k\\in\\mathcal{N}_i} \\exp\\left(\\mathbf{a}_{:,:d/2}\\mathbf{W}h_i\\right)\\cdot\\exp\\left(\\mathbf{a}_{:,d/2:}\\mathbf{W}h_k\\right)}\\\\[5pt]\n", " & = \\frac{\\exp\\left(\\mathbf{a}_{:,d/2:}\\mathbf{W}h_j\\right)}{\\sum_{k\\in\\mathcal{N}_i} \\exp\\left(\\mathbf{a}_{:,d/2:}\\mathbf{W}h_k\\right)}\\\\\n", "\\end{split}\n", "$$\n", "\n", "We can see that without the non-linearity, the attention term with $h_i$ actually cancels itself out,\n", "resulting in the attention being independent of the node itself.\n", "Hence, we would have the same issue as the GCN of creating the same output features for nodes with the same neighbors.\n", "This is why the LeakyReLU is crucial and adds some dependency on $h_i$ to the attention.\n", "\n", "Once we obtain all attention factors, we can calculate the output features for each node by performing\n", "the weighted average:\n", "\n", "$$h_i'=\\sigma\\left(\\sum_{j\\in\\mathcal{N}_i}\\alpha_{ij}\\mathbf{W}h_j\\right)$$\n", "\n", "$\\sigma$ is yet another non-linearity, as in the GCN layer.\n", "Visually, we can represent the full message passing in an attention layer as follows\n", "(figure credit - [Velickovic et al. ](https://arxiv.org/abs/1710.10903)):\n", "\n", "![](\"https://github.com/Lightning-AI/lightning-tutorials/raw/main/course_UvA-DL/06-graph-neural-networks/graph_attention.jpeg\")
\n", "\n", "To increase the expressiveness of the graph attention network, [Velickovic et al. ](https://arxiv.org/abs/1710.10903)\n", "proposed to extend it to multiple heads similar to the Multi-Head Attention block in Transformers.\n", "This results in $N$ attention layers being applied in parallel.\n", "In the image above, it is visualized as three different colors of arrows (green, blue, and purple)\n", "that are afterward concatenated.\n", "The average is only applied for the very final prediction layer in a network.\n", "\n", "After having discussed the graph attention layer in detail, we can implement it below:"]}, {"cell_type": "code", "execution_count": 7, "id": "41891a93", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:21:59.591652Z", "iopub.status.busy": "2025-04-03T19:21:59.590829Z", "iopub.status.idle": "2025-04-03T19:21:59.610871Z", "shell.execute_reply": "2025-04-03T19:21:59.609922Z"}, "papermill": {"duration": 0.029426, "end_time": "2025-04-03T19:21:59.612131", "exception": false, "start_time": "2025-04-03T19:21:59.582705", "status": "completed"}, "tags": []}, "outputs": [], "source": ["class GATLayer(nn.Module):\n", " def __init__(self, c_in, c_out, num_heads=1, concat_heads=True, alpha=0.2):\n", " \"\"\"\n", " Args:\n", " c_in: Dimensionality of input features\n", " c_out: Dimensionality of output features\n", " num_heads: Number of heads, i.e. attention mechanisms to apply in parallel. The\n", " output features are equally split up over the heads if concat_heads=True.\n", " concat_heads: If True, the output of the different heads is concatenated instead of averaged.\n", " alpha: Negative slope of the LeakyReLU activation.\n", " \"\"\"\n", " super().__init__()\n", " self.num_heads = num_heads\n", " self.concat_heads = concat_heads\n", " if self.concat_heads:\n", " assert c_out % num_heads == 0, \"Number of output features must be a multiple of the count of heads.\"\n", " c_out = c_out // num_heads\n", "\n", " # Sub-modules and parameters needed in the layer\n", " self.projection = nn.Linear(c_in, c_out * num_heads)\n", " self.a = nn.Parameter(Tensor(num_heads, 2 * c_out)) # One per head\n", " self.leakyrelu = nn.LeakyReLU(alpha)\n", "\n", " # Initialization from the original implementation\n", " nn.init.xavier_uniform_(self.projection.weight.data, gain=1.414)\n", " nn.init.xavier_uniform_(self.a.data, gain=1.414)\n", "\n", " def forward(self, node_feats, adj_matrix, print_attn_probs=False):\n", " \"\"\"Forward.\n", "\n", " Args:\n", " node_feats: Input features of the node. Shape: [batch_size, c_in]\n", " adj_matrix: Adjacency matrix including self-connections. Shape: [batch_size, num_nodes, num_nodes]\n", " print_attn_probs: If True, the attention weights are printed during the forward pass\n", " (for debugging purposes)\n", "\n", " \"\"\"\n", " batch_size, num_nodes = node_feats.size(0), node_feats.size(1)\n", "\n", " # Apply linear layer and sort nodes by head\n", " node_feats = self.projection(node_feats)\n", " node_feats = node_feats.view(batch_size, num_nodes, self.num_heads, -1)\n", "\n", " # We need to calculate the attention logits for every edge in the adjacency matrix\n", " # Doing this on all possible combinations of nodes is very expensive\n", " # => Create a tensor of [W*h_i||W*h_j] with i and j being the indices of all edges\n", " # Returns indices where the adjacency matrix is not 0 => edges\n", " edges = adj_matrix.nonzero(as_tuple=False)\n", " node_feats_flat = node_feats.view(batch_size * num_nodes, self.num_heads, -1)\n", " edge_indices_row = edges[:, 0] * num_nodes + edges[:, 1]\n", " edge_indices_col = edges[:, 0] * num_nodes + edges[:, 2]\n", " a_input = torch.cat(\n", " [\n", " torch.index_select(input=node_feats_flat, index=edge_indices_row, dim=0),\n", " torch.index_select(input=node_feats_flat, index=edge_indices_col, dim=0),\n", " ],\n", " dim=-1,\n", " ) # Index select returns a tensor with node_feats_flat being indexed at the desired positions\n", "\n", " # Calculate attention MLP output (independent for each head)\n", " attn_logits = torch.einsum(\"bhc,hc->bh\", a_input, self.a)\n", " attn_logits = self.leakyrelu(attn_logits)\n", "\n", " # Map list of attention values back into a matrix\n", " attn_matrix = attn_logits.new_zeros(adj_matrix.shape + (self.num_heads,)).fill_(-9e15)\n", " attn_matrix[adj_matrix[..., None].repeat(1, 1, 1, self.num_heads) == 1] = attn_logits.reshape(-1)\n", "\n", " # Weighted average of attention\n", " attn_probs = F.softmax(attn_matrix, dim=2)\n", " if print_attn_probs:\n", " print(\"Attention probs\\n\", attn_probs.permute(0, 3, 1, 2))\n", " node_feats = torch.einsum(\"bijh,bjhc->bihc\", attn_probs, node_feats)\n", "\n", " # If heads should be concatenated, we can do this by reshaping. Otherwise, take mean\n", " if self.concat_heads:\n", " node_feats = node_feats.reshape(batch_size, num_nodes, -1)\n", " else:\n", " node_feats = node_feats.mean(dim=2)\n", "\n", " return node_feats"]}, {"cell_type": "markdown", "id": "3bc437e7", "metadata": {"papermill": {"duration": 0.007035, "end_time": "2025-04-03T19:21:59.626339", "exception": false, "start_time": "2025-04-03T19:21:59.619304", "status": "completed"}, "tags": []}, "source": ["Again, we can apply the graph attention layer on our example graph above to understand the dynamics better.\n", "As before, the input layer is initialized as an identity matrix, but we set $\\mathbf{a}$\n", "to be a vector of arbitrary numbers to obtain different attention values.\n", "We use two heads to show the parallel, independent attention mechanisms working in the layer."]}, {"cell_type": "code", "execution_count": 8, "id": "3465a38b", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:21:59.642295Z", "iopub.status.busy": "2025-04-03T19:21:59.641430Z", "iopub.status.idle": "2025-04-03T19:21:59.656213Z", "shell.execute_reply": "2025-04-03T19:21:59.655257Z"}, "papermill": {"duration": 0.024234, "end_time": "2025-04-03T19:21:59.657572", "exception": false, "start_time": "2025-04-03T19:21:59.633338", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Attention probs\n", " tensor([[[[0.3543, 0.6457, 0.0000, 0.0000],\n", " [0.1096, 0.1450, 0.2642, 0.4813],\n", " [0.0000, 0.1858, 0.2885, 0.5257],\n", " [0.0000, 0.2391, 0.2696, 0.4913]],\n", "\n", " [[0.5100, 0.4900, 0.0000, 0.0000],\n", " [0.2975, 0.2436, 0.2340, 0.2249],\n", " [0.0000, 0.3838, 0.3142, 0.3019],\n", " [0.0000, 0.4018, 0.3289, 0.2693]]]])\n", "Adjacency matrix tensor([[[1., 1., 0., 0.],\n", " [1., 1., 1., 1.],\n", " [0., 1., 1., 1.],\n", " [0., 1., 1., 1.]]])\n", "Input features tensor([[[0., 1.],\n", " [2., 3.],\n", " [4., 5.],\n", " [6., 7.]]])\n", "Output features tensor([[[1.2913, 1.9800],\n", " [4.2344, 3.7725],\n", " [4.6798, 4.8362],\n", " [4.5043, 4.7351]]])\n"]}], "source": ["layer = GATLayer(2, 2, num_heads=2)\n", "layer.projection.weight.data = Tensor([[1.0, 0.0], [0.0, 1.0]])\n", "layer.projection.bias.data = Tensor([0.0, 0.0])\n", "layer.a.data = Tensor([[-0.2, 0.3], [0.1, -0.1]])\n", "\n", "with torch.no_grad():\n", " out_feats = layer(node_feats, adj_matrix, print_attn_probs=True)\n", "\n", "print(\"Adjacency matrix\", adj_matrix)\n", "print(\"Input features\", node_feats)\n", "print(\"Output features\", out_feats)"]}, {"cell_type": "markdown", "id": "fe6b5e45", "metadata": {"papermill": {"duration": 0.007309, "end_time": "2025-04-03T19:21:59.692677", "exception": false, "start_time": "2025-04-03T19:21:59.685368", "status": "completed"}, "tags": []}, "source": ["We recommend that you try to calculate the attention matrix at least for one head and one node for yourself.\n", "The entries are 0 where there does not exist an edge between $i$ and $j$.\n", "For the others, we see a diverse set of attention probabilities.\n", "Moreover, the output features of node 3 and 4 are now different although they have the same neighbors."]}, {"cell_type": "markdown", "id": "97fcc7d8", "metadata": {"papermill": {"duration": 0.007067, "end_time": "2025-04-03T19:21:59.706912", "exception": false, "start_time": "2025-04-03T19:21:59.699845", "status": "completed"}, "tags": []}, "source": ["## PyTorch Geometric\n", "\n", "We had mentioned before that implementing graph networks with adjacency matrix is simple and straight-forward\n", "but can be computationally expensive for large graphs.\n", "Many real-world graphs can reach over 200k nodes, for which adjacency matrix-based implementations fail.\n", "There are a lot of optimizations possible when implementing GNNs, and luckily, there exist packages that provide such layers.\n", "The most popular packages for PyTorch are [PyTorch Geometric](https://pytorch-geometric.readthedocs.io/en/latest/)\n", "and the [Deep Graph Library](https://www.dgl.ai/) (the latter being actually framework agnostic).\n", "Which one to use depends on the project you are planning to do and personal taste.\n", "In this tutorial, we will look at PyTorch Geometric as part of the PyTorch family.\n", "\n", "PyTorch Geometric provides us a set of common graph layers, including the GCN and GAT layer we implemented above.\n", "Additionally, similar to PyTorch's torchvision, it provides the common graph datasets and transformations\n", "on those to simplify training.\n", "Compared to our implementation above, PyTorch Geometric uses a list of index pairs to represent the edges.\n", "The details of this library will be explored further in our experiments.\n", "\n", "In our tasks below, we want to allow us to pick from a multitude of graph layers.\n", "Thus, we define again below a dictionary to access those using a string:"]}, {"cell_type": "code", "execution_count": 9, "id": "44ab8ce0", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:21:59.726726Z", "iopub.status.busy": "2025-04-03T19:21:59.725764Z", "iopub.status.idle": "2025-04-03T19:21:59.730673Z", "shell.execute_reply": "2025-04-03T19:21:59.729822Z"}, "papermill": {"duration": 0.018013, "end_time": "2025-04-03T19:21:59.732035", "exception": false, "start_time": "2025-04-03T19:21:59.714022", "status": "completed"}, "tags": []}, "outputs": [], "source": ["gnn_layer_by_name = {\"GCN\": geom_nn.GCNConv, \"GAT\": geom_nn.GATConv, \"GraphConv\": geom_nn.GraphConv}"]}, {"cell_type": "markdown", "id": "3c1f22c4", "metadata": {"papermill": {"duration": 0.007169, "end_time": "2025-04-03T19:21:59.746904", "exception": false, "start_time": "2025-04-03T19:21:59.739735", "status": "completed"}, "tags": []}, "source": ["Additionally to GCN and GAT, we added the layer `geom_nn.GraphConv`\n", "([documentation](https://pytorch-geometric.readthedocs.io/en/latest/modules/nn.html#torch_geometric.nn.conv.GraphConv)).\n", "GraphConv is a GCN with a separate weight matrix for the self-connections.\n", "Mathematically, this would be:\n", "\n", "$$\n", "\\mathbf{x}_i^{(l+1)} = \\mathbf{W}^{(l + 1)}_1 \\mathbf{x}_i^{(l)} + \\mathbf{W}^{(\\ell + 1)}_2 \\sum_{j \\in \\mathcal{N}_i} \\mathbf{x}_j^{(l)}\n", "$$\n", "\n", "In this formula, the neighbor's messages are added instead of averaged.\n", "However, PyTorch Geometric provides the argument `aggr` to switch between summing, averaging, and max pooling."]}, {"cell_type": "markdown", "id": "7350c5ff", "metadata": {"papermill": {"duration": 0.007176, "end_time": "2025-04-03T19:21:59.761255", "exception": false, "start_time": "2025-04-03T19:21:59.754079", "status": "completed"}, "tags": []}, "source": ["## Experiments on graph structures\n", "\n", "\n", "\n", "Tasks on graph-structured data can be grouped into three groups: node-level, edge-level and graph-level.\n", "The different levels describe on which level we want to perform classification/regression.\n", "We will discuss all three types in more detail below."]}, {"cell_type": "markdown", "id": "5096a65d", "metadata": {"papermill": {"duration": 0.007162, "end_time": "2025-04-03T19:21:59.775661", "exception": false, "start_time": "2025-04-03T19:21:59.768499", "status": "completed"}, "tags": []}, "source": ["### Node-level tasks: Semi-supervised node classification\n", "\n", "Node-level tasks have the goal to classify nodes in a graph.\n", "Usually, we have given a single, large graph with >1000 nodes of which a certain amount of nodes are labeled.\n", "We learn to classify those labeled examples during training and try to generalize to the unlabeled nodes.\n", "\n", "A popular example that we will use in this tutorial is the Cora dataset, a citation network among papers.\n", "The Cora consists of 2708 scientific publications with links between each other representing\n", "the citation of one paper by another.\n", "The task is to classify each publication into one of seven classes.\n", "Each publication is represented by a bag-of-words vector.\n", "This means that we have a vector of 1433 elements for each publication, where a 1 at feature $i$ indicates\n", "that the $i$-th word of a pre-defined dictionary is in the article.\n", "Binary bag-of-words representations are commonly used when we need very simple encodings,\n", "and already have an intuition of what words to expect in a network.\n", "There exist much better approaches, but we will leave this to the NLP courses to discuss.\n", "\n", "We will load the dataset below:"]}, {"cell_type": "code", "execution_count": 10, "id": "d82ce731", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:21:59.792281Z", "iopub.status.busy": "2025-04-03T19:21:59.791488Z", "iopub.status.idle": "2025-04-03T19:22:01.561583Z", "shell.execute_reply": "2025-04-03T19:22:01.560406Z"}, "papermill": {"duration": 1.779643, "end_time": "2025-04-03T19:22:01.562805", "exception": false, "start_time": "2025-04-03T19:21:59.783162", "status": "completed"}, "tags": []}, "outputs": [{"name": "stderr", "output_type": "stream", "text": ["Downloading https://github.com/kimiyoung/planetoid/raw/master/data/ind.cora.x\n", "Downloading https://github.com/kimiyoung/planetoid/raw/master/data/ind.cora.tx\n"]}, {"name": "stderr", "output_type": "stream", "text": ["Downloading https://github.com/kimiyoung/planetoid/raw/master/data/ind.cora.allx\n"]}, {"name": "stderr", "output_type": "stream", "text": ["Downloading https://github.com/kimiyoung/planetoid/raw/master/data/ind.cora.y\n", "Downloading https://github.com/kimiyoung/planetoid/raw/master/data/ind.cora.ty\n"]}, {"name": "stderr", "output_type": "stream", "text": ["Downloading https://github.com/kimiyoung/planetoid/raw/master/data/ind.cora.ally\n", "Downloading https://github.com/kimiyoung/planetoid/raw/master/data/ind.cora.graph\n"]}, {"name": "stderr", "output_type": "stream", "text": ["Downloading https://github.com/kimiyoung/planetoid/raw/master/data/ind.cora.test.index\n", "Processing...\n"]}, {"name": "stderr", "output_type": "stream", "text": ["Done!\n"]}], "source": ["cora_dataset = torch_geometric.datasets.Planetoid(root=DATASET_PATH, name=\"Cora\")"]}, {"cell_type": "markdown", "id": "a3b086a5", "metadata": {"papermill": {"duration": 0.007472, "end_time": "2025-04-03T19:22:01.578010", "exception": false, "start_time": "2025-04-03T19:22:01.570538", "status": "completed"}, "tags": []}, "source": ["Let's look at how PyTorch Geometric represents the graph data.\n", "Note that although we have a single graph, PyTorch Geometric returns a dataset for compatibility to other datasets."]}, {"cell_type": "code", "execution_count": 11, "id": "c557a23a", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:01.594423Z", "iopub.status.busy": "2025-04-03T19:22:01.594156Z", "iopub.status.idle": "2025-04-03T19:22:01.603781Z", "shell.execute_reply": "2025-04-03T19:22:01.602874Z"}, "papermill": {"duration": 0.019606, "end_time": "2025-04-03T19:22:01.605094", "exception": false, "start_time": "2025-04-03T19:22:01.585488", "status": "completed"}, "tags": []}, "outputs": [{"data": {"text/plain": ["Data(x=[2708, 1433], edge_index=[2, 10556], y=[2708], train_mask=[2708], val_mask=[2708], test_mask=[2708])"]}, "execution_count": 11, "metadata": {}, "output_type": "execute_result"}], "source": ["cora_dataset[0]"]}, {"cell_type": "markdown", "id": "da97a38f", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.007506, "end_time": "2025-04-03T19:22:01.620221", "exception": false, "start_time": "2025-04-03T19:22:01.612715", "status": "completed"}, "tags": []}, "source": ["The graph is represented by a `Data` object\n", "([documentation](https://pytorch-geometric.readthedocs.io/en/latest/modules/data.html#torch_geometric.data.Data))\n", "which we can access as a standard Python namespace.\n", "The edge index tensor is the list of edges in the graph and contains the mirrored version of each edge for undirected graphs.\n", "The `train_mask`, `val_mask`, and `test_mask` are boolean masks that indicate which nodes we should use for training,\n", "validation, and testing.\n", "The `x` tensor is the feature tensor of our 2708 publications, and `y` the labels for all nodes.\n", "\n", "After having seen the data, we can implement a simple graph neural network.\n", "The GNN applies a sequence of graph layers (GCN, GAT, or GraphConv), ReLU as activation function,\n", "and dropout for regularization.\n", "See below for the specific implementation."]}, {"cell_type": "code", "execution_count": 12, "id": "52007ffd", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:01.637214Z", "iopub.status.busy": "2025-04-03T19:22:01.636376Z", "iopub.status.idle": "2025-04-03T19:22:01.644777Z", "shell.execute_reply": "2025-04-03T19:22:01.643728Z"}, "lines_to_next_cell": 2, "papermill": {"duration": 0.018417, "end_time": "2025-04-03T19:22:01.646212", "exception": false, "start_time": "2025-04-03T19:22:01.627795", "status": "completed"}, "tags": []}, "outputs": [], "source": ["class GNNModel(nn.Module):\n", " def __init__(\n", " self,\n", " c_in,\n", " c_hidden,\n", " c_out,\n", " num_layers=2,\n", " layer_name=\"GCN\",\n", " dp_rate=0.1,\n", " **kwargs,\n", " ):\n", " \"\"\"GNNModel.\n", "\n", " Args:\n", " c_in: Dimension of input features\n", " c_hidden: Dimension of hidden features\n", " c_out: Dimension of the output features. Usually number of classes in classification\n", " num_layers: Number of \"hidden\" graph layers\n", " layer_name: String of the graph layer to use\n", " dp_rate: Dropout rate to apply throughout the network\n", " kwargs: Additional arguments for the graph layer (e.g. number of heads for GAT)\n", "\n", " \"\"\"\n", " super().__init__()\n", " gnn_layer = gnn_layer_by_name[layer_name]\n", "\n", " layers = []\n", " in_channels, out_channels = c_in, c_hidden\n", " for l_idx in range(num_layers - 1):\n", " layers += [\n", " gnn_layer(in_channels=in_channels, out_channels=out_channels, **kwargs),\n", " nn.ReLU(inplace=True),\n", " nn.Dropout(dp_rate),\n", " ]\n", " in_channels = c_hidden\n", " layers += [gnn_layer(in_channels=in_channels, out_channels=c_out, **kwargs)]\n", " self.layers = nn.ModuleList(layers)\n", "\n", " def forward(self, x, edge_index):\n", " \"\"\"Forward.\n", "\n", " Args:\n", " x: Input features per node\n", " edge_index: List of vertex index pairs representing the edges in the graph (PyTorch geometric notation)\n", "\n", " \"\"\"\n", " for layer in self.layers:\n", " # For graph layers, we need to add the \"edge_index\" tensor as additional input\n", " # All PyTorch Geometric graph layer inherit the class \"MessagePassing\", hence\n", " # we can simply check the class type.\n", " if isinstance(layer, geom_nn.MessagePassing):\n", " x = layer(x, edge_index)\n", " else:\n", " x = layer(x)\n", " return x"]}, {"cell_type": "markdown", "id": "3696c902", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.007536, "end_time": "2025-04-03T19:22:01.661333", "exception": false, "start_time": "2025-04-03T19:22:01.653797", "status": "completed"}, "tags": []}, "source": ["Good practice in node-level tasks is to create an MLP baseline that is applied to each node independently.\n", "This way we can verify whether adding the graph information to the model indeed improves the prediction, or not.\n", "It might also be that the features per node are already expressive enough to clearly point towards a specific class.\n", "To check this, we implement a simple MLP below."]}, {"cell_type": "code", "execution_count": 13, "id": "fe80a0ac", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:01.677974Z", "iopub.status.busy": "2025-04-03T19:22:01.677627Z", "iopub.status.idle": "2025-04-03T19:22:01.686120Z", "shell.execute_reply": "2025-04-03T19:22:01.685066Z"}, "lines_to_next_cell": 2, "papermill": {"duration": 0.01858, "end_time": "2025-04-03T19:22:01.687492", "exception": false, "start_time": "2025-04-03T19:22:01.668912", "status": "completed"}, "tags": []}, "outputs": [], "source": ["class MLPModel(nn.Module):\n", " def __init__(self, c_in, c_hidden, c_out, num_layers=2, dp_rate=0.1):\n", " \"\"\"MLPModel.\n", "\n", " Args:\n", " c_in: Dimension of input features\n", " c_hidden: Dimension of hidden features\n", " c_out: Dimension of the output features. Usually number of classes in classification\n", " num_layers: Number of hidden layers\n", " dp_rate: Dropout rate to apply throughout the network\n", "\n", " \"\"\"\n", " super().__init__()\n", " layers = []\n", " in_channels, out_channels = c_in, c_hidden\n", " for l_idx in range(num_layers - 1):\n", " layers += [nn.Linear(in_channels, out_channels), nn.ReLU(inplace=True), nn.Dropout(dp_rate)]\n", " in_channels = c_hidden\n", " layers += [nn.Linear(in_channels, c_out)]\n", " self.layers = nn.Sequential(*layers)\n", "\n", " def forward(self, x, *args, **kwargs):\n", " \"\"\"Forward.\n", "\n", " Args:\n", " x: Input features per node\n", "\n", " \"\"\"\n", " return self.layers(x)"]}, {"cell_type": "markdown", "id": "72f8eeb8", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.007579, "end_time": "2025-04-03T19:22:01.702828", "exception": false, "start_time": "2025-04-03T19:22:01.695249", "status": "completed"}, "tags": []}, "source": ["Finally, we can merge the models into a PyTorch Lightning module which handles the training,\n", "validation, and testing for us."]}, {"cell_type": "code", "execution_count": 14, "id": "68646632", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:01.719495Z", "iopub.status.busy": "2025-04-03T19:22:01.719149Z", "iopub.status.idle": "2025-04-03T19:22:01.733210Z", "shell.execute_reply": "2025-04-03T19:22:01.732074Z"}, "lines_to_next_cell": 2, "papermill": {"duration": 0.024191, "end_time": "2025-04-03T19:22:01.734645", "exception": false, "start_time": "2025-04-03T19:22:01.710454", "status": "completed"}, "tags": []}, "outputs": [], "source": ["class NodeLevelGNN(pl.LightningModule):\n", " def __init__(self, model_name, **model_kwargs):\n", " super().__init__()\n", " # Saving hyperparameters\n", " self.save_hyperparameters()\n", "\n", " if model_name == \"MLP\":\n", " self.model = MLPModel(**model_kwargs)\n", " else:\n", " self.model = GNNModel(**model_kwargs)\n", " self.loss_module = nn.CrossEntropyLoss()\n", "\n", " def forward(self, data, mode=\"train\"):\n", " x, edge_index = data.x, data.edge_index\n", " x = self.model(x, edge_index)\n", "\n", " # Only calculate the loss on the nodes corresponding to the mask\n", " if mode == \"train\":\n", " mask = data.train_mask\n", " elif mode == \"val\":\n", " mask = data.val_mask\n", " elif mode == \"test\":\n", " mask = data.test_mask\n", " else:\n", " assert False, f\"Unknown forward mode: {mode}\"\n", "\n", " loss = self.loss_module(x[mask], data.y[mask])\n", " acc = (x[mask].argmax(dim=-1) == data.y[mask]).sum().float() / mask.sum()\n", " return loss, acc\n", "\n", " def configure_optimizers(self):\n", " # We use SGD here, but Adam works as well\n", " optimizer = optim.SGD(self.parameters(), lr=0.1, momentum=0.9, weight_decay=2e-3)\n", " return optimizer\n", "\n", " def training_step(self, batch, batch_idx):\n", " loss, acc = self.forward(batch, mode=\"train\")\n", " self.log(\"train_loss\", loss)\n", " self.log(\"train_acc\", acc)\n", " return loss\n", "\n", " def validation_step(self, batch, batch_idx):\n", " _, acc = self.forward(batch, mode=\"val\")\n", " self.log(\"val_acc\", acc)\n", "\n", " def test_step(self, batch, batch_idx):\n", " _, acc = self.forward(batch, mode=\"test\")\n", " self.log(\"test_acc\", acc)"]}, {"cell_type": "markdown", "id": "04cd0fa9", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.007604, "end_time": "2025-04-03T19:22:01.749938", "exception": false, "start_time": "2025-04-03T19:22:01.742334", "status": "completed"}, "tags": []}, "source": ["Additionally to the Lightning module, we define a training function below.\n", "As we have a single graph, we use a batch size of 1 for the data loader and share the same data loader for the train,\n", "validation, and test set (the mask is picked inside the Lightning module).\n", "Besides, we set the argument `enable_progress_bar` to False as it usually shows the progress per epoch,\n", "but an epoch only consists of a single step.\n", "If you have downloaded the pre-trained models in the beginning of the tutorial, we load those instead of training from scratch.\n", "Finally, we test the model and return the results."]}, {"cell_type": "code", "execution_count": 15, "id": "77473f82", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:01.766669Z", "iopub.status.busy": "2025-04-03T19:22:01.766327Z", "iopub.status.idle": "2025-04-03T19:22:01.778269Z", "shell.execute_reply": "2025-04-03T19:22:01.777206Z"}, "lines_to_next_cell": 2, "papermill": {"duration": 0.022117, "end_time": "2025-04-03T19:22:01.779689", "exception": false, "start_time": "2025-04-03T19:22:01.757572", "status": "completed"}, "tags": []}, "outputs": [], "source": ["def train_node_classifier(model_name, dataset, **model_kwargs):\n", " pl.seed_everything(42)\n", " node_data_loader = geom_data.DataLoader(dataset, batch_size=1)\n", "\n", " # Create a PyTorch Lightning trainer\n", " root_dir = os.path.join(CHECKPOINT_PATH, \"NodeLevel\" + model_name)\n", " os.makedirs(root_dir, exist_ok=True)\n", " trainer = pl.Trainer(\n", " default_root_dir=root_dir,\n", " callbacks=[ModelCheckpoint(save_weights_only=True, mode=\"max\", monitor=\"val_acc\")],\n", " accelerator=\"auto\",\n", " devices=AVAIL_GPUS,\n", " max_epochs=200,\n", " enable_progress_bar=False,\n", " ) # 0 because epoch size is 1\n", " trainer.logger._default_hp_metric = None # Optional logging argument that we don't need\n", "\n", " # Check whether pretrained model exists. If yes, load it and skip training\n", " pretrained_filename = os.path.join(CHECKPOINT_PATH, f\"NodeLevel{model_name}.ckpt\")\n", " if os.path.isfile(pretrained_filename):\n", " print(\"Found pretrained model, loading...\")\n", " model = NodeLevelGNN.load_from_checkpoint(pretrained_filename)\n", " else:\n", " pl.seed_everything()\n", " model = NodeLevelGNN(\n", " model_name=model_name, c_in=dataset.num_node_features, c_out=dataset.num_classes, **model_kwargs\n", " )\n", " trainer.fit(model, node_data_loader, node_data_loader)\n", " model = NodeLevelGNN.load_from_checkpoint(trainer.checkpoint_callback.best_model_path)\n", "\n", " # Test best model on the test set\n", " test_result = trainer.test(model, dataloaders=node_data_loader, verbose=False)\n", " batch = next(iter(node_data_loader))\n", " batch = batch.to(model.device)\n", " _, train_acc = model.forward(batch, mode=\"train\")\n", " _, val_acc = model.forward(batch, mode=\"val\")\n", " result = {\"train\": train_acc, \"val\": val_acc, \"test\": test_result[0][\"test_acc\"]}\n", " return model, result"]}, {"cell_type": "markdown", "id": "0f09162b", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.007661, "end_time": "2025-04-03T19:22:01.795226", "exception": false, "start_time": "2025-04-03T19:22:01.787565", "status": "completed"}, "tags": []}, "source": ["Now, we can train our models. First, let's train the simple MLP:"]}, {"cell_type": "code", "execution_count": 16, "id": "6a38625d", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:01.812105Z", "iopub.status.busy": "2025-04-03T19:22:01.811762Z", "iopub.status.idle": "2025-04-03T19:22:01.817971Z", "shell.execute_reply": "2025-04-03T19:22:01.816839Z"}, "papermill": {"duration": 0.016322, "end_time": "2025-04-03T19:22:01.819345", "exception": false, "start_time": "2025-04-03T19:22:01.803023", "status": "completed"}, "tags": []}, "outputs": [], "source": ["# Small function for printing the test scores\n", "def print_results(result_dict):\n", " if \"train\" in result_dict:\n", " print(\"Train accuracy: %4.2f%%\" % (100.0 * result_dict[\"train\"]))\n", " if \"val\" in result_dict:\n", " print(\"Val accuracy: %4.2f%%\" % (100.0 * result_dict[\"val\"]))\n", " print(\"Test accuracy: %4.2f%%\" % (100.0 * result_dict[\"test\"]))"]}, {"cell_type": "code", "execution_count": 17, "id": "e8b055e6", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:01.836127Z", "iopub.status.busy": "2025-04-03T19:22:01.835790Z", "iopub.status.idle": "2025-04-03T19:22:02.750637Z", "shell.execute_reply": "2025-04-03T19:22:02.749552Z"}, "papermill": {"duration": 0.925165, "end_time": "2025-04-03T19:22:02.752219", "exception": false, "start_time": "2025-04-03T19:22:01.827054", "status": "completed"}, "tags": []}, "outputs": [{"name": "stderr", "output_type": "stream", "text": ["Seed set to 42\n"]}, {"name": "stderr", "output_type": "stream", "text": ["/usr/local/lib/python3.10/dist-packages/torch_geometric/deprecation.py:12: UserWarning: 'data.DataLoader' is deprecated, use 'loader.DataLoader' instead\n", " warnings.warn(out)\n", "GPU available: True (cuda), used: True\n"]}, {"name": "stderr", "output_type": "stream", "text": ["TPU available: False, using: 0 TPU cores\n"]}, {"name": "stderr", "output_type": "stream", "text": ["HPU available: False, using: 0 HPUs\n"]}, {"name": "stderr", "output_type": "stream", "text": ["/usr/local/lib/python3.10/dist-packages/pytorch_lightning/trainer/connectors/logger_connector/logger_connector.py:75: Starting from v1.9.0, `tensorboardX` has been removed as a dependency of the `pytorch_lightning` package, due to potential conflicts with other packages in the ML ecosystem. For this reason, `logger=True` will use `CSVLogger` as the default logger, unless the `tensorboard` or `tensorboardX` packages are found. Please `pip install lightning[extra]` or one of them to enable TensorBoard support by default\n"]}, {"name": "stdout", "output_type": "stream", "text": ["Found pretrained model, loading...\n"]}, {"name": "stderr", "output_type": "stream", "text": ["Lightning automatically upgraded your loaded checkpoint from v1.0.2 to v2.4.0. To apply the upgrade to your files permanently, run `python -m pytorch_lightning.utilities.upgrade_checkpoint saved_models/GNNs/NodeLevelMLP.ckpt`\n"]}, {"name": "stderr", "output_type": "stream", "text": ["You are using a CUDA device ('NVIDIA GeForce RTX 3090') that has Tensor Cores. To properly utilize them, you should set `torch.set_float32_matmul_precision('medium' | 'high')` which will trade-off precision for performance. For more details, read https://pytorch.org/docs/stable/generated/torch.set_float32_matmul_precision.html#torch.set_float32_matmul_precision\n"]}, {"name": "stderr", "output_type": "stream", "text": ["LOCAL_RANK: 0 - CUDA_VISIBLE_DEVICES: [0,1]\n"]}, {"name": "stdout", "output_type": "stream", "text": ["Train accuracy: 97.14%\n", "Val accuracy: 54.60%\n", "Test accuracy: 60.60%\n"]}, {"name": "stderr", "output_type": "stream", "text": ["/usr/local/lib/python3.10/dist-packages/pytorch_lightning/trainer/connectors/data_connector.py:424: The 'test_dataloader' does not have many workers which may be a bottleneck. Consider increasing the value of the `num_workers` argument` to `num_workers=63` in the `DataLoader` to improve performance.\n", "/usr/local/lib/python3.10/dist-packages/pytorch_lightning/utilities/data.py:78: Trying to infer the `batch_size` from an ambiguous collection. The batch size we found is 2708. To avoid any miscalculations, use `self.log(..., batch_size=batch_size)`.\n"]}], "source": ["node_mlp_model, node_mlp_result = train_node_classifier(\n", " model_name=\"MLP\", dataset=cora_dataset, c_hidden=16, num_layers=2, dp_rate=0.1\n", ")\n", "\n", "print_results(node_mlp_result)"]}, {"cell_type": "markdown", "id": "95310456", "metadata": {"papermill": {"duration": 0.012068, "end_time": "2025-04-03T19:22:02.777422", "exception": false, "start_time": "2025-04-03T19:22:02.765354", "status": "completed"}, "tags": []}, "source": ["Although the MLP can overfit on the training dataset because of the high-dimensional input features,\n", "it does not perform too well on the test set.\n", "Let's see if we can beat this score with our graph networks:"]}, {"cell_type": "code", "execution_count": 18, "id": "610fa419", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:02.803538Z", "iopub.status.busy": "2025-04-03T19:22:02.802861Z", "iopub.status.idle": "2025-04-03T19:22:02.973505Z", "shell.execute_reply": "2025-04-03T19:22:02.972287Z"}, "papermill": {"duration": 0.185776, "end_time": "2025-04-03T19:22:02.975688", "exception": false, "start_time": "2025-04-03T19:22:02.789912", "status": "completed"}, "tags": []}, "outputs": [{"name": "stderr", "output_type": "stream", "text": ["Seed set to 42\n"]}, {"name": "stderr", "output_type": "stream", "text": ["GPU available: True (cuda), used: True\n"]}, {"name": "stderr", "output_type": "stream", "text": ["TPU available: False, using: 0 TPU cores\n"]}, {"name": "stderr", "output_type": "stream", "text": ["HPU available: False, using: 0 HPUs\n"]}, {"name": "stderr", "output_type": "stream", "text": ["Lightning automatically upgraded your loaded checkpoint from v1.0.2 to v2.4.0. To apply the upgrade to your files permanently, run `python -m pytorch_lightning.utilities.upgrade_checkpoint saved_models/GNNs/NodeLevelGNN.ckpt`\n"]}, {"name": "stderr", "output_type": "stream", "text": ["LOCAL_RANK: 0 - CUDA_VISIBLE_DEVICES: [0,1]\n"]}, {"name": "stdout", "output_type": "stream", "text": ["Found pretrained model, loading...\n"]}, {"name": "stdout", "output_type": "stream", "text": ["Train accuracy: 100.00%\n", "Val accuracy: 78.60%\n", "Test accuracy: 82.40%\n"]}], "source": ["node_gnn_model, node_gnn_result = train_node_classifier(\n", " model_name=\"GNN\", layer_name=\"GCN\", dataset=cora_dataset, c_hidden=16, num_layers=2, dp_rate=0.1\n", ")\n", "print_results(node_gnn_result)"]}, {"cell_type": "markdown", "id": "b2246c39", "metadata": {"papermill": {"duration": 0.019073, "end_time": "2025-04-03T19:22:03.015287", "exception": false, "start_time": "2025-04-03T19:22:02.996214", "status": "completed"}, "tags": []}, "source": ["As we would have hoped for, the GNN model outperforms the MLP by quite a margin.\n", "This shows that using the graph information indeed improves our predictions and lets us generalizes better.\n", "\n", "The hyperparameters in the model have been chosen to create a relatively small network.\n", "This is because the first layer with an input dimension of 1433 can be relatively expensive to perform for large graphs.\n", "In general, GNNs can become relatively expensive for very big graphs.\n", "This is why such GNNs either have a small hidden size or use a special batching strategy\n", "where we sample a connected subgraph of the big, original graph."]}, {"cell_type": "markdown", "id": "60811c5f", "metadata": {"papermill": {"duration": 0.012657, "end_time": "2025-04-03T19:22:03.042948", "exception": false, "start_time": "2025-04-03T19:22:03.030291", "status": "completed"}, "tags": []}, "source": ["### Edge-level tasks: Link prediction\n", "\n", "In some applications, we might have to predict on an edge-level instead of node-level.\n", "The most common edge-level task in GNN is link prediction.\n", "Link prediction means that given a graph, we want to predict whether there will be/should be an edge between two nodes or not.\n", "For example, in a social network, this is used by Facebook and co to propose new friends to you.\n", "Again, graph level information can be crucial to perform this task.\n", "The output prediction is usually done by performing a similarity metric on the pair of node features,\n", "which should be 1 if there should be a link, and otherwise close to 0.\n", "To keep the tutorial short, we will not implement this task ourselves.\n", "Nevertheless, there are many good resources out there if you are interested in looking closer at this task.\n", "Tutorials and papers for this topic include:\n", "\n", "* [PyTorch Geometric example](https://github.com/rusty1s/pytorch_geometric/blob/master/examples/link_pred.py)\n", "* [Graph Neural Networks: A Review of Methods and Applications](https://arxiv.org/abs/1812.08434), Zhou et al.\n", "2019\n", "* [Link Prediction Based on Graph Neural Networks](https://papers.nips.cc/paper/2018/file/53f0d7c537d99b3824f0f99d62ea2428-Paper.pdf), Zhang and Chen, 2018."]}, {"cell_type": "markdown", "id": "5039a031", "metadata": {"papermill": {"duration": 0.009952, "end_time": "2025-04-03T19:22:03.065462", "exception": false, "start_time": "2025-04-03T19:22:03.055510", "status": "completed"}, "tags": []}, "source": ["### Graph-level tasks: Graph classification\n", "\n", "Finally, in this part of the tutorial, we will have a closer look at how to apply GNNs to the task of graph classification.\n", "The goal is to classify an entire graph instead of single nodes or edges.\n", "Therefore, we are also given a dataset of multiple graphs that we need to classify based on some structural graph properties.\n", "The most common task for graph classification is molecular property prediction, in which molecules are represented as graphs.\n", "Each atom is linked to a node, and edges in the graph are the bonds between atoms.\n", "For example, look at the figure below.\n", "\n", "![](\"https://github.com/Lightning-AI/lightning-tutorials/raw/main/course_UvA-DL/06-graph-neural-networks/molecule_graph.svg\")
\n", "\n", "On the left, we have an arbitrary, small molecule with different atoms, whereas the right part of the image shows the graph representation.\n", "The atom types are abstracted as node features (e.g. a one-hot vector), and the different bond types are used as edge features.\n", "For simplicity, we will neglect the edge attributes in this tutorial, but you can include by using methods like the\n", "[Relational Graph Convolution](https://arxiv.org/abs/1703.06103) that uses a different weight matrix for each edge type.\n", "\n", "The dataset we will use below is called the MUTAG dataset.\n", "It is a common small benchmark for graph classification algorithms, and contain 188 graphs with 18 nodes\n", "and 20 edges on average for each graph.\n", "The graph nodes have 7 different labels/atom types, and the binary graph labels represent \"their mutagenic effect\n", "on a specific gram negative bacterium\" (the specific meaning of the labels are not too important here).\n", "The dataset is part of a large collection of different graph classification datasets, known as the\n", "[TUDatasets](https://chrsmrrs.github.io/datasets/), which is directly accessible\n", "via `torch_geometric.datasets.TUDataset` ([documentation](https://pytorch-geometric.readthedocs.io/en/latest/modules/datasets.html#torch_geometric.datasets.TUDataset)) in PyTorch Geometric.\n", "We can load the dataset below."]}, {"cell_type": "code", "execution_count": 19, "id": "ac1e6266", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:03.084289Z", "iopub.status.busy": "2025-04-03T19:22:03.083717Z", "iopub.status.idle": "2025-04-03T19:22:03.737878Z", "shell.execute_reply": "2025-04-03T19:22:03.736645Z"}, "papermill": {"duration": 0.665629, "end_time": "2025-04-03T19:22:03.739685", "exception": false, "start_time": "2025-04-03T19:22:03.074056", "status": "completed"}, "tags": []}, "outputs": [{"name": "stderr", "output_type": "stream", "text": ["Downloading https://www.chrsmrrs.com/graphkerneldatasets/MUTAG.zip\n"]}, {"name": "stderr", "output_type": "stream", "text": ["Extracting /__w/11/s/.datasets/MUTAG/MUTAG.zip\n", "Processing...\n", "Done!\n"]}], "source": ["tu_dataset = torch_geometric.datasets.TUDataset(root=DATASET_PATH, name=\"MUTAG\")"]}, {"cell_type": "markdown", "id": "878ac8ad", "metadata": {"papermill": {"duration": 0.019195, "end_time": "2025-04-03T19:22:03.777453", "exception": false, "start_time": "2025-04-03T19:22:03.758258", "status": "completed"}, "tags": []}, "source": ["Let's look at some statistics for the dataset:"]}, {"cell_type": "code", "execution_count": 20, "id": "0972f529", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:03.807550Z", "iopub.status.busy": "2025-04-03T19:22:03.806663Z", "iopub.status.idle": "2025-04-03T19:22:03.813704Z", "shell.execute_reply": "2025-04-03T19:22:03.812510Z"}, "papermill": {"duration": 0.021969, "end_time": "2025-04-03T19:22:03.815226", "exception": false, "start_time": "2025-04-03T19:22:03.793257", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Data object: Data(x=[3371, 7], edge_index=[2, 7442], edge_attr=[7442, 4], y=[188])\n", "Length: 188\n", "Average label: 0.66\n"]}], "source": ["print(\"Data object:\", tu_dataset.data)\n", "print(\"Length:\", len(tu_dataset))\n", "print(f\"Average label: {tu_dataset.data.y.float().mean().item():4.2f}\")"]}, {"cell_type": "markdown", "id": "d069a9d7", "metadata": {"papermill": {"duration": 0.012435, "end_time": "2025-04-03T19:22:03.839978", "exception": false, "start_time": "2025-04-03T19:22:03.827543", "status": "completed"}, "tags": []}, "source": ["The first line shows how the dataset stores different graphs.\n", "The nodes, edges, and labels of each graph are concatenated to one tensor, and the dataset stores the indices\n", "where to split the tensors correspondingly.\n", "The length of the dataset is the number of graphs we have, and the \"average label\"\n", "denotes the percentage of the graph with label 1.\n", "As long as the percentage is in the range of 0.5, we have a relatively balanced dataset.\n", "It happens quite often that graph datasets are very imbalanced, hence checking the class balance\n", "is always a good thing to do.\n", "\n", "Next, we will split our dataset into a training and test part.\n", "Note that we do not use a validation set this time because of the small size of the dataset.\n", "Therefore, our model might overfit slightly on the validation set due to the noise of the evaluation,\n", "but we still get an estimate of the performance on untrained data."]}, {"cell_type": "code", "execution_count": 21, "id": "d5e875a2", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:03.862263Z", "iopub.status.busy": "2025-04-03T19:22:03.861520Z", "iopub.status.idle": "2025-04-03T19:22:03.867558Z", "shell.execute_reply": "2025-04-03T19:22:03.866425Z"}, "papermill": {"duration": 0.017168, "end_time": "2025-04-03T19:22:03.868957", "exception": false, "start_time": "2025-04-03T19:22:03.851789", "status": "completed"}, "tags": []}, "outputs": [], "source": ["torch.manual_seed(42)\n", "tu_dataset.shuffle()\n", "train_dataset = tu_dataset[:150]\n", "test_dataset = tu_dataset[150:]"]}, {"cell_type": "markdown", "id": "debc95c7", "metadata": {"papermill": {"duration": 0.008652, "end_time": "2025-04-03T19:22:03.886411", "exception": false, "start_time": "2025-04-03T19:22:03.877759", "status": "completed"}, "tags": []}, "source": ["When using a data loader, we encounter a problem with batching $N$ graphs.\n", "Each graph in the batch can have a different number of nodes and edges, and hence we would require a lot of padding to obtain a single tensor.\n", "Torch geometric uses a different, more efficient approach: we can view the $N$ graphs in a batch as a single large graph with concatenated node and edge list.\n", "As there is no edge between the $N$ graphs, running GNN layers on the large graph gives us the same output as running the GNN on each graph separately.\n", "Visually, this batching strategy is visualized below (figure credit - PyTorch Geometric team,\n", "[tutorial here](https://colab.research.google.com/drive/1I8a0DfQ3fI7Njc62__mVXUlcAleUclnb)).\n", "\n", "![](\"https://github.com/Lightning-AI/lightning-tutorials/raw/main/course_UvA-DL/06-graph-neural-networks/torch_geometric_stacking_graphs.png\")
\n", "\n", "The adjacency matrix is zero for any nodes that come from two different graphs, and otherwise according to the adjacency matrix of the individual graph.\n", "Luckily, this strategy is already implemented in torch geometric, and hence we can use the corresponding data loader:"]}, {"cell_type": "code", "execution_count": 22, "id": "a7bce7b7", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:03.905259Z", "iopub.status.busy": "2025-04-03T19:22:03.904910Z", "iopub.status.idle": "2025-04-03T19:22:03.911415Z", "shell.execute_reply": "2025-04-03T19:22:03.910285Z"}, "papermill": {"duration": 0.017698, "end_time": "2025-04-03T19:22:03.912820", "exception": false, "start_time": "2025-04-03T19:22:03.895122", "status": "completed"}, "tags": []}, "outputs": [], "source": ["graph_train_loader = geom_data.DataLoader(train_dataset, batch_size=BATCH_SIZE, shuffle=True)\n", "graph_val_loader = geom_data.DataLoader(test_dataset, batch_size=BATCH_SIZE) # Additional loader for a larger datasets\n", "graph_test_loader = geom_data.DataLoader(test_dataset, batch_size=BATCH_SIZE)"]}, {"cell_type": "markdown", "id": "0ba79dd6", "metadata": {"papermill": {"duration": 0.008689, "end_time": "2025-04-03T19:22:03.930293", "exception": false, "start_time": "2025-04-03T19:22:03.921604", "status": "completed"}, "tags": []}, "source": ["Let's load a batch below to see the batching in action:"]}, {"cell_type": "code", "execution_count": 23, "id": "9013242f", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:03.949513Z", "iopub.status.busy": "2025-04-03T19:22:03.948728Z", "iopub.status.idle": "2025-04-03T19:22:03.965796Z", "shell.execute_reply": "2025-04-03T19:22:03.964635Z"}, "papermill": {"duration": 0.028187, "end_time": "2025-04-03T19:22:03.967204", "exception": false, "start_time": "2025-04-03T19:22:03.939017", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Batch: DataBatch(edge_index=[2, 1512], x=[687, 7], edge_attr=[1512, 4], y=[38], batch=[687], ptr=[39])\n", "Labels: tensor([1, 1, 1, 0, 0, 0, 1, 1, 1, 0])\n", "Batch indices: tensor([0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 1,\n", " 1, 1, 1, 1, 1, 1, 1, 1, 1, 1, 2, 2, 2, 2, 2, 2])\n"]}], "source": ["batch = next(iter(graph_test_loader))\n", "print(\"Batch:\", batch)\n", "print(\"Labels:\", batch.y[:10])\n", "print(\"Batch indices:\", batch.batch[:40])"]}, {"cell_type": "markdown", "id": "50d4c292", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.008719, "end_time": "2025-04-03T19:22:03.984717", "exception": false, "start_time": "2025-04-03T19:22:03.975998", "status": "completed"}, "tags": []}, "source": ["We have 38 graphs stacked together for the test dataset.\n", "The batch indices, stored in `batch`, show that the first 12 nodes belong to the first graph,\n", "the next 22 to the second graph, and so on.\n", "These indices are important for performing the final prediction.\n", "To perform a prediction over a whole graph, we usually perform a pooling operation over all nodes after running the GNN model.\n", "In this case, we will use the average pooling.\n", "Hence, we need to know which nodes should be included in which average pool.\n", "Using this pooling, we can already create our graph network below.\n", "Specifically, we reuse our class `GNNModel` from before,\n", "and simply add an average pool and single linear layer for the graph prediction task."]}, {"cell_type": "code", "execution_count": 24, "id": "049e87a5", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:04.004428Z", "iopub.status.busy": "2025-04-03T19:22:04.003568Z", "iopub.status.idle": "2025-04-03T19:22:04.012220Z", "shell.execute_reply": "2025-04-03T19:22:04.011093Z"}, "lines_to_next_cell": 2, "papermill": {"duration": 0.02006, "end_time": "2025-04-03T19:22:04.013645", "exception": false, "start_time": "2025-04-03T19:22:03.993585", "status": "completed"}, "tags": []}, "outputs": [], "source": ["class GraphGNNModel(nn.Module):\n", " def __init__(self, c_in, c_hidden, c_out, dp_rate_linear=0.5, **kwargs):\n", " \"\"\"GraphGNNModel.\n", "\n", " Args:\n", " c_in: Dimension of input features\n", " c_hidden: Dimension of hidden features\n", " c_out: Dimension of output features (usually number of classes)\n", " dp_rate_linear: Dropout rate before the linear layer (usually much higher than inside the GNN)\n", " kwargs: Additional arguments for the GNNModel object\n", "\n", " \"\"\"\n", " super().__init__()\n", " self.GNN = GNNModel(c_in=c_in, c_hidden=c_hidden, c_out=c_hidden, **kwargs) # Not our prediction output yet!\n", " self.head = nn.Sequential(nn.Dropout(dp_rate_linear), nn.Linear(c_hidden, c_out))\n", "\n", " def forward(self, x, edge_index, batch_idx):\n", " \"\"\"Forward.\n", "\n", " Args:\n", " x: Input features per node\n", " edge_index: List of vertex index pairs representing the edges in the graph (PyTorch geometric notation)\n", " batch_idx: Index of batch element for each node\n", "\n", " \"\"\"\n", " x = self.GNN(x, edge_index)\n", " x = geom_nn.global_mean_pool(x, batch_idx) # Average pooling\n", " x = self.head(x)\n", " return x"]}, {"cell_type": "markdown", "id": "ddfbf9a9", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.00877, "end_time": "2025-04-03T19:22:04.031323", "exception": false, "start_time": "2025-04-03T19:22:04.022553", "status": "completed"}, "tags": []}, "source": ["Finally, we can create a PyTorch Lightning module to handle the training.\n", "It is similar to the modules we have seen before and does nothing surprising in terms of training.\n", "As we have a binary classification task, we use the Binary Cross Entropy loss."]}, {"cell_type": "code", "execution_count": 25, "id": "0b42a7f2", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:04.050387Z", "iopub.status.busy": "2025-04-03T19:22:04.050023Z", "iopub.status.idle": "2025-04-03T19:22:04.063399Z", "shell.execute_reply": "2025-04-03T19:22:04.062270Z"}, "lines_to_next_cell": 2, "papermill": {"duration": 0.024462, "end_time": "2025-04-03T19:22:04.064596", "exception": false, "start_time": "2025-04-03T19:22:04.040134", "status": "completed"}, "tags": []}, "outputs": [], "source": ["class GraphLevelGNN(pl.LightningModule):\n", " def __init__(self, **model_kwargs):\n", " super().__init__()\n", " # Saving hyperparameters\n", " self.save_hyperparameters()\n", "\n", " self.model = GraphGNNModel(**model_kwargs)\n", " self.loss_module = nn.BCEWithLogitsLoss() if self.hparams.c_out == 1 else nn.CrossEntropyLoss()\n", "\n", " def forward(self, data, mode=\"train\"):\n", " x, edge_index, batch_idx = data.x, data.edge_index, data.batch\n", " x = self.model(x, edge_index, batch_idx)\n", " x = x.squeeze(dim=-1)\n", "\n", " if self.hparams.c_out == 1:\n", " preds = (x > 0).float()\n", " data.y = data.y.float()\n", " else:\n", " preds = x.argmax(dim=-1)\n", " loss = self.loss_module(x, data.y)\n", " acc = (preds == data.y).sum().float() / preds.shape[0]\n", " return loss, acc\n", "\n", " def configure_optimizers(self):\n", " # High lr because of small dataset and small model\n", " optimizer = optim.AdamW(self.parameters(), lr=1e-2, weight_decay=0.0)\n", " return optimizer\n", "\n", " def training_step(self, batch, batch_idx):\n", " loss, acc = self.forward(batch, mode=\"train\")\n", " self.log(\"train_loss\", loss)\n", " self.log(\"train_acc\", acc)\n", " return loss\n", "\n", " def validation_step(self, batch, batch_idx):\n", " _, acc = self.forward(batch, mode=\"val\")\n", " self.log(\"val_acc\", acc)\n", "\n", " def test_step(self, batch, batch_idx):\n", " _, acc = self.forward(batch, mode=\"test\")\n", " self.log(\"test_acc\", acc)"]}, {"cell_type": "markdown", "id": "826c37a3", "metadata": {"lines_to_next_cell": 2, "papermill": {"duration": 0.0088, "end_time": "2025-04-03T19:22:04.082285", "exception": false, "start_time": "2025-04-03T19:22:04.073485", "status": "completed"}, "tags": []}, "source": ["Below we train the model on our dataset. It resembles the typical training functions we have seen so far."]}, {"cell_type": "code", "execution_count": 26, "id": "c63fd3b1", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:04.101440Z", "iopub.status.busy": "2025-04-03T19:22:04.101094Z", "iopub.status.idle": "2025-04-03T19:22:04.111983Z", "shell.execute_reply": "2025-04-03T19:22:04.110925Z"}, "papermill": {"duration": 0.022203, "end_time": "2025-04-03T19:22:04.113353", "exception": false, "start_time": "2025-04-03T19:22:04.091150", "status": "completed"}, "tags": []}, "outputs": [], "source": ["def train_graph_classifier(model_name, **model_kwargs):\n", " pl.seed_everything(42)\n", "\n", " # Create a PyTorch Lightning trainer with the generation callback\n", " root_dir = os.path.join(CHECKPOINT_PATH, \"GraphLevel\" + model_name)\n", " os.makedirs(root_dir, exist_ok=True)\n", " trainer = pl.Trainer(\n", " default_root_dir=root_dir,\n", " callbacks=[ModelCheckpoint(save_weights_only=True, mode=\"max\", monitor=\"val_acc\")],\n", " accelerator=\"cuda\",\n", " devices=AVAIL_GPUS,\n", " max_epochs=500,\n", " enable_progress_bar=False,\n", " )\n", " trainer.logger._default_hp_metric = None\n", "\n", " # Check whether pretrained model exists. If yes, load it and skip training\n", " pretrained_filename = os.path.join(CHECKPOINT_PATH, f\"GraphLevel{model_name}.ckpt\")\n", " if os.path.isfile(pretrained_filename):\n", " print(\"Found pretrained model, loading...\")\n", " model = GraphLevelGNN.load_from_checkpoint(pretrained_filename)\n", " else:\n", " pl.seed_everything(42)\n", " model = GraphLevelGNN(\n", " c_in=tu_dataset.num_node_features,\n", " c_out=1 if tu_dataset.num_classes == 2 else tu_dataset.num_classes,\n", " **model_kwargs,\n", " )\n", " trainer.fit(model, graph_train_loader, graph_val_loader)\n", " model = GraphLevelGNN.load_from_checkpoint(trainer.checkpoint_callback.best_model_path)\n", "\n", " # Test best model on validation and test set\n", " train_result = trainer.test(model, dataloaders=graph_train_loader, verbose=False)\n", " test_result = trainer.test(model, dataloaders=graph_test_loader, verbose=False)\n", " result = {\"test\": test_result[0][\"test_acc\"], \"train\": train_result[0][\"test_acc\"]}\n", " return model, result"]}, {"cell_type": "markdown", "id": "e63e93cb", "metadata": {"papermill": {"duration": 0.008819, "end_time": "2025-04-03T19:22:04.131185", "exception": false, "start_time": "2025-04-03T19:22:04.122366", "status": "completed"}, "tags": []}, "source": ["Finally, let's perform the training and testing.\n", "Feel free to experiment with different GNN layers, hyperparameters, etc."]}, {"cell_type": "code", "execution_count": 27, "id": "34b3276d", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:04.150439Z", "iopub.status.busy": "2025-04-03T19:22:04.150076Z", "iopub.status.idle": "2025-04-03T19:22:04.291715Z", "shell.execute_reply": "2025-04-03T19:22:04.290599Z"}, "papermill": {"duration": 0.153736, "end_time": "2025-04-03T19:22:04.293839", "exception": false, "start_time": "2025-04-03T19:22:04.140103", "status": "completed"}, "tags": []}, "outputs": [{"name": "stderr", "output_type": "stream", "text": ["Seed set to 42\n"]}, {"name": "stderr", "output_type": "stream", "text": ["GPU available: True (cuda), used: True\n"]}, {"name": "stderr", "output_type": "stream", "text": ["TPU available: False, using: 0 TPU cores\n"]}, {"name": "stderr", "output_type": "stream", "text": ["HPU available: False, using: 0 HPUs\n"]}, {"name": "stderr", "output_type": "stream", "text": ["Lightning automatically upgraded your loaded checkpoint from v1.0.2 to v2.4.0. To apply the upgrade to your files permanently, run `python -m pytorch_lightning.utilities.upgrade_checkpoint saved_models/GNNs/GraphLevelGraphConv.ckpt`\n"]}, {"name": "stderr", "output_type": "stream", "text": ["LOCAL_RANK: 0 - CUDA_VISIBLE_DEVICES: [0,1]\n"]}, {"name": "stderr", "output_type": "stream", "text": ["/usr/local/lib/python3.10/dist-packages/pytorch_lightning/trainer/connectors/data_connector.py:475: Your `test_dataloader`'s sampler has shuffling enabled, it is strongly recommended that you turn shuffling off for val/test dataloaders.\n", "/usr/local/lib/python3.10/dist-packages/pytorch_lightning/utilities/data.py:78: Trying to infer the `batch_size` from an ambiguous collection. The batch size we found is 2. To avoid any miscalculations, use `self.log(..., batch_size=batch_size)`.\n", "LOCAL_RANK: 0 - CUDA_VISIBLE_DEVICES: [0,1]\n"]}, {"name": "stdout", "output_type": "stream", "text": ["Found pretrained model, loading...\n"]}], "source": ["model, result = train_graph_classifier(\n", " model_name=\"GraphConv\", c_hidden=256, layer_name=\"GraphConv\", num_layers=3, dp_rate_linear=0.5, dp_rate=0.0\n", ")"]}, {"cell_type": "code", "execution_count": 28, "id": "8e8c259e", "metadata": {"execution": {"iopub.execute_input": "2025-04-03T19:22:04.335740Z", "iopub.status.busy": "2025-04-03T19:22:04.335541Z", "iopub.status.idle": "2025-04-03T19:22:04.340530Z", "shell.execute_reply": "2025-04-03T19:22:04.339558Z"}, "papermill": {"duration": 0.027829, "end_time": "2025-04-03T19:22:04.342049", "exception": false, "start_time": "2025-04-03T19:22:04.314220", "status": "completed"}, "tags": []}, "outputs": [{"name": "stdout", "output_type": "stream", "text": ["Train performance: 92.67%\n", "Test performance: 92.11%\n"]}], "source": ["print(\"Train performance: %4.2f%%\" % (100.0 * result[\"train\"]))\n", "print(\"Test performance: %4.2f%%\" % (100.0 * result[\"test\"]))"]}, {"cell_type": "markdown", "id": "a3c81e49", "metadata": {"papermill": {"duration": 0.01275, "end_time": "2025-04-03T19:22:04.367671", "exception": false, "start_time": "2025-04-03T19:22:04.354921", "status": "completed"}, "tags": []}, "source": ["The test performance shows that we obtain quite good scores on an unseen part of the dataset.\n", "It should be noted that as we have been using the test set for validation as well, we might have overfitted slightly to this set.\n", "Nevertheless, the experiment shows us that GNNs can be indeed powerful to predict the properties of graphs and/or molecules."]}, {"cell_type": "markdown", "id": "5171a769", "metadata": {"papermill": {"duration": 0.010964, "end_time": "2025-04-03T19:22:04.391552", "exception": false, "start_time": "2025-04-03T19:22:04.380588", "status": "completed"}, "tags": []}, "source": ["## Conclusion\n", "\n", "In this tutorial, we have seen the application of neural networks to graph structures.\n", "We looked at how a graph can be represented (adjacency matrix or edge list),\n", "and discussed the implementation of common graph layers: GCN and GAT.\n", "The implementations showed the practical side of the layers, which is often easier than the theory.\n", "Finally, we experimented with different tasks, on node-, edge- and graph-level.\n", "Overall, we have seen that including graph information in the predictions can be crucial for achieving high performance.\n", "There are a lot of applications that benefit from GNNs,\n", "and the importance of these networks will likely increase over the next years."]}, {"cell_type": "markdown", "id": "0d4ab3ac", "metadata": {"papermill": {"duration": 0.009267, "end_time": "2025-04-03T19:22:04.410121", "exception": false, "start_time": "2025-04-03T19:22:04.400854", "status": "completed"}, "tags": []}, "source": ["## Congratulations - Time to Join the Community!\n", "\n", "Congratulations on completing this notebook tutorial! If you enjoyed this and would like to join the Lightning\n", "movement, you can do so in the following ways!\n", "\n", "### Star [Lightning](https://github.com/Lightning-AI/lightning) on GitHub\n", "The easiest way to help our community is just by starring the GitHub repos! This helps raise awareness of the cool\n", "tools we're building.\n", "\n", "### Join our [Discord](https://discord.com/invite/tfXFetEZxv)!\n", "The best way to keep up to date on the latest advancements is to join our community! Make sure to introduce yourself\n", "and share your interests in `#general` channel\n", "\n", "\n", "### Contributions !\n", "The best way to contribute to our community is to become a code contributor! At any time you can go to\n", "[Lightning](https://github.com/Lightning-AI/lightning) or [Bolt](https://github.com/Lightning-AI/lightning-bolts)\n", "GitHub Issues page and filter for \"good first issue\".\n", "\n", "* [Lightning good first issue](https://github.com/Lightning-AI/lightning/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)\n", "* [Bolt good first issue](https://github.com/Lightning-AI/lightning-bolts/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)\n", "* You can also contribute your own notebooks with useful examples !\n", "\n", "### Great thanks from the entire Pytorch Lightning Team for your interest !\n", "\n", "[{height=\"60px\" width=\"240px\"}](https://pytorchlightning.ai)"]}, {"cell_type": "raw", "metadata": {"raw_mimetype": "text/restructuredtext"}, "source": [".. customcarditem::\n", " :header: Tutorial 6: Basics of Graph Neural Networks\n", " :card_description: In this tutorial, we will discuss the application of neural networks on graphs. Graph Neural Networks (GNNs) have recently gained increasing popularity in both applications...\n", " :tags: Graph,GPU/TPU,UvA-DL-Course\n", " :image: _static/images/course_UvA-DL/06-graph-neural-networks.jpg"]}], "metadata": {"jupytext": {"cell_metadata_filter": "colab_type,colab,id,-all", "formats": "ipynb,py:percent", "main_language": "python"}, "language_info": {"codemirror_mode": {"name": "ipython", "version": 3}, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "ipython3", "version": "3.10.12"}, "papermill": {"default_parameters": {}, "duration": 12.165987, "end_time": "2025-04-03T19:22:05.739571", "environment_variables": {}, "exception": null, "input_path": "course_UvA-DL/06-graph-neural-networks/overview.ipynb", "output_path": ".notebooks/course_UvA-DL/06-graph-neural-networks.ipynb", "parameters": {}, "start_time": "2025-04-03T19:21:53.573584", "version": "2.6.0"}}, "nbformat": 4, "nbformat_minor": 5}