torch_geometric.transforms

Compose	Composes several transforms together.
ToSparseTensor	Converts the edge_index attribute of a data object into a (transposed) torch_sparse.SparseTensor type with key adj_.t.
ToUndirected	Converts the graph to an undirected graph, so that \((j,i) \in \mathcal{E}\) for every edge \((i,j) \in \mathcal{E}\).
Constant	Adds a constant value to each node feature.
Distance	Saves the Euclidean distance of linked nodes in its edge attributes.
Cartesian	Saves the relative Cartesian coordinates of linked nodes in its edge attributes.
LocalCartesian	Saves the relative Cartesian coordinates of linked nodes in its edge attributes.
Polar	Saves the polar coordinates of linked nodes in its edge attributes.
Spherical	Saves the spherical coordinates of linked nodes in its edge attributes.
PointPairFeatures	Computes the rotation-invariant Point Pair Features
OneHotDegree	Adds the node degree as one hot encodings to the node features.
TargetIndegree	Saves the globally normalized degree of target nodes
LocalDegreeProfile	Appends the Local Degree Profile (LDP) from the “A Simple yet Effective Baseline for Non-attribute Graph Classification” paper
Center	Centers node positions around the origin.
NormalizeRotation	Rotates all points according to the eigenvectors of the point cloud.
NormalizeScale	Centers and normalizes node positions to the interval \((-1, 1)\).
RandomTranslate	Translates node positions by randomly sampled translation values within a given interval.
RandomFlip	Flips node positions along a given axis randomly with a given probability.
LinearTransformation	Transforms node positions with a square transformation matrix computed offline.
RandomScale	Scales node positions by a randomly sampled factor \(s\) within a given interval, e.g., resulting in the transformation matrix
RandomRotate	Rotates node positions around a specific axis by a randomly sampled factor within a given interval.
RandomShear	Shears node positions by randomly sampled factors \(s\) within a given interval, e.g., resulting in the transformation matrix
NormalizeFeatures	Row-normalizes node features to sum-up to one.
AddSelfLoops	Adds self-loops to edge indices.
RemoveIsolatedNodes	Removes isolated nodes from the graph.
KNNGraph	Creates a k-NN graph based on node positions pos.
RadiusGraph	Creates edges based on node positions pos to all points within a given distance.
FaceToEdge	Converts mesh faces [3, num_faces] to edge indices [2, num_edges].
SamplePoints	Uniformly samples num points on the mesh faces according to their face area.
FixedPoints	Samples a fixed number of num points and features from a point cloud.
ToDense	Converts a sparse adjacency matrix to a dense adjacency matrix with shape [num_nodes, num_nodes, *].
TwoHop	Adds the two hop edges to the edge indices.
LineGraph	Converts a graph to its corresponding line-graph:
LaplacianLambdaMax	Computes the highest eigenvalue of the graph Laplacian given by torch_geometric.utils.get_laplacian().
GenerateMeshNormals	Generate normal vectors for each mesh node based on neighboring faces.
Delaunay	Computes the delaunay triangulation of a set of points.
ToSLIC	Converts an image to a superpixel representation using the skimage.segmentation.slic() algorithm, resulting in a torch_geometric.data.Data object holding the centroids of superpixels in pos and their mean color in x.
GDC	Processes the graph via Graph Diffusion Convolution (GDC) from the “Diffusion Improves Graph Learning” paper.
SIGN	The Scalable Inception Graph Neural Network module (SIGN) from the “SIGN: Scalable Inception Graph Neural Networks” paper, which precomputes the fixed representations
GridSampling	Clusters points into voxels with size size.
GCNNorm	Applies the GCN normalization from the “Semi-supervised Classification with Graph Convolutional Networks” paper.

class AddSelfLoops

Adds self-loops to edge indices.

class Cartesian(norm=True, max_value=None, cat=True)

Saves the relative Cartesian coordinates of linked nodes in its edge attributes.

Parameters

• norm (bool, optional) – If set to False, the output will not be normalized to the interval \({[0, 1]}^D\). (default: True)

