torch_geometric.transforms¶
An abstract base class for writing transforms. 

Composes several transforms together. 

Performs tensor device conversion, either for all attributes of the 

Converts the 

Converts a homogeneous or heterogeneous graph to an undirected graph such that \((j,i) \in \mathcal{E}\) for every edge \((i,j) \in \mathcal{E}\). 

Adds a constant value to each node feature 

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

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

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

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

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

Computes the rotationinvariant Point Pair Features 

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

Saves the globally normalized degree of target nodes 

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

Centers node positions 

Rotates all points according to the eigenvectors of the point cloud. 

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

Translates node positions by randomly sampled translation values within a given interval. 

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

Transforms node positions 

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

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

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

Rownormalizes the attributes given in 

Adds selfloops to the given homogeneous or heterogeneous graph. 

Removes isolated nodes from the graph. 

Creates a kNN graph based on node positions 

Creates edges based on node positions 

Converts mesh faces 

Uniformly samples 

Samples a fixed number of 

Converts a sparse adjacency matrix to a dense adjacency matrix with shape 

Adds the two hop edges to the edge indices. 

Converts a graph to its corresponding linegraph: 

Computes the highest eigenvalue of the graph Laplacian given by 

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

Computes the delaunay triangulation of a set of points. 

Converts an image to a superpixel representation using the 

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

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

Clusters points into voxels with size 

Applies the GCN normalization from the “Semisupervised Classification with Graph Convolutional Networks” paper. 

Dimensionality reduction of node features via Singular Value Decomposition (SVD). 

Removes classes from the nodelevel training set as given by 

Performs a nodelevel random split by adding 

Performs an edgelevel random split into training, validation and test sets of a 

Adds additional edge types to a 
 class BaseTransform[source]¶
An abstract base class for writing transforms.
Transforms are a general way to modify and customize
Data
objects, either by implicitly passing them as an argument to aDataset
, or by applying them explicitly to individualData
objects.import torch_geometric.transforms as T from torch_geometric.datasets import TUDataset transform = T.Compose([T.ToUndirected(), T.AddSelfLoops()]) dataset = TUDataset(path, name='MUTAG', transform=transform) data = dataset[0] # Implicitly transform data on every access. data = TUDataset(path, name='MUTAG')[0] data = transform(data) # Explicitly transform data.
 class Compose(transforms: List[Callable])[source]¶
Composes several transforms together.
 Parameters
transforms (List[Callable]) – List of transforms to compose.
 class ToDevice(device: Union[int, str], attrs: List[str] = [], non_blocking: bool = False)[source]¶
Performs tensor device conversion, either for all attributes of the
Data
object or only the ones given byattrs
. Parameters
device (torch.device) – The destination device.
attrs (List[str], optional) – If given, will only perform tensor device conversion for the given attributes. (default:
[]
)non_blocking (bool, optional) – If set to
True
and tensor values are in pinned memory, the copy will be asynchronous with respect to the host. (default:False
)
 class ToSparseTensor(attr: Optional[str] = 'edge_weight', remove_edge_index: bool = True, fill_cache: bool = True)[source]¶
Converts the
edge_index
attributes of a homogeneous or heterogeneous data object into a (transposed)torch_sparse.SparseTensor
type with keyadj_.t
.Note
In case of composing multiple transforms, it is best to convert the
data
object to aSparseTensor
as late as possible, since there exist some transforms that are only able to operate ondata.edge_index
for now. Parameters
attr – (str, optional): The name of the attribute to add as a value to the
SparseTensor
object (if present). (default:edge_weight
)remove_edge_index (bool, optional) – If set to
False
, theedge_index
tensor will not be removed. (default:True
)fill_cache (bool, optional) – If set to
False
, will not fill the underlyingSparseTensor
cache. (default:True
)
 class ToUndirected(reduce: str = 'add', merge: bool = True)[source]¶
Converts a homogeneous or heterogeneous graph to an undirected graph such that \((j,i) \in \mathcal{E}\) for every edge \((i,j) \in \mathcal{E}\). In heterogeneous graphs, will add “reverse” connections for all existing edge types.
 Parameters
