torch_geometric.utils

degree	Computes the (unweighted) degree of a given one-dimensional index tensor.
softmax	Computes a sparsely evaluated softmax.
dropout_adj	Randomly drops edges from the adjacency matrix (edge_index, edge_attr) with probability p using samples from a Bernoulli distribution.
sort_edge_index	Row-wise sorts edge_index.
coalesce	Row-wise sorts edge_index and removes its duplicated entries.
is_undirected	Returns True if the graph given by edge_index is undirected.
to_undirected	Converts the graph given by edge_index to an undirected graph such that \((j,i) \in \mathcal{E}\) for every edge \((i,j) \in \mathcal{E}\).
contains_self_loops	Returns True if the graph given by edge_index contains self-loops.
remove_self_loops	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}\).
segregate_self_loops	Segregates self-loops from the graph.
add_self_loops	Adds a self-loop \((i,i) \in \mathcal{E}\) to every node \(i \in \mathcal{V}\) in the graph given by edge_index.
add_remaining_self_loops	Adds remaining self-loop \((i,i) \in \mathcal{E}\) to every node \(i \in \mathcal{V}\) in the graph given by edge_index.
contains_isolated_nodes	Returns True if the graph given by edge_index contains isolated nodes.
remove_isolated_nodes	Removes the isolated nodes from the graph given by edge_index with optional edge attributes edge_attr.
subgraph	Returns the induced subgraph of (edge_index, edge_attr) containing the nodes in subset.
k_hop_subgraph	Computes the \(k\)-hop subgraph of edge_index around node node_idx.
homophily	The homophily of a graph characterizes how likely nodes with the same label are near each other in a graph.
get_laplacian	Computes the graph Laplacian of the graph given by edge_index and optional edge_weight.
to_dense_batch	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\)).
to_dense_adj	Converts batched sparse adjacency matrices given by edge indices and edge attributes to a single dense batched adjacency matrix.
dense_to_sparse	Converts a dense adjacency matrix to a sparse adjacency matrix defined by edge indices and edge attributes.
normalized_cut	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.
grid	Returns the edge indices of a two-dimensional grid graph with height height and width width and its node positions.
geodesic_distance	Computes (normalized) geodesic distances of a mesh given by pos and face.
tree_decomposition	The tree decomposition algorithm of molecules from the “Junction Tree Variational Autoencoder for Molecular Graph Generation” paper.
to_scipy_sparse_matrix	Converts a graph given by edge indices and edge attributes to a scipy sparse matrix.
from_scipy_sparse_matrix	Converts a scipy sparse matrix to edge indices and edge attributes.
to_networkx	Converts a torch_geometric.data.Data instance to a networkx.Graph if to_undirected is set to True, or a directed networkx.DiGraph otherwise.
from_networkx	Converts a networkx.Graph or networkx.DiGraph to a torch_geometric.data.Data instance.
to_trimesh	Converts a torch_geometric.data.Data instance to a trimesh.Trimesh.
from_trimesh	Converts a trimesh.Trimesh to a torch_geometric.data.Data instance.
to_cugraph	Converts a graph given by edge_index and optional edge_weight into a cugraph graph object.
erdos_renyi_graph	Returns the edge_index of a random Erdos-Renyi graph.
stochastic_blockmodel_graph	Returns the edge_index of a stochastic blockmodel graph.
barabasi_albert_graph	Returns the edge_index of a Barabasi-Albert preferential attachment model, where a graph of num_nodes nodes grows by attaching new nodes with num_edges edges that are preferentially attached to existing nodes with high degree.
negative_sampling	Samples random negative edges of a graph given by edge_index.
batched_negative_sampling	Samples random negative edges of multiple graphs given by edge_index and batch.
structured_negative_sampling	Samples a negative edge (i,k) for every positive edge (i,j) in the graph given by edge_index, and returns it as a tuple of the form (i,j,k).
structured_negative_sampling_feasible	Returns True if structured_negative_sampling() is feasible on the graph given by edge_index.
train_test_split_edges	Splits the edges of a torch_geometric.data.Data object into positive and negative train/val/test edges.
accuracy	Computes the accuracy of predictions.
true_positive	Computes the number of true positive predictions.
true_negative	Computes the number of true negative predictions.
false_positive	Computes the number of false positive predictions.
false_negative	Computes the number of false negative predictions.
precision	Computes the precision \(\frac{\mathrm{TP}}{\mathrm{TP}+\mathrm{FP}}\) of predictions.
recall	Computes the recall \(\frac{\mathrm{TP}}{\mathrm{TP}+\mathrm{FN}}\) of predictions.
f1_score	Computes the \(F_1\) score \(2 \cdot \frac{\mathrm{precision} \cdot \mathrm{recall}} {\mathrm{precision}+\mathrm{recall}}\) of predictions.
intersection_and_union	Computes intersection and union of predictions.
mean_iou	Computes the mean intersection over union score of predictions.

