dgl

The dgl package contains data structure for storing structural and feature data (i.e., the DGLGraph class) and also utilities for generating, manipulating and transforming graphs.

Graph Create Ops

Operators for constructing DGLGraph from raw data formats.

graph(data, *[, num_nodes, idtype, device, ...])	Create a graph and return.
heterograph(data_dict[, num_nodes_dict, ...])	Create a heterogeneous graph and return.
from_cugraph(cugraph_graph)	Create a graph from a cugraph.Graph object.
from_scipy(sp_mat[, eweight_name, idtype, ...])	Create a graph from a SciPy sparse matrix and return.
from_networkx(nx_graph[, node_attrs, ...])	Create a graph from a NetworkX graph and return.
bipartite_from_scipy(sp_mat, utype, etype, vtype)	Create a uni-directional bipartite graph from a SciPy sparse matrix and return.
bipartite_from_networkx(nx_graph, utype, ...)	Create a unidirectional bipartite graph from a NetworkX graph and return.
rand_graph(num_nodes, num_edges[, idtype, ...])	Generate a random graph of the given number of nodes/edges and return.
rand_bipartite(utype, etype, vtype, ...[, ...])	Generate a random uni-directional bipartite graph and return.
knn_graph(x, k[, algorithm, dist, exclude_self])	Construct a graph from a set of points according to k-nearest-neighbor (KNN) and return.
segmented_knn_graph(x, k, segs[, algorithm, ...])	Construct multiple graphs from multiple sets of points according to k-nearest-neighbor (KNN) and return.
radius_graph(x, r[, p, self_loop, ...])	Construct a graph from a set of points with neighbors within given distance.
create_block(data_dict[, num_src_nodes, ...])	Create a message flow graph (MFG) as a DGLBlock object.
block_to_graph(block)	Convert a message flow graph (MFG) as a DGLBlock object to a DGLGraph.
merge(graphs)	Merge a sequence of graphs together into a single graph.

Subgraph Extraction Ops

Operators for extracting and returning subgraphs.

node_subgraph(graph, nodes, *[, ...])	Return a subgraph induced on the given nodes.
edge_subgraph(graph, edges, *[, ...])	Return a subgraph induced on the given edges.
node_type_subgraph(graph, ntypes[, ...])	Return the subgraph induced on given node types.
edge_type_subgraph(graph, etypes[, ...])	Return the subgraph induced on given edge types.
in_subgraph(graph, nodes, *[, ...])	Return the subgraph induced on the inbound edges of all the edge types of the given nodes.
out_subgraph(graph, nodes, *[, ...])	Return the subgraph induced on the outbound edges of all the edge types of the given nodes.
khop_in_subgraph(graph, nodes, k, *[, ...])	Return the subgraph induced by k-hop in-neighborhood of the specified node(s).
khop_out_subgraph(graph, nodes, k, *[, ...])	Return the subgraph induced by k-hop out-neighborhood of the specified node(s).

Graph Transform Ops

Operators for generating new graphs by manipulating the structure of the existing ones.