• max_value (float, optional) – If set and norm=True, normalization will be performed based on this value instead of the maximum value found in the data. (default: None)

• cat (bool, optional) – If set to False, all existing edge attributes will be replaced. (default: True)

class Center

Centers node positions around the origin.

class Compose(transforms)

Composes several transforms together.

Parameters

transforms (list of transform objects) – List of transforms to compose.

class Constant(value=1, cat=True)

Adds a constant value to each node feature.

Parameters

• value (int, optional) – The value to add. (default: 1)

• cat (bool, optional) – If set to False, all existing node features will be replaced. (default: True)

class Delaunay

Computes the delaunay triangulation of a set of points.

class Distance(norm=True, max_value=None, cat=True)

Saves the Euclidean distance of linked nodes in its edge attributes.

Parameters

• norm (bool, optional) – If set to False, the output will not be normalized to the interval \([0, 1]\). (default: True)

• max_value (float, optional) – If set and norm=True, normalization will be performed based on this value instead of the maximum value found in the data. (default: None)

• cat (bool, optional) – If set to False, all existing edge attributes will be replaced. (default: True)

class FaceToEdge(remove_faces=True)

Converts mesh faces [3, num_faces] to edge indices [2, num_edges].

Parameters

remove_faces (bool, optional) – If set to False, the face tensor will not be removed.

class FixedPoints(num, replace=True, allow_duplicates=False)

Samples a fixed number of num points and features from a point cloud.

Parameters

• num (int) – The number of points to sample.

• replace (bool, optional) – If set to False, samples points without replacement. (default: True)

• allow_duplicates (bool, optional) – In case replace is :obj`False` and num is greater than the number of points, this option determines whether to add duplicated nodes to the output points or not. In case allow_duplicates is False, the number of output points might be smaller than num. In case allow_duplicates is True, the number of duplicated points are kept to a minimum. (default: False)

class GCNNorm

Applies the GCN normalization from the “Semi-supervised Classification with Graph Convolutional Networks” paper.

\[\mathbf{\hat{A}} = \mathbf{\hat{D}}^{-1/2} (\mathbf{A} + \mathbf{I}) \mathbf{\hat{D}}^{-1/2}\]

where \(\hat{D}_{ii} = \sum_{j=0} \hat{A}_{ij} + 1\).

class GDC(self_loop_weight=1, normalization_in='sym', normalization_out='col', diffusion_kwargs={'alpha': 0.15, 'method': 'ppr'}, sparsification_kwargs={'avg_degree': 64, 'method': 'threshold'}, exact=True)

Processes the graph via Graph Diffusion Convolution (GDC) from the “Diffusion Improves Graph Learning” paper.

Note

The paper offers additional advice on how to choose the hyperparameters. For an example of using GCN with GDC, see examples/gcn.py.

Parameters

• self_loop_weight (float, optional) – Weight of the added self-loop. Set to None to add no self-loops. (default: 1)

• normalization_in (str, optional) – Normalization of the transition matrix on the original (input) graph. Possible values: "sym", "col", and "row". See GDC.transition_matrix() for details. (default: "sym")

• normalization_out (str, optional) – Normalization of the transition matrix on the transformed GDC (output) graph. Possible values: "sym", "col", "row", and None. See GDC.transition_matrix() for details. (default: "col")

• diffusion_kwargs (dict, optional) – Dictionary containing the parameters for diffusion. method specifies the diffusion method ("ppr", "heat" or "coeff"). Each diffusion method requires different additional parameters. See GDC.diffusion_matrix_exact() or GDC.diffusion_matrix_approx() for details. (default: dict(method='ppr', alpha=0.15))

• sparsification_kwargs (dict, optional) – Dictionary containing the parameters for sparsification. method specifies the sparsification method ("threshold" or "topk"). Each sparsification method requires different additional parameters. See GDC.sparsify_dense() for details. (default: dict(method='threshold', avg_degree=64))

• exact (bool, optional) – Whether to exactly calculate the diffusion matrix. Note that the exact variants are not scalable. They densify the adjacency matrix and calculate either its inverse or its matrix exponential. However, the approximate variants do not support edge weights and currently only personalized PageRank and sparsification by threshold are implemented as fast, approximate versions. (default: True)