degree(index, num_nodes: Optional[int] = None, dtype: Optional[int] = None)

Computes the (unweighted) degree of a given one-dimensional index tensor.

Parameters

• index (LongTensor) – Index tensor.

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of index. (default: None)

• dtype (torch.dtype, optional) – The desired data type of the returned tensor.

Return type

Tensor

dropout_adj(edge_index, edge_attr=None, p=0.5, force_undirected=False, num_nodes=None, training=True)

Randomly drops edges from the adjacency matrix (edge_index, edge_attr) with probability p 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 of edge_index. (default: None)

• training (bool, optional) – If set to False, this operation is a no-op. (default: True)

sort_edge_index(edge_index: torch.Tensor, edge_attr: Optional[Union[torch.Tensor, List[torch.Tensor]]] = None, num_nodes: Optional[int] = None, sort_by_row: bool = True) → Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor], Tuple[torch.Tensor, List[torch.Tensor]]]

Row-wise sorts edge_index.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_attr (Tensor or List[Tensor], optional) – Edge weights or multi- dimensional edge features. If given as a list, will re-shuffle and remove duplicates for all its entries. (default: None)

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

• sort_by_row (bool, optional) – If set to False, will sort edge_index column-wise.

Return type

LongTensor if edge_attr is None, else (LongTensor, Tensor or List[Tensor]])

coalesce(edge_index: torch.Tensor, edge_attr: Optional[Union[torch.Tensor, List[torch.Tensor]]] = None, num_nodes: Optional[int] = None, reduce: str = 'add', is_sorted: bool = False, sort_by_row: bool = True) → Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor], Tuple[torch.Tensor, List[torch.Tensor]]]

Row-wise sorts edge_index and removes its duplicated entries. Duplicate entries in edge_attr are merged by scattering them together according to the given reduce option.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_attr (Tensor or List[Tensor], optional) – Edge weights or multi- dimensional edge features. If given as a list, will re-shuffle and remove duplicates for all its entries. (default: None)

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

• reduce (string, optional) – The reduce operation to use for merging edge features ("add", "mean", "min", "max", "mul"). (default: "add")

• is_sorted (bool, optional) – If set to True, will expect edge_index to be already sorted row-wise.

• sort_by_row (bool, optional) – If set to False, will sort edge_index column-wise.

Return type

LongTensor if edge_attr is None, else (LongTensor, Tensor or List[Tensor]])

is_undirected(edge_index: torch.Tensor, edge_attr: Optional[Union[torch.Tensor, List[torch.Tensor]]] = None, num_nodes: Optional[int] = None) → bool

Returns True if the graph given by edge_index is undirected.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_attr (Tensor or List[Tensor], optional) – Edge weights or multi- dimensional edge features. If given as a list, will check for equivalence in all its entries. (default: None)

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

Return type

bool

to_undirected(edge_index: torch.Tensor, edge_attr: Optional[Union[torch.Tensor, List[torch.Tensor]]] = None, num_nodes: Optional[int] = None, reduce: str = 'add') → Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor], Tuple[torch.Tensor, List[torch.Tensor]]]

Converts the graph given by edge_index to an undirected graph such that \((j,i) \in \mathcal{E}\) for every edge \((i,j) \in \mathcal{E}\).

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_attr (Tensor or List[Tensor], optional) – Edge weights or multi- dimensional edge features. If given as a list, will remove duplicates for all its entries. (default: None)

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

• reduce (string, optional) – The reduce operation to use for merging edge features ("add", "mean", "min", "max", "mul"). (default: "add")

Return type

LongTensor if edge_attr is None, else (LongTensor, Tensor or List[Tensor]])

contains_self_loops(edge_index: torch.Tensor) → bool

Returns True if the graph given by edge_index contains self-loops.

Parameters

edge_index (LongTensor) – The edge indices.

Return type

bool

