# 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. AddTrainValTestMask Adds a node-level random split via train_mask, val_mask and test_mask attributes to the data object.
class AddSelfLoops[source]

class AddTrainValTestMask(split: str, num_splits: int = 1, num_train_per_class: int = 20, num_val: Union[int, float] = 500, num_test: Union[int, float] = 1000)[source]

Adds a node-level random split via train_mask, val_mask and test_mask attributes to the data object.

Parameters
• split (string) –

The type of dataset split ("train_rest", "test_rest", "random"). If set to "train_rest", all nodes except those in the validation and test sets will be used for training (as in the “FastGCN: Fast Learning with Graph Convolutional Networks via Importance Sampling” paper). If set to "test_rest", all nodes except those in the training and validation sets will be used for test (as in the “Pitfalls of Graph Neural Network Evaluation” paper). If set to "random", train, validation, and test sets will be randomly generated, according to num_train_per_class, num_val and num_test (as in the “Semi-supervised Classification with Graph Convolutional Networks” paper).

• num_splits (int, optional) – The number of splits to add. If bigger than 1, the shape of masks will be [num_nodes, num_splits], and [num_nodes] otherwise. (default: 1)

• num_train_per_class (int, optional) – The number of training samples per class in case of "test_rest" and "random" split. (default: 20)

• num_val (int or float, optional) – The number of validation samples. If float, it represents the ratio of samples to include in the validation set. (default: 500)

• num_test (int or float, optional) – The number of test samples in case of "train_rest" and "random" split. If float, it represents the ratio of samples to include in the test set. (default: 1000)

class Cartesian(norm=True, max_value=None, cat=True)[source]

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

Parameters
class Center[source]

Centers node positions around the origin.

class Compose(transforms)[source]

Composes several transforms together.

Parameters

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

class Constant(value=1, cat=True)[source]

Adds a constant value to each node feature.

Parameters
class Delaunay[source]

Computes the delaunay triangulation of a set of points.

class Distance(norm=True, max_value=None, cat=True)[source]

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

Parameters
class FaceToEdge(remove_faces=True)[source]

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)[source]

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 :objFalse 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(add_self_loops: bool = True)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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[source]

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

class GridSampling(size, start=None, end=None)[source]

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')[source]

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)[source]

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)[source]

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)[source]

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(norm=True, cat=True)[source]

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

Parameters
class LocalDegreeProfile[source]

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[source]

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

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

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[source]

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

class OneHotDegree(max_degree, in_degree=False, cat=True)[source]

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

Parameters
class PointPairFeatures(cat=True)[source]

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)[source]

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

Parameters
class RadiusGraph(r, loop=False, max_num_neighbors=32, flow='source_to_target')[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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[source]

Removes isolated nodes from the graph.

class SIGN(K)[source]

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)[source]

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

Parameters
class Spherical(norm=True, max_value=None, cat=True)[source]

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

Parameters
class TargetIndegree(norm=True, max_value=None, cat=True)[source]

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)[source]

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)[source]

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)])

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)[source]

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

Note

In case of composing multiple transforms, it is best to convert the data object to a SparseTensor as late as possible, since there exist some transforms that are only able to operate on data.edge_index for now.

Parameters
class ToUndirected(reduce: str = 'add')[source]

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

Parameters

reduce (string, optional) – The reduce operation to use for merging edge features. (default: "add")

class TwoHop[source]

Adds the two hop edges to the edge indices.