add_edges(g, u, v[, data, etype])	Add the edges to the graph and return a new graph.
add_nodes(g, num[, data, ntype])	Add the given number of nodes to the graph and return a new graph.
add_reverse_edges(g[, readonly, copy_ndata, ...])	Add a reversed edge for each edge in the input graph and return a new graph.
add_self_loop(g[, edge_feat_names, ...])	Add self-loops for each node in the graph and return a new graph.
adj_product_graph(A, B, weight_name[, etype])	Create a weighted graph whose adjacency matrix is the product of the adjacency matrices of the given two graphs.
adj_sum_graph(graphs, weight_name)	Create a weighted graph whose adjacency matrix is the sum of the adjacency matrices of the given graphs, whose rows represent source nodes and columns represent destination nodes.
compact_graphs(graphs[, always_preserve, ...])	Given a list of graphs with the same set of nodes, find and eliminate the common isolated nodes across all graphs.
khop_adj(g, k)	Return the matrix of \(A^k\) where \(A\) is the adjacency matrix of the graph \(g\).
khop_graph(g, k[, copy_ndata])	Return the graph whose edges connect the k-hop neighbors of the original graph.
knn_graph(x, k[, algorithm, dist, exclude_self])	Construct a graph from a set of points according to k-nearest-neighbor (KNN) and return.
laplacian_lambda_max(g)	Return the largest eigenvalue of the normalized symmetric Laplacian of a graph.
line_graph(g[, backtracking, shared])	Return the line graph of this graph.
metapath_reachable_graph(g, metapath)	Return a graph where the successors of any node u are nodes reachable from u by the given metapath.
metis_partition(g, k[, extra_cached_hops, ...])	This is to partition a graph with Metis partitioning.
metis_partition_assignment(g, k[, ...])	This assigns nodes to different partitions with Metis partitioning algorithm.
norm_by_dst(g[, etype])	Calculate normalization coefficient per edge based on destination node degree.
partition_graph_with_halo(g, node_part, ...)	Partition a graph.
radius_graph(x, r[, p, self_loop, ...])	Construct a graph from a set of points with neighbors within given distance.
remove_edges(g, eids[, etype, store_ids])	Remove the specified edges and return a new graph.
remove_nodes(g, nids[, ntype, store_ids])	Remove the specified nodes and return a new graph.
remove_self_loop(g[, etype])	Remove self-loops for each node in the graph and return a new graph.
reorder_graph(g[, node_permute_algo, ...])	Return a new graph with nodes and edges re-ordered/re-labeled according to the specified permute algorithm.
reverse(g[, copy_ndata, copy_edata, ...])	Return a new graph with every edges being the reverse ones in the input graph.
segmented_knn_graph(x, k, segs[, algorithm, ...])	Construct multiple graphs from multiple sets of points according to k-nearest-neighbor (KNN) and return.
sort_csr_by_tag(g, tag[, tag_offset_name, ...])	Return a new graph whose CSR matrix is sorted by the given tag.
sort_csc_by_tag(g, tag[, tag_offset_name, ...])	Return a new graph whose CSC matrix is sorted by the given tag.
to_bidirected(g[, copy_ndata, readonly])	Convert the graph to a bi-directional simple graph and return.
to_block(g[, dst_nodes, include_dst_in_src, ...])	Convert a graph into a bipartite-structured block for message passing.
to_cugraph(g)	Convert a DGL graph to a cugraph.Graph and return.
to_double(g)	Cast this graph to use float64 (double-precision) for any floating-point edge and node feature data.
to_float(g)	Cast this graph to use float32 (single-precision) for any floating-point edge and node feature data.
to_half(g)	Cast this graph to use float16 (half-precision) for any floating-point edge and node feature data.
to_heterogeneous(G, ntypes, etypes[, ...])	Convert a homogeneous graph to a heterogeneous graph and return.
to_homogeneous(G[, ndata, edata, ...])	Convert a heterogeneous graph to a homogeneous graph and return.
to_networkx(g[, node_attrs, edge_attrs, ...])	Convert a graph to a NetworkX graph and return.
to_simple(g[, return_counts, ...])	Convert a graph to a simple graph without parallel edges and return.
to_simple_graph(g)	Convert the graph to a simple graph with no multi-edge.

Graph Positional Encoding Ops:

Operators for generating positional encodings of each node.

random_walk_pe(g, k[, eweight_name])	Random Walk Positional Encoding, as introduced in Graph Neural Networks with Learnable Structural and Positional Representations
lap_pe(g, k[, padding, return_eigval])	Laplacian Positional Encoding, as introduced in Benchmarking Graph Neural Networks
double_radius_node_labeling(g, src, dst)	Double Radius Node Labeling, as introduced in Link Prediction Based on Graph Neural Networks.
shortest_dist(g[, root, return_paths])	Compute shortest distance and paths on the given graph.
svd_pe(g, k[, padding, random_flip])	SVD-based Positional Encoding, as introduced in Global Self-Attention as a Replacement for Graph Convolution

Graph Partition Utilities

metis_partition(g, k[, extra_cached_hops, ...])	This is to partition a graph with Metis partitioning.
metis_partition_assignment(g, k[, ...])	This assigns nodes to different partitions with Metis partitioning algorithm.
partition_graph_with_halo(g, node_part, ...)	Partition a graph.

Batching and Reading Out Ops

Operators for batching multiple graphs into one for batch processing and operators for computing graph-level representation for both single and batched graphs.

batch(graphs[, ndata, edata])	Batch a collection of DGLGraph s into one graph for more efficient graph computation.
unbatch(g[, node_split, edge_split])	Revert the batch operation by split the given graph into a list of small ones.
slice_batch(g, gid[, store_ids])	Get a particular graph from a batch of graphs.
readout_nodes(graph, feat[, weight, op, ntype])	Generate a graph-level representation by aggregating node features feat.
readout_edges(graph, feat[, weight, op, etype])	Sum the edge feature feat in graph, optionally multiplies it by a edge weight.
sum_nodes(graph, feat[, weight, ntype])	Syntax sugar for dgl.readout_nodes(graph, feat, weight, ntype=ntype, op='sum').
sum_edges(graph, feat[, weight, etype])	Syntax sugar for dgl.readout_edges(graph, feat, weight, etype=etype, op='sum').
mean_nodes(graph, feat[, weight, ntype])	Syntax sugar for dgl.readout_nodes(graph, feat, weight, ntype=ntype, op='mean').
mean_edges(graph, feat[, weight, etype])	Syntax sugar for dgl.readout_edges(graph, feat, weight, etype=etype, op='mean').
max_nodes(graph, feat[, weight, ntype])	Syntax sugar for dgl.readout_nodes(graph, feat, weight, ntype=ntype, op='max').
max_edges(graph, feat[, weight, etype])	Syntax sugar for dgl.readout_edges(graph, feat, weight, etype=etype, op='max').
softmax_nodes(graph, feat, *[, ntype])	Perform graph-wise softmax on the node features.
softmax_edges(graph, feat, *[, etype])	Perform graph-wise softmax on the edge features.
broadcast_nodes(graph, graph_feat, *[, ntype])	Generate a node feature equal to the graph-level feature graph_feat.
broadcast_edges(graph, graph_feat, *[, etype])	Generate an edge feature equal to the graph-level feature graph_feat.
topk_nodes(graph, feat, k, *[, descending, ...])	Return a graph-level representation by a graph-wise top-k on node features feat in graph by feature at index sortby.
topk_edges(graph, feat, k, *[, descending, ...])	Return a graph-level representation by a graph-wise top-k on edge features feat in graph by feature at index sortby.