remove_self_loops(edge_index: torch.Tensor, edge_attr: Optional[torch.Tensor] = None) → Tuple[torch.Tensor, Optional[torch.Tensor]]

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: torch.Tensor, edge_attr: Optional[torch.Tensor] = None) → Tuple[torch.Tensor, Optional[torch.Tensor], torch.Tensor, Optional[torch.Tensor]]

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: torch.Tensor, edge_attr: Optional[torch.Tensor] = None, fill_value: Optional[Union[float, torch.Tensor, str]] = None, num_nodes: Optional[int] = None) → Tuple[torch.Tensor, Optional[torch.Tensor]]

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 or has multi-dimensional edge features (edge_attr != None), edge features of self-loops will be added according to fill_value.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_attr (Tensor, optional) – Edge weights or multi-dimensional edge features. (default: None)

• fill_value (float or Tensor or str, optional) – The way to generate edge features of self-loops (in case edge_attr != None). If given as float or torch.Tensor, edge features of self-loops will be directly given by fill_value. If given as str, edge features of self-loops are computed by aggregating all features of edges that point to the specific node, according to a reduce operation. ("add", "mean", "min", "max", "mul"). (default: 1.)

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

Return type

(LongTensor, Tensor)

add_remaining_self_loops(edge_index: torch.Tensor, edge_attr: Optional[torch.Tensor] = None, fill_value: Optional[Union[float, torch.Tensor, str]] = None, num_nodes: Optional[int] = None) → Tuple[torch.Tensor, Optional[torch.Tensor]]

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 or has multi-dimensional edge features (edge_attr != None), edge features of non-existing self-loops will be added according to fill_value.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_attr (Tensor, optional) – Edge weights or multi-dimensional edge features. (default: None)

• fill_value (float or Tensor or str, optional) – The way to generate edge features of self-loops (in case edge_attr != None). If given as float or torch.Tensor, edge features of self-loops will be directly given by fill_value. If given as str, edge features of self-loops are computed by aggregating all features of edges that point to the specific node, according to a reduce operation. ("add", "mean", "min", "max", "mul"). (default: 1.)

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

Return type

(LongTensor, Tensor)

contains_isolated_nodes(edge_index, num_nodes=None)

Returns True if the graph given by edge_index contains isolated nodes.

Parameters

• edge_index (LongTensor) – The edge indices.

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

Return type

bool

remove_isolated_nodes(edge_index, edge_attr=None, num_nodes=None)

Removes the isolated nodes from the graph given by edge_index with optional edge attributes edge_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

• edge_index (LongTensor) – The edge indices.

• edge_attr (Tensor, optional) – Edge weights or multi-dimensional edge features. (default: None)

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

Return type

(LongTensor, Tensor, BoolTensor)

subgraph(subset: Union[torch.Tensor, List[int]], edge_index: torch.Tensor, edge_attr: Optional[torch.Tensor] = None, relabel_nodes: bool = False, num_nodes: Optional[int] = None, return_edge_mask: bool = False)

Returns the induced subgraph of (edge_index, edge_attr) containing the nodes in subset.

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 resulting edge_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 of edge_index. (default: None)

• return_edge_mask (bool, optional) – If set to True, will return the edge mask to filter out additional edge features. (default: False)

Return type

(LongTensor, Tensor)

k_hop_subgraph(node_idx, num_hops, edge_index, relabel_nodes=False, num_nodes=None, flow='source_to_target')

Computes the \(k\)-hop subgraph of edge_index around node node_idx. It returns (1) the nodes involved in the subgraph, (2) the filtered edge_index connectivity, (3) the mapping from node indices in node_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 resulting edge_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 of edge_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)

homophily(edge_index: Union[torch.Tensor, torch_sparse.tensor.SparseTensor], y: torch.Tensor, batch: Optional[torch.Tensor] = None, method: str = 'edge') → Union[float, torch.Tensor]

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.

• batch (LongTensor, optional) – Batch vector \(\mathbf{b} \in {\{ 0, \ldots,B-1\}}^N\), which assigns each node to a specific example. (default: None)

• method (str, optional) – The method used to calculate the homophily, either "edge" (first formula) or "node" (second formula). (default: "edge")

get_laplacian(edge_index, edge_weight: Optional[torch.Tensor] = None, normalization: Optional[str] = None, dtype: Optional[int] = None, num_nodes: Optional[int] = None)

Computes the graph Laplacian of the graph given by edge_index and optional edge_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 of edge_index. (default: None)

to_dense_batch(x: torch.Tensor, batch: Optional[torch.Tensor] = None, fill_value: float = 0.0, max_num_nodes: Optional[int] = None, batch_size: Optional[int] = None) → Tuple[torch.Tensor, torch.Tensor]

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 mask of shape \(\mathbf{M} \in \{ 0, 1 \}^{B \times N_{\max}}\) is returned, holding information about the existence of fake-nodes in the dense representation.

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. Must be ordered. (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)