Return type

torch_geometric.data.Data

diffusion_matrix_approx(edge_index, edge_weight, num_nodes, normalization, method, **kwargs)

Calculate the approximate, sparse diffusion on a given sparse graph.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_weight (Tensor) – One-dimensional edge weights.

• num_nodes (int) – Number of nodes.

• normalization (str) – Transition matrix normalization scheme ("sym", "row", or "col"). See GDC.transition_matrix() for details.

• method (str) –

  Diffusion method:

  1. "ppr": Use personalized PageRank as diffusion. Additionally expects the parameters:

     • alpha (float) - Return probability in PPR. Commonly lies in [0.05, 0.2].

     • eps (float) - Threshold for PPR calculation stopping criterion (edge_weight >= eps * out_degree). Recommended default: 1e-4.

Return type

(LongTensor, Tensor)

diffusion_matrix_exact(edge_index, edge_weight, num_nodes, method, **kwargs)

Calculate the (dense) diffusion on a given sparse graph. Note that these exact variants are not scalable. They densify the adjacency matrix and calculate either its inverse or its matrix exponential.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_weight (Tensor) – One-dimensional edge weights.

• num_nodes (int) – Number of nodes.

• method (str) –

  Diffusion method:

  1. "ppr": Use personalized PageRank as diffusion. Additionally expects the parameter:

     • alpha (float) - Return probability in PPR. Commonly lies in [0.05, 0.2].

  2. "heat": Use heat kernel diffusion. Additionally expects the parameter:

     • t (float) - Time of diffusion. Commonly lies in [2, 10].

  3. "coeff": Freely choose diffusion coefficients. Additionally expects the parameter:

     • coeffs (List[float]) - List of coefficients theta_k for each power of the transition matrix (starting at 0).

Return type

(Tensor)

sparsify_dense(matrix, method, **kwargs)

Sparsifies the given dense matrix.

Parameters

• matrix (Tensor) – Matrix to sparsify.

• num_nodes (int) – Number of nodes.

• method (str) –

  Method of sparsification. Options:

  1. "threshold": Remove all edges with weights smaller than eps. Additionally expects one of these parameters:

     • eps (float) - Threshold to bound edges at.

     • avg_degree (int) - If eps is not given, it can optionally be calculated by calculating the eps required to achieve a given avg_degree.

  2. "topk": Keep edges with top k edge weights per node (column). Additionally expects the following parameters:

     • k (int) - Specifies the number of edges to keep.

     • dim (int) - The axis along which to take the top k.

Return type

(LongTensor, Tensor)

sparsify_sparse(edge_index, edge_weight, num_nodes, method, **kwargs)

Sparsifies a given sparse graph further.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_weight (Tensor) – One-dimensional edge weights.

• num_nodes (int) – Number of nodes.

• method (str) –

  Method of sparsification:

  1. "threshold": Remove all edges with weights smaller than eps. Additionally expects one of these parameters:

     • eps (float) - Threshold to bound edges at.

     • avg_degree (int) - If eps is not given, it can optionally be calculated by calculating the eps required to achieve a given avg_degree.

Return type

(LongTensor, Tensor)

transition_matrix(edge_index, edge_weight, num_nodes, normalization)

Calculate the approximate, sparse diffusion on a given sparse matrix.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_weight (Tensor) – One-dimensional edge weights.

• num_nodes (int) – Number of nodes.

• normalization (str) –

  Normalization scheme:

  1. "sym": Symmetric normalization \(\mathbf{T} = \mathbf{D}^{-1/2} \mathbf{A} \mathbf{D}^{-1/2}\).

  2. "col": Column-wise normalization \(\mathbf{T} = \mathbf{A} \mathbf{D}^{-1}\).

  3. "row": Row-wise normalization \(\mathbf{T} = \mathbf{D}^{-1} \mathbf{A}\).

  4. None: No normalization.

Return type

(LongTensor, Tensor)

class GenerateMeshNormals

Generate normal vectors for each mesh node based on neighboring faces.