reduce (string, optional) – The reduce operation to use for merging edge features (
"add"
,"mean"
,"min"
,"max"
,"mul"
). (default:"add"
)merge (bool, optional) – If set to
False
, will create reverse edge types for connections pointing to the same source and target node type. If set toTrue
, reverse edges will be merged into the original relation. This option only has effects inHeteroData
graph data. (default:True
)
 class Constant(value: float = 1.0, cat: bool = True)[source]¶
Adds a constant value to each node feature
x
.
 class Distance(norm=True, max_value=None, cat=True)[source]¶
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)[source]¶
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(norm=True, cat=True)[source]¶
Saves the relative Cartesian coordinates of linked nodes in its edge attributes. Each coordinate gets neighborhoodnormalized to the interval \({[0, 1]}^D\).
 class Polar(norm=True, max_value=None, cat=True)[source]¶
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)[source]¶
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)[source]¶
Computes the rotationinvariant 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.
 class OneHotDegree(max_degree, in_degree=False, cat=True)[source]¶
Adds the node degree as one hot encodings to the node features.
 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.
 class LocalDegreeProfile[source]¶
Appends the Local Degree Profile (LDP) from the “A Simple yet Effective Baseline for Nonattribute 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 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.
 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.
 class RandomFlip(axis, p=0.5)[source]¶
Flips node positions along a given axis randomly with a given probability.
 class LinearTransformation(matrix: torch.Tensor)[source]¶
Transforms node positions
pos
with a square transformation matrix computed offline. Parameters
matrix (Tensor) – tensor with shape
[D, D]
whereD
corresponds to the dimensionality of node positions.
 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 threedimensional 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)[source]¶
Rotates node positions around a specific axis by a randomly sampled factor within a given interval.
 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 threedimensional positions.
 class NormalizeFeatures(attrs: List[str] = ['x'])[source]¶
Rownormalizes the attributes given in
attrs
to sumup to one. Parameters
attrs (List[str]) – The names of attributes to normalize. (default:
["x"]
)
 class KNNGraph(k=6, loop=False, force_undirected=False, flow='source_to_target')[source]¶
Creates a kNN 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 selfloops. (default:False
)force_undirected (bool, optional) – If set to
True
, new edges will be undirected. (default:False
)flow (string, optional) – The flow direction when used in combination with message passing (
"source_to_target"
or"target_to_source"
). If set to"source_to_target"
, every target node will have exactly \(k\) source nodes pointing to it. (default:"source_to_target"
)
 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 selfloops. (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)[source]¶
Converts mesh faces
[3, num_faces]
to edge indices[2, num_edges]
.
 class SamplePoints(num, remove_faces=True, include_normals=False)[source]¶
Uniformly samples
num
points on the mesh faces according to their face area.
 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 :obj`False` andnum
is greater than the number of points, this option determines whether to add duplicated nodes to the output points or not. In caseallow_duplicates
isFalse
, the number of output points might be smaller thannum
. In caseallow_duplicates
isTrue
, the number of duplicated points are kept to a minimum. (default:False
)
 class ToDense(num_nodes=None)[source]¶
Converts a sparse adjacency matrix to a dense adjacency matrix with shape
[num_nodes, num_nodes, *]
.
 class LineGraph(force_directed=False)[source]¶
Converts a graph to its corresponding linegraph:
\[ \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} \]Linegraph node indices are equal to indices in the original graph’s coalesced
edge_index
. For undirected graphs, the maximum linegraph 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.
 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"
: Randomwalk 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[source]¶
Generate normal vectors for each mesh node based on neighboring faces.
 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 atorch_geometric.data.Data
object holding the centroids of superpixels inpos
and their mean color inx
.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)[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 selfloop. Set to
None
to add no selfloops. (default:1
)normalization_in (str, optional) – Normalization of the transition matrix on the original (input) graph. Possible values:
"sym"
,"col"
, and"row"
. SeeGDC.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"
, andNone
. SeeGDC.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. SeeGDC.diffusion_matrix_exact()
orGDC.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. SeeGDC.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
 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) – Onedimensional edge weights.
num_nodes (int) – Number of nodes.
normalization (str) –
Normalization scheme:
"sym"
: Symmetric normalization \(\mathbf{T} = \mathbf{D}^{1/2} \mathbf{A} \mathbf{D}^{1/2}\)."col"
: Columnwise normalization \(\mathbf{T} = \mathbf{A} \mathbf{D}^{1}\)."row"
: Rowwise normalization \(\mathbf{T} = \mathbf{D}^{1} \mathbf{A}\).None
: No normalization.
 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) – Onedimensional edge weights.
