Introduction by Example
=======================

We shortly introduce the fundamental concepts of :pyg:`PyG` through self-contained examples.

For an introduction to Graph Machine Learning, we refer the interested reader to the :stanford:`null` `Stanford CS224W: Machine Learning with Graphs <https://www.youtube.com/watch?v=JAB_plj2rbA>`__ lectures.
For an interactive introduction to :pyg:`PyG`, we recommend our carefully curated :colab:`null` `Google Colab <colabs.html>`__ notebooks.

At its core, :pyg:`PyG` provides the following main features:

.. contents::
    :local:

Data Handling of Graphs
-----------------------

A graph is used to model pairwise relations (edges) between objects (nodes).
A single graph in :pyg:`PyG` is described by an instance of :class:`torch_geometric.data.Data`, which holds the following attributes by default:

- :obj:`data.x`: Node feature matrix with shape :obj:`[num_nodes, num_node_features]`
- :obj:`data.edge_index`: Graph connectivity in `COO format <https://pytorch.org/docs/stable/sparse.html#sparse-coo-docs>`_ with shape :obj:`[2, num_edges]` and type :obj:`torch.long`
- :obj:`data.edge_attr`: Edge feature matrix with shape :obj:`[num_edges, num_edge_features]`
- :obj:`data.y`: Target to train against (may have arbitrary shape), *e.g.*, node-level targets of shape :obj:`[num_nodes, *]` or graph-level targets of shape :obj:`[1, *]`
- :obj:`data.pos`: Node position matrix with shape :obj:`[num_nodes, num_dimensions]`

None of these attributes are required.
In fact, the :class:`~torch_geometric.data.Data` object is not even restricted to these attributes.
We can, *e.g.*, extend it by :obj:`data.face` to save the connectivity of triangles from a 3D mesh in a tensor with shape :obj:`[3, num_faces]` and type :obj:`torch.long`.

.. Note::
    :pytorch:`PyTorch` and :obj:`torchvision` define an example as a tuple of an image and a target.
    We omit this notation in :pyg:`PyG` to allow for various data structures in a clean and understandable way.

We show a simple example of an unweighted and undirected graph with three nodes and four edges.
Each node contains exactly one feature:

.. code-block:: python

    import torch
    from torch_geometric.data import Data

    edge_index = torch.tensor([[0, 1, 1, 2],
                               [1, 0, 2, 1]], dtype=torch.long)
    x = torch.tensor([[-1], [0], [1]], dtype=torch.float)

    data = Data(x=x, edge_index=edge_index)
    >>> Data(edge_index=[2, 4], x=[3, 1])

.. image:: ../_figures/graph.svg
  :align: center
  :width: 300px

|

Note that :obj:`edge_index`, *i.e.* the tensor defining the source and target nodes of all edges, is **not** a list of index tuples.
If you want to write your indices this way, you should transpose and call :obj:`contiguous` on it before passing them to the data constructor:

.. code-block:: python

    import torch
    from torch_geometric.data import Data

    edge_index = torch.tensor([[0, 1],
                               [1, 0],
                               [1, 2],
                               [2, 1]], dtype=torch.long)
    x = torch.tensor([[-1], [0], [1]], dtype=torch.float)

    data = Data(x=x, edge_index=edge_index.t().contiguous())
    >>> Data(edge_index=[2, 4], x=[3, 1])

Although the graph has only two edges, we need to define four index tuples to account for both directions of a edge.

.. Note::
    You can print out your data object anytime and receive a short information about its attributes and their shapes.

Note that it is necessary that the elements in :obj:`edge_index` only hold indices in the range :obj:`{ 0, ..., num_nodes - 1}`.
This is needed as we want our final data representation to be as compact as possible, *e.g.*, we want to index the source and destination node features of the first edge :obj:`(0, 1)` via :obj:`x[0]` and :obj:`x[1]`, respectively.
You can always check that your final :class:`~torch_geometric.data.Data` objects fulfill these requirements by running :meth:`~torch_geometric.data.Data.validate`:

.. code-block:: python

   data.validate(raise_on_error=True)

Besides holding a number of node-level, edge-level or graph-level attributes, :class:`~torch_geometric.data.Data` provides a number of useful utility functions, *e.g.*:

