torch_geometric.utils¶
-
degree
(index, num_nodes=None, dtype=None)[source]¶ Computes the (unweighted) degree of a given one-dimensional index tensor.
Parameters: Return type: Tensor
-
scatter_
(name, src, index, dim=0, dim_size=None)[source]¶ Aggregates all values from the
src
tensor at the indices specified in theindex
tensor along the first dimension. If multiple indices reference the same location, their contributions are aggregated according toname
(either"add"
,"mean"
or"max"
).Parameters: - name (string) – The aggregation to use (
"add"
,"mean"
,"min"
,"max"
). - src (Tensor) – The source tensor.
- index (LongTensor) – The indices of elements to scatter.
- dim (int, optional) – The axis along which to index. (default:
0
) - dim_size (int, optional) – Automatically create output tensor with size
dim_size
in the first dimension. If set toNone
, a minimal sized output tensor is returned. (default:None
)
Return type: Tensor
- name (string) – The aggregation to use (
-
softmax
(src, index, num_nodes=None)[source]¶ Computes a sparsely evaluated softmax. Given a value tensor
src
, this function first groups the values along the first dimension based on the indices specified inindex
, and then proceeds to compute the softmax individually for each group.Parameters: Return type: Tensor
-
dropout_adj
(edge_index, edge_attr=None, p=0.5, force_undirected=False, num_nodes=None, training=True)[source]¶ Randomly drops edges from the adjacency matrix
(edge_index, edge_attr)
with probabilityp
using samples from a Bernoulli distribution.Parameters: - edge_index (LongTensor) – The edge indices.
- edge_attr (Tensor, optional) – Edge weights or multi-dimensional
edge features. (default:
None
) - p (float, optional) – Dropout probability. (default:
0.5
) - force_undirected (bool, optional) – If set to
True
, will either drop or keep both edges of an undirected edge. (default:False
) - num_nodes (int, optional) – The number of nodes, i.e.
max_val + 1
ofedge_index
. (default:None
) - training (bool, optional) – If set to
False
, this operation is a no-op. (default:True
)
-
sort_edge_index
(edge_index, edge_attr=None, num_nodes=None)[source]¶ Row-wise sorts edge indices
edge_index
.Parameters: Return type: (
LongTensor
,Tensor
)
-
is_undirected
(edge_index, edge_attr=None, num_nodes=None)[source]¶ Returns
True
if the graph given byedge_index
is undirected.Parameters: Return type:
-
to_undirected
(edge_index, num_nodes=None)[source]¶ Converts the graph given by
edge_index
to an undirected graph, so that \((j,i) \in \mathcal{E}\) for every edge \((i,j) \in \mathcal{E}\).Parameters: Return type: LongTensor
-
contains_self_loops
(edge_index)[source]¶ Returns
True
if the graph given byedge_index
contains self-loops.Parameters: edge_index (LongTensor) – The edge indices. Return type: bool
-
remove_self_loops
(edge_index, edge_attr=None)[source]¶ Removes every self-loop in the graph given by
edge_index
, so that \((i,i) \not\in \mathcal{E}\) for every \(i \in \mathcal{V}\).Parameters: - edge_index (LongTensor) – The edge indices.
- edge_attr (Tensor, optional) – Edge weights or multi-dimensional
edge features. (default:
None
)
Return type: (
LongTensor
,Tensor
)
-
segregate_self_loops
(edge_index, edge_attr=None)[source]¶ Segregates self-loops from the graph.
Parameters: - edge_index (LongTensor) – The edge indices.
- edge_attr (Tensor, optional) – Edge weights or multi-dimensional
edge features. (default:
None
)
Return type: (
LongTensor
,Tensor
,LongTensor
,Tensor
)
-
add_self_loops
(edge_index, edge_weight=None, fill_value=1, num_nodes=None)[source]¶ Adds a self-loop \((i,i) \in \mathcal{E}\) to every node \(i \in \mathcal{V}\) in the graph given by
edge_index
. In case the graph is weighted, self-loops will be added with edge weights denoted byfill_value
.Parameters: - edge_index (LongTensor) – The edge indices.
- edge_weight (Tensor, optional) – One-dimensional edge weights.
(default:
None
) - fill_value (int, optional) – If
edge_weight
is notNone
, will add self-loops with edge weights offill_value
to the graph. (default:1
) - num_nodes (int, optional) – The number of nodes, i.e.
max_val + 1
ofedge_index
. (default:None
)
Return type: (
LongTensor
,Tensor
)
-
add_remaining_self_loops
(edge_index, edge_weight=None, fill_value=1, num_nodes=None)[source]¶ Adds remaining self-loop \((i,i) \in \mathcal{E}\) to every node \(i \in \mathcal{V}\) in the graph given by
edge_index
. In case the graph is weighted and already contains a few self-loops, only non-existent self-loops will be added with edge weights denoted byfill_value
.Parameters: - edge_index (LongTensor) – The edge indices.
- edge_weight (Tensor, optional) – One-dimensional edge weights.
(default:
None
) - fill_value (int, optional) – If
edge_weight
is notNone
, will add self-loops with edge weights offill_value
to the graph. (default:1
) - num_nodes (int, optional) – The number of nodes, i.e.
max_val + 1
ofedge_index
. (default:None
)
Return type: (
LongTensor
,Tensor
)
-
contains_isolated_nodes
(edge_index, num_nodes=None)[source]¶ Returns
True
if the graph given byedge_index
contains isolated nodes.Parameters: Return type:
-
remove_isolated_nodes
(edge_index, edge_attr=None, num_nodes=None)[source]¶ Removes the isolated nodes from the graph given by
edge_index
with optional edge attributesedge_attr
. In addition, returns a mask of shape[num_nodes]
to manually filter out isolated node features later on. Self-loops are preserved for non-isolated nodes.Parameters: Return type: (LongTensor, Tensor, BoolTensor)
-
subgraph
(subset, edge_index, edge_attr=None, relabel_nodes=False, num_nodes=None)[source]¶ Returns the induced subgraph of
(edge_index, edge_attr)
containing the nodes insubset
.Parameters: - subset (LongTensor, BoolTensor or [int]) – The nodes to keep.
- edge_index (LongTensor) – The edge indices.
- edge_attr (Tensor, optional) – Edge weights or multi-dimensional
edge features. (default:
None
) - relabel_nodes (bool, optional) – If set to
True
, the resultingedge_index
will be relabeled to hold consecutive indices starting from zero. (default:False
) - num_nodes (int, optional) – The number of nodes, i.e.
max_val + 1
ofedge_index
. (default:None
)
Return type: (
LongTensor
,Tensor
)
-
get_laplacian
(edge_index, edge_weight=None, normalization=None, dtype=None, num_nodes=None)[source]¶ Computes the graph Laplacian of the graph given by
edge_index
and optionaledge_weight
.Parameters: - edge_index (LongTensor) – The edge indices.
- edge_weight (Tensor, optional) – One-dimensional edge weights.
(default:
None
) - 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}\) - dtype (torch.dtype, optional) – The desired data type of returned tensor
in case
edge_weight=None
. (default:None
) - num_nodes (int, optional) – The number of nodes, i.e.
max_val + 1
ofedge_index
. (default:None
)
-
to_dense_batch
(x, batch=None, fill_value=0)[source]¶ Given a sparse batch of node features \(\mathbf{X} \in \mathbb{R}^{(N_1 + \ldots + N_B) \times F}\) (with \(N_i\) indicating the number of nodes in graph \(i\)), creates a dense node feature tensor \(\mathbf{X} \in \mathbb{R}^{B \times N_{\max} \times F}\) (with \(N_{\max} = \max_i^B N_i\)). In addition, a second tensor holding \([N_1, \ldots, N_B] \in \mathbb{N}^B\) is returned.
Parameters: - x (Tensor) – Node feature matrix \(\mathbf{X} \in \mathbb{R}^{(N_1 + \ldots + N_B) \times F}\).
- batch (LongTensor, optional) – Batch vector
\(\mathbf{b} \in {\{ 0, \ldots, B-1\}}^N\), which assigns each
node to a specific example. (default:
None
) - fill_value (float, optional) – The value for invalid entries in the
resulting dense output tensor. (default:
0
)
Return type: (
Tensor
,BoolTensor
)
-
to_dense_adj
(edge_index, batch=None, edge_attr=None)[source]¶ Converts batched sparse adjacency matrices given by edge indices and edge attributes to a single dense batched adjacency matrix.
Parameters: Return type: Tensor
-
dense_to_sparse
(tensor)[source]¶ Converts a dense adjacency matrix to a sparse adjacency matrix defined by edge indices and edge attributes.
Parameters: tensor – The dense adjacency matrix.
-
normalized_cut
(edge_index, edge_attr, num_nodes=None)[source]¶ Computes the normalized cut \(\mathbf{e}_{i,j} \cdot \left( \frac{1}{\deg(i)} + \frac{1}{\deg(j)} \right)\) of a weighted graph given by edge indices and edge attributes.
Parameters: Return type: Tensor
-
grid
(height, width, dtype=None, device=None)[source]¶ Returns the edge indices of a two-dimensional grid graph with height
height
and widthwidth
and its node positions.Parameters: Return type: (
LongTensor
,Tensor
)
-
geodesic_distance
(pos, face, src=None, dest=None, norm=True, max_distance=None)[source]¶ Computes (normalized) geodesic distances of a mesh given by
pos
andface
. Ifsrc
anddest
are given, this method only computes the geodesic distances for the respective source and target node-pairs.Note
This function requires the
gdist
package. To install, runpip install cython && pip install gdist
.Parameters: - pos (Tensor) – The node positions.
- face (LongTensor) – The face indices.
- src (LongTensor, optional) – If given, only compute geodesic distances
for the specified source indices. (default:
None
) - dest (LongTensor, optional) – If given, only compute geodesic distances
for the specified target indices. (default:
None
) - norm (bool, optional) – Normalizes geodesic distances by
\(\sqrt{\textrm{area}(\mathcal{M})}\). (default:
True
) - max_distance (float, optional) – If given, only yields results for
geodesic distances less than
max_distance
. This will speed up runtime dramatically. (default:None
)
Return type: Tensor
-
to_scipy_sparse_matrix
(edge_index, edge_attr=None, num_nodes=None)[source]¶ Converts a graph given by edge indices and edge attributes to a scipy sparse matrix.
Parameters:
-
from_scipy_sparse_matrix
(A)[source]¶ Converts a scipy sparse matrix to edge indices and edge attributes.
Parameters: A (scipy.sparse) – A sparse matrix.
-
to_networkx
(data, node_attrs=None, edge_attrs=None)[source]¶ Converts a
torch_geometric.data.Data
instance to anetworkx.DiGraph
.Parameters: - data (torch_geometric.data.Data) – The data object.
- node_attrs (iterable of str, optional) – The node attributes to be
copied. (default:
None
) - edge_attrs (iterable of str, optional) – The edge attributes to be
copied. (default:
None
)
-
from_networkx
(G)[source]¶ Converts a
networkx.Graph
ornetworkx.DiGraph
to atorch_geometric.data.Data
instance.Parameters: G (networkx.Graph or networkx.DiGraph) – A networkx graph.
-
to_trimesh
(data)[source]¶ Converts a
torch_geometric.data.Data
instance to atrimesh.Trimesh
.Parameters: data (torch_geometric.data.Data) – The data object.
-
from_trimesh
(mesh)[source]¶ Converts a
trimesh.Trimesh
to atorch_geometric.data.Data
instance.Parameters: mesh (trimesh.Trimesh) – A trimesh
mesh.
-
erdos_renyi_graph
(num_nodes, edge_prob, directed=False)[source]¶ Returns the
edge_index
of a random Erdos-Renyi graph.Parameters:
-
stochastic_blockmodel_graph
(block_sizes, edge_probs, directed=False)[source]¶ Returns the
edge_index
of a stochastic blockmodel graph.Parameters: - block_sizes ([int] or LongTensor) – The sizes of blocks.
- edge_probs ([[float]] or FloatTensor) – The density of edges going
- each block to each other block. Must be symmetric if the graph is (from) – undirected.
- directed (bool, optional) – If set to
True
, will return a directed graph. (default:False
)
-
barabasi_albert_graph
(num_nodes, num_edges)[source]¶ Returns the
edge_index
of a Barabasi-Albert preferential attachment model, where a graph ofnum_nodes
nodes grows by attaching new nodes withnum_edges
edges that are preferentially attached to existing nodes with high degree.Parameters:
-
negative_sampling
(edge_index, num_nodes=None, num_neg_samples=None)[source]¶ Samples random negative edges of a graph given by
edge_index
.Parameters: - edge_index (LongTensor) – The edge indices.
- num_nodes (int, optional) – The number of nodes, i.e.
max_val + 1
ofedge_index
. (default:None
) - num_neg_samples (int, optional) – The number of negative samples to
return. If set to
None
, will try to return a negative edge for every positive edge. (default:None
)
Return type: LongTensor
-
structured_negative_sampling
(edge_index, num_nodes=None)[source]¶ Samples a negative edge
(i,k)
for every positive edge(i,j)
in the graph given byedge_index
, and returns it as a tuple of the form(i,j,k)
.Parameters: Return type: (LongTensor, LongTensor, LongTensor)
-
batched_negative_sampling
(edge_index, batch, num_neg_samples=None)[source]¶ Samples random negative edges of multiple graphs given by
edge_index
andbatch
.Parameters: - edge_index (LongTensor) – The edge indices.
- batch (LongTensor) – Batch vector \(\mathbf{b} \in {\{ 0, \ldots, B-1\}}^N\), which assigns each node to a specific example.
- num_neg_samples (int, optional) – The number of negative samples to
return. If set to
None
, will try to return a negative edge for every positive edge. (default:None
)
Return type: LongTensor
-
accuracy
(pred, target)[source]¶ Computes the accuracy of predictions.
Parameters: - pred (Tensor) – The predictions.
- target (Tensor) – The targets.
Return type:
-
true_positive
(pred, target, num_classes)[source]¶ Computes the number of true positive predictions.
Parameters: - pred (Tensor) – The predictions.
- target (Tensor) – The targets.
- num_classes (int) – The number of classes.
Return type: LongTensor
-
true_negative
(pred, target, num_classes)[source]¶ Computes the number of true negative predictions.
Parameters: - pred (Tensor) – The predictions.
- target (Tensor) – The targets.
- num_classes (int) – The number of classes.
Return type: LongTensor
-
false_positive
(pred, target, num_classes)[source]¶ Computes the number of false positive predictions.
Parameters: - pred (Tensor) – The predictions.
- target (Tensor) – The targets.
- num_classes (int) – The number of classes.
Return type: LongTensor
-
false_negative
(pred, target, num_classes)[source]¶ Computes the number of false negative predictions.
Parameters: - pred (Tensor) – The predictions.
- target (Tensor) – The targets.
- num_classes (int) – The number of classes.
Return type: LongTensor
-
precision
(pred, target, num_classes)[source]¶ Computes the precision \(\frac{\mathrm{TP}}{\mathrm{TP}+\mathrm{FP}}\) of predictions.
Parameters: - pred (Tensor) – The predictions.
- target (Tensor) – The targets.
- num_classes (int) – The number of classes.
Return type: Tensor
-
recall
(pred, target, num_classes)[source]¶ Computes the recall \(\frac{\mathrm{TP}}{\mathrm{TP}+\mathrm{FN}}\) of predictions.
Parameters: - pred (Tensor) – The predictions.
- target (Tensor) – The targets.
- num_classes (int) – The number of classes.
Return type: Tensor
-
f1_score
(pred, target, num_classes)[source]¶ Computes the \(F_1\) score \(2 \cdot \frac{\mathrm{precision} \cdot \mathrm{recall}} {\mathrm{precision}+\mathrm{recall}}\) of predictions.
Parameters: - pred (Tensor) – The predictions.
- target (Tensor) – The targets.
- num_classes (int) – The number of classes.
Return type: Tensor
-
intersection_and_union
(pred, target, num_classes, batch=None)[source]¶ Computes intersection and union of predictions.
Parameters: - pred (LongTensor) – The predictions.
- target (LongTensor) – The targets.
- num_classes (int) – The number of classes.
- batch (LongTensor) – The assignment vector which maps each pred-target pair to an example.
Return type: (
LongTensor
,LongTensor
)
-
mean_iou
(pred, target, num_classes, batch=None)[source]¶ Computes the mean intersection over union score of predictions.
Parameters: - pred (LongTensor) – The predictions.
- target (LongTensor) – The targets.
- num_classes (int) – The number of classes.
- batch (LongTensor) – The assignment vector which maps each pred-target pair to an example.
Return type: Tensor