num_nodes (int) – Number of nodes.
method (str) –
Diffusion method:
"ppr"
: Use personalized PageRank as diffusion. Additionally expects the parameter:alpha (float)  Return probability in PPR. Commonly lies in
[0.05, 0.2]
.
"heat"
: Use heat kernel diffusion. Additionally expects the parameter:t (float)  Time of diffusion. Commonly lies in
[2, 10]
.
"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 at0
).
 Return type
(
Tensor
)
 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) – Onedimensional edge weights.
num_nodes (int) – Number of nodes.
normalization (str) – Transition matrix normalization scheme (
"sym"
,"row"
, or"col"
). SeeGDC.transition_matrix()
for details.method (str) –
Diffusion method:
"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:1e4
.
 Return type
(
LongTensor
,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:
"threshold"
: Remove all edges with weights smaller thaneps
. 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 theeps
required to achieve a givenavg_degree
.
"topk"
: Keep edges with topk
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) – Onedimensional edge weights.
num_nodes (int) – Number of nodes.
method (str) –
Method of sparsification:
"threshold"
: Remove all edges with weights smaller thaneps
. 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 theeps
required to achieve a givenavg_degree
.
 Return type
(
LongTensor
,Tensor
)
 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 precomputed, this operator is able to scale well to large graphs via classic minibatching. For an example of using SIGN, see examples/sign.py.
 Parameters
K (int) – The number of hops/layer.
 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 indata.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 indata.pos
. (default:None
)
 class GCNNorm(add_self_loops: bool = True)[source]¶
Applies the GCN normalization from the “Semisupervised 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 SVDFeatureReduction(out_channels)[source]¶
Dimensionality reduction of node features via Singular Value Decomposition (SVD).
 Parameters
out_channels (int) – The dimensionlity of node features after reduction.
 class RemoveTrainingClasses(classes: List[int])[source]¶
Removes classes from the nodelevel training set as given by
data.train_mask
, e.g., in order to get a zeroshot label scenario. Parameters
classes (List[int]) – The classes to remove from the training set.
 class RandomNodeSplit(split: str = 'train_rest', num_splits: int = 1, num_train_per_class: int = 20, num_val: Union[int, float] = 500, num_test: Union[int, float] = 1000, key: Optional[str] = 'y')[source]¶
Performs a nodelevel random split by adding
train_mask
,val_mask
andtest_mask
attributes to theData
orHeteroData
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 tonum_train_per_class
,num_val
andnum_test
(as in the “Semisupervised Classification with Graph Convolutional Networks” paper). (default:"train_rest"
)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
)key (str, optional) – The name of the attribute holding groundtruth labels. By default, will only add nodelevel splits for nodelevel storages in which
key
is present. (default:"y"
).
 class RandomLinkSplit(num_val: Union[int, float] = 0.1, num_test: Union[int, float] = 0.2, is_undirected: bool = False, key: str = 'edge_label', split_labels: bool = False, add_negative_train_samples: bool = True, neg_sampling_ratio: float = 1.0, disjoint_train_ratio: Union[int, float] = 0.0, edge_types: Optional[Union[Tuple[str, str, str], List[Tuple[str, str, str]]]] = None, rev_edge_types: Optional[Union[Tuple[str, str, str], List[Tuple[str, str, str]]]] = None)[source]¶
Performs an edgelevel random split into training, validation and test sets of a
Data
or aHeteroData
object. The split is performed such that the training split does not include edges in validation and test splits; and the validation split does not include edges in the test split.from torch_geometric.transforms import RandomLinkSplit transform = RandomLinkSplit(is_undirected=True) train_data, val_data, test_data = transform(data)
 Parameters