.. code-block:: python

    print(data.keys())
    >>> ['x', 'edge_index']

    print(data['x'])
    >>> tensor([[-1.0],
                [0.0],
                [1.0]])

    for key, item in data:
        print(f'{key} found in data')
    >>> x found in data
    >>> edge_index found in data

    'edge_attr' in data
    >>> False

    data.num_nodes
    >>> 3

    data.num_edges
    >>> 4

    data.num_node_features
    >>> 1

    data.has_isolated_nodes()
    >>> False

    data.has_self_loops()
    >>> False

    data.is_directed()
    >>> False

    # Transfer data object to GPU.
    device = torch.device('cuda')
    data = data.to(device)

You can find a complete list of all methods at :class:`torch_geometric.data.Data`.

Common Benchmark Datasets
-------------------------

:pyg:`PyG` contains a large number of common benchmark datasets, *e.g.*, all Planetoid datasets (Cora, Citeseer, Pubmed), all graph classification datasets from `TUDatasets <https://chrsmrrs.github.io/datasets/>`_ and their `cleaned versions <https://github.com/nd7141/graph_datasets>`_, the QM7 and QM9 dataset, and a handful of 3D mesh/point cloud datasets like FAUST, ModelNet10/40 and ShapeNet.

Initializing a dataset is straightforward.
An initialization of a dataset will automatically download its raw files and process them to the previously described :class:`~torch_geometric.data.Data` format.
*E.g.*, to load the ENZYMES dataset (consisting of 600 graphs within 6 classes), type:

.. code-block:: python

    from torch_geometric.datasets import TUDataset

    dataset = TUDataset(root='/tmp/ENZYMES', name='ENZYMES')
    >>> ENZYMES(600)

    len(dataset)
    >>> 600

    dataset.num_classes
    >>> 6

    dataset.num_node_features
    >>> 3

We now have access to all 600 graphs in the dataset:

.. code-block:: python

    data = dataset[0]
    >>> Data(edge_index=[2, 168], x=[37, 3], y=[1])

    data.is_undirected()
    >>> True

We can see that the first graph in the dataset contains 37 nodes, each one having 3 features.
There are 168/2 = 84 undirected edges and the graph is assigned to exactly one class.
In addition, the data object is holding exactly one graph-level target.

We can even use slices, long or bool tensors to split the dataset.
*E.g.*, to create a 90/10 train/test split, type:

.. code-block:: python

    train_dataset = dataset[:540]
    >>> ENZYMES(540)

    test_dataset = dataset[540:]
    >>> ENZYMES(60)

If you are unsure whether the dataset is already shuffled before you split, you can randomly permutate it by running:

.. code-block:: python

    dataset = dataset.shuffle()
    >>> ENZYMES(600)

This is equivalent of doing:

.. code-block:: python

    perm = torch.randperm(len(dataset))
    dataset = dataset[perm]
    >> ENZYMES(600)

Let's try another one! Let's download Cora, the standard benchmark dataset for semi-supervised graph node classification:

.. code-block:: python

    from torch_geometric.datasets import Planetoid

    dataset = Planetoid(root='/tmp/Cora', name='Cora')
    >>> Cora()

    len(dataset)
    >>> 1

    dataset.num_classes
    >>> 7

    dataset.num_node_features
    >>> 1433

Here, the dataset contains only a single, undirected citation graph:

.. code-block:: python

    data = dataset[0]
    >>> Data(edge_index=[2, 10556], test_mask=[2708],
             train_mask=[2708], val_mask=[2708], x=[2708, 1433], y=[2708])

    data.is_undirected()
    >>> True

    data.train_mask.sum().item()
    >>> 140

    data.val_mask.sum().item()
    >>> 500

    data.test_mask.sum().item()
    >>> 1000

This time, the :class:`~torch_geometric.data.Data` objects holds a label for each node, and additional node-level attributes: :obj:`train_mask`, :obj:`val_mask` and :obj:`test_mask`, where

- :obj:`train_mask` denotes against which nodes to train (140 nodes),
- :obj:`val_mask` denotes which nodes to use for validation, *e.g.*, to perform early stopping (500 nodes),
- :obj:`test_mask` denotes against which nodes to test (1000 nodes).

Mini-batches
------------

