torch_geometric.transforms¶
-
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
)
- norm (bool, optional) – If set to
-
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
)
- norm (bool, optional) – If set to
-
class
LocalCartesian
(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: 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: - 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
)
- norm (bool, optional) – If set to
-
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
)
- norm (bool, optional) – If set to
-
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
OneHotDegree
(max_degree, in_degree=False, cat=True)[source]¶ Adds the node degree as one hot encodings to the node features.
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
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=-1)[source]¶ 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 ofmax_points
points are sampled and used to compute eigenvectors. (default:-1
)
-
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
RandomFlip
(axis, p=0.5)[source]¶ Flips node positions along a given axis randomly with a given probability.
Parameters:
-
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
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
RandomRotate
(degrees, axis=0)[source]¶ Rotates node positions around a specific axis by a randomly sampled factor within a given interval.
Parameters:
-
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
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"
)
- k (int, optional) – The number of neighbors. (default:
-
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
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
SamplePoints
(num, remove_faces=True, include_normals=False)[source]¶ Uniformly samples
num
points on the mesh faces according to their face area.Parameters:
-
class
FixedPoints
(num, replace=True)[source]¶ Samples a fixed number of
num
points and features from a point cloud.Parameters:
-
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
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
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
)
- normalization (str, optional) –
-
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.
- add_seg (bool, optional) – If set to True, will add the segmentation
result to the data object. (default:
-
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
.
- alpha (float) - Return probability in PPR.
Commonly lies in
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]
.
- alpha (float) - Return probability in PPR.
Commonly lies in
"heat"
: Use heat kernel diffusion. Additionally expects the parameter:- t (float) - Time of diffusion. Commonly lies in
[2, 10]
.
- t (float) - Time of diffusion. Commonly lies in
"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
).
- coeffs (List[float]) - List of coefficients
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
)
- self_loop_weight (float, optional) – Weight of the added self-loop.
Set to
-
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
)