• batch_size (int, optional) – None)

Return type

(Tensor, BoolTensor)

to_dense_adj(edge_index, batch=None, edge_attr=None, max_num_nodes=None)

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

dense_to_sparse(adj)

Converts a dense adjacency matrix to a sparse adjacency matrix defined by edge indices and edge attributes.

Parameters

adj – The dense adjacency matrix.

normalized_cut(edge_index, edge_attr, num_nodes: Optional[int] = None)

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

• edge_index (LongTensor) – The edge indices.

• edge_attr (Tensor) – Edge weights or multi-dimensional edge features.

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

Return type

Tensor

grid(height, width, dtype=None, device=None)

Returns the edge indices of a two-dimensional grid graph with height height and width width and its node positions.

Parameters

• height (int) – The height of the grid.

• width (int) – The width of the grid.

• dtype (torch.device, optional) – The desired data type of the returned position tensor.

• dtype – The desired device of the returned tensors.

Return type

(LongTensor, Tensor)

geodesic_distance(pos, face, src=None, dest=None, norm=True, max_distance=None, num_workers=0)

Computes (normalized) geodesic distances of a mesh given by pos and face. If src and dest 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, run pip 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

tree_decomposition(mol, return_vocab=False)

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.

Parameters

• mol (rdkit.Chem.Mol) – A rdkit molecule.

• return_vocab (bool, optional) – If set to True, will return an identifier for each clique (ring, bond, bridged compounds, single). (default: False)

Return type

(LongTensor, LongTensor, int)

to_scipy_sparse_matrix(edge_index, edge_attr=None, num_nodes=None)

Converts a graph given by edge indices and edge attributes to a scipy sparse matrix.

Parameters

• edge_index (LongTensor) – The edge indices.

• edge_attr (Tensor, optional) – Edge weights or multi-dimensional edge features. (default: None)

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of index. (default: None)

from_scipy_sparse_matrix(A)

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, to_undirected=False, remove_self_loops=False)

Converts a torch_geometric.data.Data instance to a networkx.Graph if to_undirected is set to True, or a directed networkx.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 a networkx.Graph instead of a networkx.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)

from_networkx(G, group_node_attrs: Optional[Union[List[str], all]] = None, group_edge_attrs: Optional[Union[List[str], all]] = None)

Converts a networkx.Graph or networkx.DiGraph to a torch_geometric.data.Data instance.

Parameters

• G (networkx.Graph or networkx.DiGraph) – A networkx graph.

• group_node_attrs (List[str] or all, optional) – The node attributes to be concatenated and added to data.x. (default: None)

• group_edge_attrs (List[str] or all, optional) – The edge attributes to be concatenated and added to data.edge_attr. (default: None)

Note

All group_node_attrs and group_edge_attrs values must be numeric.

to_trimesh(data)

Converts a torch_geometric.data.Data instance to a trimesh.Trimesh.

Parameters

data (torch_geometric.data.Data) – The data object.

from_trimesh(mesh)

Converts a trimesh.Trimesh to a torch_geometric.data.Data instance.

Parameters

mesh (trimesh.Trimesh) – A trimesh mesh.

to_cugraph(edge_index: torch.Tensor, edge_weight: Optional[torch.Tensor] = None, relabel_nodes: bool = True)

Converts a graph given by edge_index and optional edge_weight into a cugraph graph object.

Parameters

relabel_nodes (bool, optional) – If set to True, cugraph will remove any isolated nodes, leading to a relabeling of nodes. (default: True)

erdos_renyi_graph(num_nodes, edge_prob, directed=False)

Returns the edge_index of a random Erdos-Renyi graph.

Parameters

• num_nodes (int) – The number of nodes.

• edge_prob (float) – Probability of an edge.

• directed (bool, optional) – If set to True, will return a directed graph. (default: False)

stochastic_blockmodel_graph(block_sizes, edge_probs, directed=False)

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 from each block to each other block. Must be symmetric if the graph is undirected.

• directed (bool, optional) – If set to True, will return a directed graph. (default: False)

barabasi_albert_graph(num_nodes, num_edges)

Returns the edge_index of a Barabasi-Albert preferential attachment model, where a graph of num_nodes nodes grows by attaching new nodes with num_edges edges that are preferentially attached to existing nodes with high degree.

Parameters

• num_nodes (int) – The number of nodes.

• num_edges (int) – The number of edges from a new node to existing nodes.

