torch_geometric.transforms

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 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 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 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 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 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 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 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 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 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 Center

Centers node positions around the origin.

class NormalizeRotation(max_points=-1)

Rotates all points so that the eigenvectors overlie the axes of the Cartesian coordinate system. If the data additionally holds normals saved in data.norm these will be also rotated.

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)

class NormalizeScale

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

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 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 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 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 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 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 NormalizeFeatures

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

class AddSelfLoops

Adds self-loops to edge indices.

class RemoveIsolatedNodes

Removes isolated nodes from the graph.

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 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 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 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 FixedPoints(num, replace=True)

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 fixed points without replacement. In case num is greater than the number of points, duplicated points are kept to a minimum. (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 TwoHop

Adds the two hop edges to the edge indices.

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 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 GenerateMeshNormals

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

class Delaunay

Computes the delaunay triangulation of a set of points.

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