class GridSampling(size, start=None, end=None)

Clusters points into voxels with size size.

Parameters

• size (float or [float] or Tensor) – Size of a voxel (in each dimension).

• start (float or [float] or Tensor, optional) – Start coordinates of the grid (in each dimension). If set to None, will be set to the minimum coordinates found in data.pos. (default: None)

• end (float or [float] or Tensor, optional) – End coordinates of the grid (in each dimension). If set to None, will be set to the maximum coordinates found in data.pos. (default: None)

class KNNGraph(k=6, loop=False, force_undirected=False, flow='source_to_target')

Creates a k-NN graph based on node positions pos.

Parameters

• k (int, optional) – The number of neighbors. (default: 6)

• loop (bool, optional) – If True, the graph will contain self-loops. (default: False)

• force_undirected (bool, optional) – If set to True, new edges will be undirected. (default: False)

• flow (string, optional) – The flow direction when using in combination with message passing ("source_to_target" or "target_to_source"). (default: "source_to_target")

class LaplacianLambdaMax(normalization=None, is_undirected=False)

Computes the highest eigenvalue of the graph Laplacian given by torch_geometric.utils.get_laplacian().

Parameters

• normalization (str, optional) –

  The normalization scheme for the graph Laplacian (default: None):

  1. None: No normalization \(\mathbf{L} = \mathbf{D} - \mathbf{A}\)

  2. "sym": Symmetric normalization \(\mathbf{L} = \mathbf{I} - \mathbf{D}^{-1/2} \mathbf{A} \mathbf{D}^{-1/2}\)

  3. "rw": Random-walk normalization \(\mathbf{L} = \mathbf{I} - \mathbf{D}^{-1} \mathbf{A}\)

• is_undirected (bool, optional) – If set to True, this transform expects undirected graphs as input, and can hence speed up the computation of the largest eigenvalue. (default: False)

class LineGraph(force_directed=False)

Converts a graph to its corresponding line-graph:

\[ \begin{align}\begin{aligned}L(\mathcal{G}) &= (\mathcal{V}^{\prime}, \mathcal{E}^{\prime})\\\mathcal{V}^{\prime} &= \mathcal{E}\\\mathcal{E}^{\prime} &= \{ (e_1, e_2) : e_1 \cap e_2 \neq \emptyset \}\end{aligned}\end{align} \]

