torch_geometric.transforms¶
Composes several transforms together. |
|
Converts the |
|
Converts the graph to an undirected graph, so 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 rotation-invariant 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 Non-attribute Graph Classification” paper |
|
Centers node positions around the origin. |
|
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 with a square transformation matrix computed offline. |
|
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 |
|
Row-normalizes node features to sum-up to one. |
|
Adds self-loops to edge indices. |
|
Removes isolated nodes from the graph. |
|
Creates a k-NN 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 line-graph: |
|
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 “Semi-supervised Classification with Graph Convolutional Networks” paper. |
|
Adds a node-level random split via |
-
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
andtest_mask
attributes to thedata
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 “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
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
Compose
(transforms)[source]¶ Composes several transforms together.
- Parameters
transforms (list of
transform
objects) – List of transforms to compose.
-
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
FaceToEdge
(remove_faces=True)[source]¶ Converts mesh faces
[3, num_faces]
to edge indices[2, num_edges]
.
-
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
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"
. 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
-
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"
). 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: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:
"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
)
-
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) – One-dimensional 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
)
-
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:
"sym"
: Symmetric normalization \(\mathbf{T} = \mathbf{D}^{-1/2} \mathbf{A} \mathbf{D}^{-1/2}\)."col"
: Column-wise normalization \(\mathbf{T} = \mathbf{A} \mathbf{D}^{-1}\)."row"
: Row-wise normalization \(\mathbf{T} = \mathbf{D}^{-1} \mathbf{A}\).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 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
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.
-
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\).
-
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
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
OneHotDegree
(max_degree, in_degree=False, cat=True)[source]¶ Adds the node degree as one hot encodings to the node features.
-
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.
-
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
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.
-
class
RandomRotate
(degrees, axis=0)[source]¶ Rotates node positions around a specific axis by a randomly sampled factor within a given interval.
-
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.
-
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
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.
-
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
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
ToDense
(num_nodes=None)[source]¶ Converts a sparse adjacency matrix to a dense adjacency matrix with shape
[num_nodes, num_nodes, *]
.
-
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
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 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.