Neural networks are usually trained in a batch-wise fashion.
:pyg:`PyG` achieves parallelization over a mini-batch by creating sparse block diagonal adjacency matrices (defined by :obj:`edge_index`) and concatenating feature and target matrices in the node dimension.
This composition allows differing number of nodes and edges over examples in one batch:

.. math::

    \mathbf{A} = \begin{bmatrix} \mathbf{A}_1 & & \\ & \ddots & \\ & & \mathbf{A}_n \end{bmatrix}, \qquad \mathbf{X} = \begin{bmatrix} \mathbf{X}_1 \\ \vdots \\ \mathbf{X}_n \end{bmatrix}, \qquad \mathbf{Y} = \begin{bmatrix} \mathbf{Y}_1 \\ \vdots \\ \mathbf{Y}_n \end{bmatrix}

:pyg:`PyG` contains its own :class:`torch_geometric.loader.DataLoader`, which already takes care of this concatenation process.
Let's learn about it in an example:

.. code-block:: python

    from torch_geometric.datasets import TUDataset
    from torch_geometric.loader import DataLoader

    dataset = TUDataset(root='/tmp/ENZYMES', name='ENZYMES', use_node_attr=True)
    loader = DataLoader(dataset, batch_size=32, shuffle=True)

    for batch in loader:
        batch
        >>> DataBatch(batch=[1082], edge_index=[2, 4066], x=[1082, 21], y=[32])

        batch.num_graphs
        >>> 32

:class:`torch_geometric.data.Batch` inherits from :class:`torch_geometric.data.Data` and contains an additional attribute called :obj:`batch`.

:obj:`batch` is a column vector which maps each node to its respective graph in the batch:

.. math::

    \mathrm{batch} = {\begin{bmatrix} 0 & \cdots & 0 & 1 & \cdots & n - 2 & n -1 & \cdots & n - 1 \end{bmatrix}}^{\top}

You can use it to, *e.g.*, average node features in the node dimension for each graph individually:

.. code-block:: python

    from torch_geometric.utils import scatter
    from torch_geometric.datasets import TUDataset
    from torch_geometric.loader import DataLoader

    dataset = TUDataset(root='/tmp/ENZYMES', name='ENZYMES', use_node_attr=True)
    loader = DataLoader(dataset, batch_size=32, shuffle=True)

    for data in loader:
        data
        >>> DataBatch(batch=[1082], edge_index=[2, 4066], x=[1082, 21], y=[32])

        data.num_graphs
        >>> 32

        x = scatter(data.x, data.batch, dim=0, reduce='mean')
        x.size()
        >>> torch.Size([32, 21])

You can learn more about the internal batching procedure of :pyg:`PyG`, *e.g.*, how to modify its behavior, `here <../advanced/batching.html>`__.
For documentation of scatter operations, we refer the interested reader to the :obj:`torch_scatter` `documentation <https://pytorch-scatter.readthedocs.io>`_.

Data Transforms
---------------

Transforms are a common way in :obj:`torchvision` to transform images and perform augmentation.
:pyg:`PyG` comes with its own transforms, which expect a :class:`~torch_geometric.data.Data` object as input and return a new transformed :class:`~torch_geometric.data.Data` object.
Transforms can be chained together using :class:`torch_geometric.transforms.Compose` and are applied before saving a processed dataset on disk (:obj:`pre_transform`) or before accessing a graph in a dataset (:obj:`transform`).

Let's look at an example, where we apply transforms on the ShapeNet dataset (containing 17,000 3D shape point clouds and per point labels from 16 shape categories).

.. code-block:: python

    from torch_geometric.datasets import ShapeNet

    dataset = ShapeNet(root='/tmp/ShapeNet', categories=['Airplane'])

    dataset[0]
    >>> Data(pos=[2518, 3], y=[2518])

We can convert the point cloud dataset into a graph dataset by generating nearest neighbor graphs from the point clouds via transforms:

.. code-block:: python

    import torch_geometric.transforms as T
    from torch_geometric.datasets import ShapeNet

    dataset = ShapeNet(root='/tmp/ShapeNet', categories=['Airplane'],
                        pre_transform=T.KNNGraph(k=6))

    dataset[0]
    >>> Data(edge_index=[2, 15108], pos=[2518, 3], y=[2518])

