torch_geometric.utils¶
Computes the (unweighted) degree of a given one-dimensional index tensor. |
|
|
Computes a sparsely evaluated softmax. |
Randomly drops edges from the adjacency matrix |
|
Row-wise sorts edge indices |
|
Returns |
|
Converts the graph given by |
|
Returns |
|
Removes every self-loop in the graph given by |
|
Segregates self-loops from the graph. |
|
Adds a self-loop \((i,i) \in \mathcal{E}\) to every node \(i \in \mathcal{V}\) in the graph given by |
|
Adds remaining self-loop \((i,i) \in \mathcal{E}\) to every node \(i \in \mathcal{V}\) in the graph given by |
|
Returns |
|
Removes the isolated nodes from the graph given by |
|
Returns the induced subgraph of |
|
Computes the \(k\)-hop subgraph of |
|
The homophily of a graph characterizes how likely nodes with the same label are near each other in a graph. |
|
Computes the graph Laplacian of the graph given by |
|
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\)). |
|
Converts batched sparse adjacency matrices given by edge indices and edge attributes to a single dense batched adjacency matrix. |
|
Converts a dense adjacency matrix to a sparse adjacency matrix defined by edge indices and edge attributes. |
|
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. |
|
Returns the edge indices of a two-dimensional grid graph with height |
|
Computes (normalized) geodesic distances of a mesh given by |
|
The tree decomposition algorithm of molecules from the “Junction Tree Variational Autoencoder for Molecular Graph Generation” paper. |
|
Converts a graph given by edge indices and edge attributes to a scipy sparse matrix. |
|
Converts a scipy sparse matrix to edge indices and edge attributes. |
|
Converts a |
|
Converts a |
|
Converts a |
|
Converts a |
|
Converts a graph given by |
|
Returns the |
|
Returns the |
|
Returns the |
|
Samples random negative edges of a graph given by |
|
Samples a negative edge |
|
Samples random negative edges of multiple graphs given by |
|
Splits the edges of a |
|
Computes the accuracy of predictions. |
|
Computes the number of true positive predictions. |
|
Computes the number of true negative predictions. |
|
Computes the number of false positive predictions. |
|
Computes the number of false negative predictions. |
|
Computes the precision \(\frac{\mathrm{TP}}{\mathrm{TP}+\mathrm{FP}}\) of predictions. |
|
Computes the recall \(\frac{\mathrm{TP}}{\mathrm{TP}+\mathrm{FN}}\) of predictions. |
|
Computes the \(F_1\) score \(2 \cdot \frac{\mathrm{precision} \cdot \mathrm{recall}} {\mathrm{precision}+\mathrm{recall}}\) of predictions. |
|
Computes intersection and union of predictions. |
|
Computes the mean intersection over union score of predictions. |
-
accuracy
(pred, target)[source]¶ Computes the accuracy of predictions.
- Parameters
pred (Tensor) – The predictions.
target (Tensor) – The targets.
- Return type
-
add_remaining_self_loops
(edge_index, edge_weight: Optional[torch.Tensor] = None, fill_value: float = 1.0, num_nodes: Optional[int] = 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 (float, 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_self_loops
(edge_index, edge_weight: Optional[torch.Tensor] = None, fill_value: float = 1.0, num_nodes: Optional[int] = 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 (float, 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
)
-
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.
-
batched_negative_sampling
(edge_index, batch, num_neg_samples=None, method='sparse', force_undirected=False)[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
)method (string, optional) – The method to use for negative sampling, i.e.,
"sparse"
or"dense"
. This is a memory/runtime trade-off."sparse"
will work on any graph of any size, while"dense"
can perform faster true-negative checks. (default:"sparse"
)force_undirected (bool, optional) – If set to
True
, sampled negative edges will be undirected. (default:False
)
- Return type
LongTensor
-
contains_isolated_nodes
(edge_index, num_nodes=None)[source]¶ Returns
True
if the graph given byedge_index
contains isolated nodes.
-
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
-
degree
(index, num_nodes: Optional[int] = None, dtype: Optional[int] = None)[source]¶ Computes the (unweighted) degree of a given one-dimensional index 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.
-
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
)
-
erdos_renyi_graph
(num_nodes, edge_prob, directed=False)[source]¶ Returns the
edge_index
of a random Erdos-Renyi graph.
-
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
-
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
-
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
-
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.
-
from_scipy_sparse_matrix
(A)[source]¶ Converts a scipy sparse matrix to edge indices and edge attributes.
- Parameters
A (scipy.sparse) – A sparse matrix.
-
from_trimesh
(mesh)[source]¶ Converts a
trimesh.Trimesh
to atorch_geometric.data.Data
instance.- Parameters
mesh (trimesh.Trimesh) – A
trimesh
mesh.
-
geodesic_distance
(pos, face, src=None, dest=None, norm=True, max_distance=None, num_workers=0)[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
)num_workers (int, optional) – How many subprocesses to use for calculating geodesic distances.
0
means that computation takes place in the main process.-1
means that the available amount of CPU cores is used. (default:0
)
- Return type
Tensor
-
get_laplacian
(edge_index, edge_weight: Optional[torch.Tensor] = None, normalization: Optional[str] = None, dtype: Optional[int] = None, num_nodes: Optional[int] = 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
)
-
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.
-
homophily
(edge_index: Union[torch.Tensor, torch_sparse.tensor.SparseTensor], y: torch.Tensor, method: str = 'edge')[source]¶ The homophily of a graph characterizes how likely nodes with the same label are near each other in a graph. There are many measures of homophily that fits this definition. In particular:
In the “Beyond Homophily in Graph Neural Networks: Current Limitations and Effective Designs” paper, the homophily is the fraction of edges in a graph which connects nodes that have the same class label:
\[\text{homophily} = \frac{| \{ (v,w) : (v,w) \in \mathcal{E} \wedge y_v = y_w \} | } {|\mathcal{E}|}\]That measure is called the edge homophily ratio.
In the “Geom-GCN: Geometric Graph Convolutional Networks” paper, edge homophily is normalized across neighborhoods:
\[\text{homophily} = \frac{1}{|\mathcal{V}|} \sum_{v \in \mathcal{V}} \frac{ | \{ (w,v) : w \in \mathcal{N}(v) \wedge y_v = y_w \} | } { |\mathcal{N}(v)| }\]That measure is called the node homophily ratio.
- Parameters
edge_index (Tensor or SparseTensor) – The graph connectivity.
y (Tensor) – The labels.
method (str, optional) – The method used to calculate the homophily, either
"edge"
(first formula) or"node"
(second formula). (default:"edge"
)
-
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
)
-
is_undirected
(edge_index, edge_attr=None, num_nodes=None)[source]¶ Returns
True
if the graph given byedge_index
is undirected.
-
k_hop_subgraph
(node_idx, num_hops, edge_index, relabel_nodes=False, num_nodes=None, flow='source_to_target')[source]¶ Computes the \(k\)-hop subgraph of
edge_index
around nodenode_idx
. It returns (1) the nodes involved in the subgraph, (2) the filterededge_index
connectivity, (3) the mapping from node indices innode_idx
to their new location, and (4) the edge mask indicating which edges were preserved.- Parameters
node_idx (int, list, tuple or
torch.Tensor
) – The central node(s).num_hops – (int): The number of hops \(k\).
edge_index (LongTensor) – The edge indices.
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
)flow (string, optional) – The flow direction of \(k\)-hop aggregation (
"source_to_target"
or"target_to_source"
). (default:"source_to_target"
)
- Return type
(
LongTensor
,LongTensor
,LongTensor
,BoolTensor
)
-
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
-
negative_sampling
(edge_index, num_nodes=None, num_neg_samples=None, method='sparse', force_undirected=False)[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 (approximate) number of negative samples to return. If set to
None
, will try to return a negative edge for every positive edge. (default:None
)method (string, optional) – The method to use for negative sampling, i.e.,
"sparse"
or"dense"
. This is a memory/runtime trade-off."sparse"
will work on any graph of any size, while"dense"
can perform faster true-negative checks. (default:"sparse"
)force_undirected (bool, optional) – If set to
True
, sampled negative edges will be undirected. (default:False
)
- Return type
LongTensor
-
normalized_cut
(edge_index, edge_attr, num_nodes: Optional[int] = 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.
-
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
-
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.
-
remove_self_loops
(edge_index, edge_attr: Optional[torch.Tensor] = 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: Optional[torch.Tensor] = 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
)
-
sort_edge_index
(edge_index, edge_attr=None, num_nodes=None)[source]¶ Row-wise sorts edge indices
edge_index
.
-
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
)
-
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)
.
-
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
)
-
to_cugraph
(edge_index: torch.Tensor, edge_weight: Optional[torch.Tensor] = None, relabel_nodes: bool = True)[source]¶ Converts a graph given by
edge_index
and optionaledge_weight
into acugraph
graph object.
-
to_dense_adj
(edge_index, batch=None, edge_attr=None, max_num_nodes=None)[source]¶ Converts batched sparse adjacency matrices given by edge indices and edge attributes to a single dense batched adjacency matrix.
- Parameters
edge_index (LongTensor) – The edge indices.
batch (LongTensor, optional) – Batch vector \(\mathbf{b} \in {\{ 0, \ldots, B-1\}}^N\), which assigns each node to a specific example. (default:
None
)edge_attr (Tensor, optional) – Edge weights or multi-dimensional edge features. (default:
None
)max_num_nodes (int, optional) – The size of the output node dimension. (default:
None
)
- Return type
Tensor
-
to_dense_batch
(x, batch=None, fill_value=0, max_num_nodes=None)[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
)max_num_nodes (int, optional) – The size of the output node dimension. (default:
None
)
- Return type
(
Tensor
,BoolTensor
)
-
to_networkx
(data, node_attrs=None, edge_attrs=None, to_undirected=False, remove_self_loops=False)[source]¶ Converts a
torch_geometric.data.Data
instance to anetworkx.Graph
ifto_undirected
is set toTrue
, or a directednetworkx.DiGraph
otherwise.- 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
)to_undirected (bool, optional) – If set to
True
, will return a anetworkx.Graph
instead of anetworkx.DiGraph
. The undirected graph will correspond to the upper triangle of the corresponding adjacency matrix. (default:False
)remove_self_loops (bool, optional) – If set to
True
, will not include self loops in the resulting graph. (default:False
)
-
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.
-
to_trimesh
(data)[source]¶ Converts a
torch_geometric.data.Data
instance to atrimesh.Trimesh
.- Parameters
data (torch_geometric.data.Data) – The data object.
-
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}\).
-
train_test_split_edges
(data, val_ratio=0.05, test_ratio=0.1)[source]¶ Splits the edges of a
torch_geometric.data.Data
object into positive and negative train/val/test edges, and adds attributes of train_pos_edge_index, train_neg_adj_mask, val_pos_edge_index, val_neg_edge_index, test_pos_edge_index, and test_neg_edge_index todata
.- Parameters
- Return type
-
tree_decomposition
(mol, return_vocab=False)[source]¶ The tree decomposition algorithm of molecules from the “Junction Tree Variational Autoencoder for Molecular Graph Generation” paper. Returns the graph connectivity of the junction tree, the assignment mapping of each atom to the clique in the junction tree, and the number of cliques.