Line-graph node indices are equal to indices in the original graph’s coalesced edge_index. For undirected graphs, the maximum line-graph node index is (data.edge_index.size(1) // 2) - 1.

New node features are given by old edge attributes. For undirected graphs, edge attributes for reciprocal edges (row, col) and (col, row) get summed together.

Parameters

force_directed (bool, optional) – If set to True, the graph will be always treated as a directed graph. (default: False)

class LinearTransformation(matrix)

Transforms node positions with a square transformation matrix computed offline.

Parameters

matrix (Tensor) – tensor with shape \([D, D]\) where \(D\) corresponds to the dimensionality of node positions.

class LocalCartesian(cat=True)

Saves the relative Cartesian coordinates of linked nodes in its edge attributes. Each coordinate gets neighborhood-normalized to the interval \({[0, 1]}^D\).

Parameters

cat (bool, optional) – If set to False, all existing edge attributes will be replaced. (default: True)

class LocalDegreeProfile

Appends the Local Degree Profile (LDP) from the “A Simple yet Effective Baseline for Non-attribute Graph Classification” paper

\[\mathbf{x}_i = \mathbf{x}_i \, \Vert \, (\deg(i), \min(DN(i)), \max(DN(i)), \textrm{mean}(DN(i)), \textrm{std}(DN(i)))\]

to the node features, where \(DN(i) = \{ \deg(j) \mid j \in \mathcal{N}(i) \}\).

class NormalizeFeatures

Row-normalizes node features to sum-up to one.

class NormalizeRotation(max_points: int = - 1, sort: bool = False)

Rotates all points according to the eigenvectors of the point cloud. If the data additionally holds normals saved in data.normal, these will be rotated accordingly.

Parameters

• max_points (int, optional) – If set to a value greater than 0, only a random number of max_points points are sampled and used to compute eigenvectors. (default: -1)

• sort (bool, optional) – If set to True, will sort eigenvectors according to their eigenvalues. (default: False)

class NormalizeScale

Centers and normalizes node positions to the interval \((-1, 1)\).

class OneHotDegree(max_degree, in_degree=False, cat=True)

Adds the node degree as one hot encodings to the node features.

Parameters

• max_degree (int) – Maximum degree.

• in_degree (bool, optional) – If set to True, will compute the in-degree of nodes instead of the out-degree. (default: False)

• cat (bool, optional) – Concat node degrees to node features instead of replacing them. (default: True)

class PointPairFeatures(cat=True)

Computes the rotation-invariant Point Pair Features

\[\left( \| \mathbf{d_{j,i}} \|, \angle(\mathbf{n}_i, \mathbf{d_{j,i}}), \angle(\mathbf{n}_j, \mathbf{d_{j,i}}), \angle(\mathbf{n}_i, \mathbf{n}_j) \right)\]

of linked nodes in its edge attributes, where \(\mathbf{d}_{j,i}\) denotes the difference vector between, and \(\mathbf{n}_i\) and \(\mathbf{n}_j\) denote the surface normals of node \(i\) and \(j\) respectively.

Parameters

cat (bool, optional) – If set to False, all existing edge attributes will be replaced. (default: True)

class Polar(norm=True, max_value=None, cat=True)

Saves the polar coordinates of linked nodes in its edge attributes.

Parameters

• norm (bool, optional) – If set to False, the output will not be normalized to the interval \({[0, 1]}^2\). (default: True)

• max_value (float, optional) – If set and norm=True, normalization will be performed based on this value instead of the maximum value found in the data. (default: None)

• cat (bool, optional) – If set to False, all existing edge attributes will be replaced. (default: True)

class RadiusGraph(r, loop=False, max_num_neighbors=32, flow='source_to_target')

Creates edges based on node positions pos to all points within a given distance.

Parameters

• r (float) – The distance.

• loop (bool, optional) – If True, the graph will contain self-loops. (default: False)

• max_num_neighbors (int, optional) – The maximum number of neighbors to return for each element in y. This flag is only needed for CUDA tensors. (default: 32)

• flow (string, optional) – The flow direction when using in combination with message passing ("source_to_target" or "target_to_source"). (default: "source_to_target")

class RandomFlip(axis, p=0.5)

Flips node positions along a given axis randomly with a given probability.

Parameters

• axis (int) – The axis along the position of nodes being flipped.

• p (float, optional) – Probability that node positions will be flipped. (default: 0.5)

class RandomRotate(degrees, axis=0)

Rotates node positions around a specific axis by a randomly sampled factor within a given interval.

Parameters

• degrees (tuple or float) – Rotation interval from which the rotation angle is sampled. If degrees is a number instead of a tuple, the interval is given by \([-\mathrm{degrees}, \mathrm{degrees}]\).

• axis (int, optional) – The rotation axis. (default: 0)

class RandomScale(scales)

Scales node positions by a randomly sampled factor \(s\) within a given interval, e.g., resulting in the transformation matrix

\[\begin{split}\begin{bmatrix} s & 0 & 0 \\ 0 & s & 0 \\ 0 & 0 & s \\ \end{bmatrix}\end{split}\]

for three-dimensional positions.

Parameters

scales (tuple) – scaling factor interval, e.g. (a, b), then scale is randomly sampled from the range \(a \leq \mathrm{scale} \leq b\).

class RandomShear(shear)

Shears node positions by randomly sampled factors \(s\) within a given interval, e.g., resulting in the transformation matrix

\[\begin{split}\begin{bmatrix} 1 & s_{xy} & s_{xz} \\ s_{yx} & 1 & s_{yz} \\ s_{zx} & z_{zy} & 1 \\ \end{bmatrix}\end{split}\]

for three-dimensional positions.

Parameters

shear (float or int) – maximum shearing factor defining the range \((-\mathrm{shear}, +\mathrm{shear})\) to sample from.

class RandomTranslate(translate)

Translates node positions by randomly sampled translation values within a given interval. In contrast to other random transformations, translation is applied separately at each position.

Parameters

translate (sequence or float or int) – Maximum translation in each dimension, defining the range \((-\mathrm{translate}, +\mathrm{translate})\) to sample from. If translate is a number instead of a sequence, the same range is used for each dimension.

class RemoveIsolatedNodes

Removes isolated nodes from the graph.

class SIGN(K)

The Scalable Inception Graph Neural Network module (SIGN) from the “SIGN: Scalable Inception Graph Neural Networks” paper, which precomputes the fixed representations

\[\mathbf{X}^{(i)} = {\left( \mathbf{D}^{-1/2} \mathbf{A} \mathbf{D}^{-1/2} \right)}^i \mathbf{X}\]

for \(i \in \{ 1, \ldots, K \}\) and saves them in data.x1, data.x2, …

Note

Since intermediate node representations are pre-computed, this operator is able to scale well to large graphs via classic mini-batching. For an example of using SIGN, see examples/sign.py.

Parameters

K (int) – The number of hops/layer.

class SamplePoints(num, remove_faces=True, include_normals=False)

Uniformly samples num points on the mesh faces according to their face area.

Parameters

• num (int) – The number of points to sample.

• remove_faces (bool, optional) – If set to False, the face tensor will not be removed. (default: True)

• include_normals (bool, optional) – If set to True, then compute normals for each sampled point. (default: False)

class Spherical(norm=True, max_value=None, cat=True)

Saves the spherical coordinates of linked nodes in its edge attributes.

Parameters

• norm (bool, optional) – If set to False, the output will not be normalized to the interval \({[0, 1]}^3\). (default: True)

• max_value (float, optional) – If set and norm=True, normalization will be performed based on this value instead of the maximum value found in the data. (default: None)

• cat (bool, optional) – If set to False, all existing edge attributes will be replaced. (default: True)

class TargetIndegree(norm=True, max_value=None, cat=True)

Saves the globally normalized degree of target nodes

\[\mathbf{u}(i,j) = \frac{\deg(j)}{\max_{v \in \mathcal{V}} \deg(v)}\]

in its edge attributes.

Parameters

cat (bool, optional) – Concat pseudo-coordinates to edge attributes instead of replacing them. (default: True)

class ToDense(num_nodes=None)

Converts a sparse adjacency matrix to a dense adjacency matrix with shape [num_nodes, num_nodes, *].

Parameters

num_nodes (int) – The number of nodes. If set to None, the number of nodes will get automatically inferred. (default: None)

class ToSLIC(add_seg=False, add_img=False, **kwargs)

Converts an image to a superpixel representation using the skimage.segmentation.slic() algorithm, resulting in a torch_geometric.data.Data object holding the centroids of superpixels in pos and their mean color in x.

This transform can be used with any torchvision dataset.

Example:

from torchvision.datasets import MNIST
import torchvision.transforms as T
from torch_geometric.transforms import ToSLIC

transform = T.Compose([T.ToTensor(), ToSLIC(n_segments=75)])
dataset = MNIST('/tmp/MNIST', download=True, transform=transform)

Parameters

• add_seg (bool, optional) – If set to True, will add the segmentation result to the data object. (default: False)

• add_img (bool, optional) – If set to True, will add the input image to the data object. (default: False)

• **kwargs (optional) – Arguments to adjust the output of the SLIC algorithm. See the SLIC documentation for an overview.

class ToSparseTensor(remove_edge_index: bool = True, fill_cache: bool = True)

Converts the edge_index attribute of a data object into a (transposed) torch_sparse.SparseTensor type with key adj_.t.

Parameters

• remove_faces (bool, optional) – If set to False, the edge_index tensor will not be removed. (default: True)

• fill_cache (bool, optional) – If set to False, will not fill the underlying SparseTensor cache. (default: True)

class ToUndirected

Converts the graph to an undirected graph, so that \((j,i) \in \mathcal{E}\) for every edge \((i,j) \in \mathcal{E}\).

class TwoHop

Adds the two hop edges to the edge indices.