.. note::
    We use the :obj:`pre_transform` to convert the data before saving it to disk (leading to faster loading times).
    Note that the next time the dataset is initialized it will already contain graph edges, even if you do not pass any transform.
    If the :obj:`pre_transform` does not match with the one from the already processed dataset, you will be given a warning.

In addition, we can use the :obj:`transform` argument to randomly augment a :class:`~torch_geometric.data.Data` object, *e.g.*, translating each node position by a small number:

.. code-block:: python

    import torch_geometric.transforms as T
    from torch_geometric.datasets import ShapeNet

    dataset = ShapeNet(root='/tmp/ShapeNet', categories=['Airplane'],
                        pre_transform=T.KNNGraph(k=6),
                        transform=T.RandomJitter(0.01))

    dataset[0]
    >>> Data(edge_index=[2, 15108], pos=[2518, 3], y=[2518])

You can find a complete list of all implemented transforms at :mod:`torch_geometric.transforms`.

Learning Methods on Graphs
--------------------------

After learning about data handling, datasets, loader and transforms in :pyg:`PyG`, it's time to implement our first graph neural network!

We will use a simple GCN layer and replicate the experiments on the Cora citation dataset.
For a high-level explanation on GCN, have a look at its `blog post <http://tkipf.github.io/graph-convolutional-networks/>`_.

We first need to load the Cora dataset:

.. code-block:: python

    from torch_geometric.datasets import Planetoid

    dataset = Planetoid(root='/tmp/Cora', name='Cora')
    >>> Cora()

Note that we do not need to use transforms or a dataloader.
Now let's implement a two-layer GCN:

.. code-block:: python

    import torch
    import torch.nn.functional as F
    from torch_geometric.nn import GCNConv

    class GCN(torch.nn.Module):
        def __init__(self):
            super().__init__()
            self.conv1 = GCNConv(dataset.num_node_features, 16)
            self.conv2 = GCNConv(16, dataset.num_classes)

        def forward(self, data):
            x, edge_index = data.x, data.edge_index

            x = self.conv1(x, edge_index)
            x = F.relu(x)
            x = F.dropout(x, training=self.training)
            x = self.conv2(x, edge_index)

            return F.log_softmax(x, dim=1)

The constructor defines two :class:`~torch_geometric.nn.conv.GCNConv` layers which get called in the forward pass of our network.
Note that the non-linearity is not integrated in the :obj:`conv` calls and hence needs to be applied afterwards (something which is consistent across all operators in :pyg:`PyG`).
Here, we chose to use ReLU as our intermediate non-linearity and finally output a softmax distribution over the number of classes.
Let's train this model on the training nodes for 200 epochs:

.. code-block:: python

    device = torch.device('cuda' if torch.cuda.is_available() else 'cpu')
    model = GCN().to(device)
    data = dataset[0].to(device)
    optimizer = torch.optim.Adam(model.parameters(), lr=0.01, weight_decay=5e-4)

    model.train()
    for epoch in range(200):
        optimizer.zero_grad()
        out = model(data)
        loss = F.nll_loss(out[data.train_mask], data.y[data.train_mask])
        loss.backward()
        optimizer.step()

Finally, we can evaluate our model on the test nodes:

.. code-block:: python

    model.eval()
    pred = model(data).argmax(dim=1)
    correct = (pred[data.test_mask] == data.y[data.test_mask]).sum()
    acc = int(correct) / int(data.test_mask.sum())
    print(f'Accuracy: {acc:.4f}')
    >>> Accuracy: 0.8150

This is all it takes to implement your first graph neural network.
The easiest way to learn more about Graph Neural Networks is to study the examples in the :obj:`examples/` directory and to browse :mod:`torch_geometric.nn`.
Happy hacking!

Exercises
---------

1. What does :obj:`edge_index.t().contiguous()` do?

2. Load the :obj:`"IMDB-BINARY"` dataset from the :class:`~torch_geometric.datasets.TUDataset` benchmark suite and randomly split it into 80%/10%/10% training, validation and test graphs.

3. What does each number of the following output mean?

   .. code-block:: python

       print(batch)
       >>> DataBatch(batch=[1082], edge_index=[2, 4066], x=[1082, 21], y=[32])