Adjacency Related Utilities

Utilities for computing adjacency matrix and Lapacian matrix.

khop_adj(g, k)	Return the matrix of \(A^k\) where \(A\) is the adjacency matrix of the graph \(g\).
laplacian_lambda_max(g)	Return the largest eigenvalue of the normalized symmetric Laplacian of a graph.

Graph Traversal & Message Propagation

DGL implements graph traversal algorithms implemented as python generators, which returns the visited set of nodes or edges (in ID tensor) at each iteration. The naming convention is <algorithm>_[nodes|edges]_generator. An example usage is as follows.

g = ...  # some DGLGraph
for nodes in dgl.bfs_nodes_generator(g, 0):
    do_something(nodes)

bfs_nodes_generator(graph, source[, reverse])	Node frontiers generator using breadth-first search.
bfs_edges_generator(graph, source[, reverse])	Edges frontiers generator using breadth-first search.
topological_nodes_generator(graph[, reverse])	Node frontiers generator using topological traversal.
dfs_edges_generator(graph, source[, reverse])	Edge frontiers generator using depth-first-search (DFS).
dfs_labeled_edges_generator(graph, source[, ...])	Produce edges in a depth-first-search (DFS) labeled by type.

DGL provides APIs to perform message passing following graph traversal order. prop_nodes_XXX calls traversal algorithm XXX and triggers pull() on the visited node set at each iteration. prop_edges_YYY applies traversal algorithm YYY and triggers send_and_recv() on the visited edge set at each iteration.

prop_nodes(graph, nodes_generator[, ...])	Functional method for dgl.DGLGraph.prop_nodes().
prop_nodes_bfs(graph, source, message_func, ...)	Message propagation using node frontiers generated by BFS.
prop_nodes_topo(graph, message_func, reduce_func)	Message propagation using node frontiers generated by topological order.
prop_edges(graph, edges_generator[, ...])	Functional method for dgl.DGLGraph.prop_edges().
prop_edges_dfs(graph, source, message_func, ...)	Message propagation using edge frontiers generated by labeled DFS.

Homophily Measures

Utilities for measuring homophily of a graph

edge_homophily(graph, y)	Homophily measure from Beyond Homophily in Graph Neural Networks: Current Limitations and Effective Designs
node_homophily(graph, y)	Homophily measure from Geom-GCN: Geometric Graph Convolutional Networks
linkx_homophily(graph, y)	Homophily measure from Large Scale Learning on Non-Homophilous Graphs: New Benchmarks and Strong Simple Methods
adjusted_homophily(graph, y)	Homophily measure recommended in Characterizing Graph Datasets for Node Classification: Homophily-Heterophily Dichotomy and Beyond

Label Informativeness Measures

Utilities for measuring label informativeness of a graph

edge_label_informativeness(graph, y[, eps])	Label informativeness (\(\mathrm{LI}\)) is a characteristic of labeled graphs proposed in the Characterizing Graph Datasets for Node Classification: Homophily-Heterophily Dichotomy and Beyond
node_label_informativeness(graph, y[, eps])	Label informativeness (\(\mathrm{LI}\)) is a characteristic of labeled graphs proposed in the Characterizing Graph Datasets for Node Classification: Homophily-Heterophily Dichotomy and Beyond

Utilities

Other utilities for controlling randomness, saving and loading graphs, setting and getting runtime configurations, functions that applies the same function to every elements in a container, etc.

seed(val)	Set the random seed of DGL.
save_graphs(filename, g_list[, labels, formats])	Save graphs and optionally their labels to file.
load_graphs(filename[, idx_list])	Load graphs and optionally their labels from file saved by save_graphs().
apply_each(data, fn, *args, **kwargs)	Apply a function to every element in a container.
use_libxsmm(flag)	Set whether DGL uses libxsmm at runtime.
is_libxsmm_enabled()	Get whether the use_libxsmm flag is turned on.