num_val (int or float, optional) – The number of validation edges. If set to a floatingpoint value in \([0, 1]\), it represents the ratio of edges to include in the validation set. (default:
0.1
)num_test (int or float, optional) – The number of test edges. If set to a floatingpoint value in \([0, 1]\), it represents the ratio of edges to include in the test set. (default:
0.2
)is_undirected (bool) – If set to
True
, the graph is assumed to be undirected, and positive and negative samples will not leak (reverse) edge connectivity across different splits. (default:False
)key (str, optional) – The name of the attribute holding groundtruth labels. If
data[key]
does not exist, it will be automatically created and represents a binary classification task (1
= edge,0
= no edge). Ifdata[key]
exists, it has to be a categorical label from0
tonum_classes  1
. After negative sampling, label0
represents negative edges, and labels1
tonum_classes
represent the labels of positive edges. (default:"edge_label"
)split_labels (bool, optional) – If set to
True
, will split positive and negative labels and save them in distinct attributes"pos_edge_label"
and"neg_edge_label"
, respectively. (default:False
)add_negative_train_samples (bool, optional) – Whether to add negative training samples for link prediction. If the model already performs negative sampling, then the option should be set to
False
. Otherwise, the added negative samples will be the same across training iterations unless negative sampling is performed again. (default:True
)neg_sampling_ratio (float, optional) – The ratio of sampled negative edges to the number of positive edges. (default:
1.0
)disjoint_train_ratio (int or float, optional) – If set to a value greater than
0.0
, training edges will not be shared for message passing and supervision. Instead, :disjoint_train_ratio` edges are used as groundtruth labels for supervision during training. (default:0.0
)edge_types (Tuple[EdgeType] or List[EdgeType], optional) – The edge types used for performing edgelevel splitting in case of operating on
HeteroData
objects. (default:None
)rev_edge_types (Tuple[EdgeType] or List[Tuple[EdgeType]], optional) – The reverse edge types of
edge_types
in case of operating onHeteroData
objects. This will ensure that edges of the reverse direction will be splitted accordingly to prevent any data leakage. Can beNone
in case no reverse connection exists. (default:None
)
 class AddMetaPaths(metapaths: List[List[Tuple[str, str, str]]], drop_orig_edges: bool = False, keep_same_node_type: bool = False)[source]¶
Adds additional edge types to a
HeteroData
object between the source node type and the destination node type of a givenmetapath
, as described in the “Heterogenous Graph Attention Networks” paper. Metapath based neighbors can exploit different aspects of structure information in heterogeneous graphs. Formally, a metapath is a path of the form\[\mathcal{V}_1 \xrightarrow{R_1} \mathcal{V}_2 \xrightarrow{R_2} \ldots \xrightarrow{R_{\ell1}} \mathcal{V}_{\ell}\]in which \(\mathcal{V}_i\) represents node types, and \(R_j\) represents the edge type connecting two node types. The added edge type is given by the sequential multiplication of adjacency matrices along the metapath, and is added to the
HeteroData
object as edge type(src_node_type, "metapath_*", dst_node_type)
, wheresrc_node_type
anddst_node_type
denote \(\mathcal{V}_1\) and \(\mathcal{V}_{\ell}\), repectively.In addition, a
metapath_dict
object is added to theHeteroData
object which maps the metapathbased edge type to its original metapath.from torch_geometric.datasets import DBLP from torch_geometric.data import HeteroData from torch_geometric.transforms import AddMetaPaths data = DBLP(root)[0] # 4 node types: "paper", "author", "conference", and "term" # 6 edge types: ("paper","author"), ("author", "paper"), # ("paper, "term"), ("paper", "conference"), # ("term, "paper"), ("conference", "paper") # Add two metapaths: # 1. From "paper" to "paper" through "conference" # 2. From "author" to "conference" through "paper" metapaths = [[("paper", "conference"), ("conference", "paper")], [("author", "paper"), ("paper", "conference")]] data = AddMetaPaths(metapaths)(data) print(data.edge_types) >>> [("author", "to", "paper"), ("paper", "to", "author"), ("paper", "to", "term"), ("paper", "to", "conference"), ("term", "to", "paper"), ("conference", "to", "paper"), ("paper", "metapath_0", "paper"), ("author", "metapath_1", "conference")] print(data.metapath_dict) >>> {("paper", "metapath_0", "paper"): [("paper", "conference"), ("conference", "paper")], ("author", "metapath_1", "conference"): [("author", "paper"), ("paper", "conference")]}
 Parameters
metapaths (List[List[Tuple[str, str, str]]]) – The metapaths described by a list of lists of
(src_node_type, rel_type, dst_node_type)
tuples.drop_orig_edges (bool, optional) – If set to
True
, existing edge types will be dropped. (default:False
)keep_same_node_type (bool, optional) – If set to
True
, existing edge types between the same node type are not dropped even in casedrop_orig_edges
is set toTrue
. (default:False
)