negative_sampling(edge_index: torch.Tensor, num_nodes: Optional[Union[int, Tuple[int, int]]] = None, num_neg_samples: Optional[int] = None, method: str = 'sparse', force_undirected: bool = False) → torch.Tensor

Samples random negative edges of a graph given by edge_index.

Parameters

• edge_index (LongTensor) – The edge indices.

• num_nodes (int or Tuple[int, int], optional) – The number of nodes, i.e. max_val + 1 of edge_index. If given as a tuple, then edge_index is interpreted as a bipartite graph with shape (num_src_nodes, num_dst_nodes). (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

batched_negative_sampling(edge_index: torch.Tensor, batch: Union[torch.Tensor, Tuple[torch.Tensor, torch.Tensor]], num_neg_samples: Optional[int] = None, method: str = 'sparse', force_undirected: bool = False) → torch.Tensor

Samples random negative edges of multiple graphs given by edge_index and batch.

Parameters

• edge_index (LongTensor) – The edge indices.

• batch (LongTensor or Tuple[LongTensor, LongTensor]) – Batch vector \(\mathbf{b} \in {\{ 0, \ldots, B-1\}}^N\), which assigns each node to a specific example. If given as a tuple, then edge_index is interpreted as a bipartite graph connecting two different node types.

• 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

structured_negative_sampling(edge_index, num_nodes: Optional[int] = None, contains_neg_self_loops: bool = True)

Samples a negative edge (i,k) for every positive edge (i,j) in the graph given by edge_index, and returns it as a tuple of the form (i,j,k).

Parameters

• edge_index (LongTensor) – The edge indices.

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

• contains_neg_self_loops (bool, optional) – If set to False, sampled negative edges will not contain self loops. (default: True)

Return type

(LongTensor, LongTensor, LongTensor)

structured_negative_sampling_feasible(edge_index: torch.Tensor, num_nodes: Optional[int] = None, contains_neg_self_loops: bool = True) → bool

Returns True if structured_negative_sampling() is feasible on the graph given by edge_index. structured_negative_sampling is infeasible if atleast one node is connected to all other nodes.

Parameters

• edge_index (LongTensor) – The edge indices.

• num_nodes (int, optional) – The number of nodes, i.e. max_val + 1 of edge_index. (default: None)

• contains_neg_self_loops (bool, optional) – If set to False, sampled negative edges will not contain self loops. (default: True)

Return type

bool

train_test_split_edges(data, val_ratio: float = 0.05, test_ratio: float = 0.1)

Splits the edges of a torch_geometric.data.Data object into positive and negative train/val/test edges. As such, it will replace the edge_index attribute with train_pos_edge_index, train_pos_neg_adj_mask, val_pos_edge_index, val_neg_edge_index and test_pos_edge_index attributes. If data has edge features named edge_attr, then train_pos_edge_attr, val_pos_edge_attr and test_pos_edge_attr will be added as well.

Warning

train_test_split_edges() is deprecated and will be removed in a future release. Use torch_geometric.transforms.RandomLinkSplit instead.

Parameters

• data (Data) – The data object.

• val_ratio (float, optional) – The ratio of positive validation edges. (default: 0.05)

• test_ratio (float, optional) – The ratio of positive test edges. (default: 0.1)

Return type

torch_geometric.data.Data

accuracy(pred: torch.Tensor, target: torch.Tensor) → float

Computes the accuracy of predictions.

Parameters

• pred (Tensor) – The predictions.

• target (Tensor) – The targets.

Return type

float

true_positive(pred: torch.Tensor, target: torch.Tensor, num_classes: int) → torch.Tensor

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: torch.Tensor, target: torch.Tensor, num_classes: int) → torch.Tensor

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: torch.Tensor, target: torch.Tensor, num_classes: int) → torch.Tensor

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: torch.Tensor, target: torch.Tensor, num_classes: int) → torch.Tensor

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: torch.Tensor, target: torch.Tensor, num_classes: int) → torch.Tensor

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: torch.Tensor, target: torch.Tensor, num_classes: int) → torch.Tensor

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: torch.Tensor, target: torch.Tensor, num_classes: int) → torch.Tensor

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: torch.Tensor, target: torch.Tensor, num_classes: int, batch: Optional[torch.Tensor] = None) → Tuple[torch.Tensor, torch.Tensor]

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: torch.Tensor, target: torch.Tensor, num_classes: int, batch: Optional[torch.Tensor] = None, omitnans: bool = False) → torch.Tensor

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.

• omitnans (bool, optional) – If set to True, will ignore any NaN values encountered during computation. Otherwise, will treat them as 1. (default: False)

Return type

Tensor