dgl

dgl 包包含用于存储结构和特征数据的数据结构（即 DGLGraph 类），以及用于生成、操作和转换图的工具。

图创建操作

用于从原始数据格式构建 DGLGraph 的操作符。

graph(data, *[, num_nodes, idtype, device, ...])	创建一个图并返回。
heterograph(data_dict[, num_nodes_dict, ...])	创建一个异构图并返回。
from_cugraph(cugraph_graph)	从 cugraph.Graph 对象创建一个图。
from_scipy(sp_mat[, eweight_name, idtype, ...])	从 SciPy 稀疏矩阵创建一个图并返回。
from_networkx(nx_graph[, node_attrs, ...])	从 NetworkX 图创建一个图并返回。
bipartite_from_scipy(sp_mat, utype, etype, vtype)	从 SciPy 稀疏矩阵创建一个单向二分图并返回。
bipartite_from_networkx(nx_graph, utype, ...)	从 NetworkX 图创建一个单向二分图并返回。
rand_graph(num_nodes, num_edges[, idtype, ...])	生成一个具有给定节点数/边数的随机图并返回。
rand_bipartite(utype, etype, vtype, ...[, ...])	生成一个随机单向二分图并返回。
knn_graph(x, k[, algorithm, dist, exclude_self])	根据 k 近邻 (KNN) 从一组点构造一个图并返回。
segmented_knn_graph(x, k, segs[, algorithm, ...])	根据 k 近邻 (KNN) 从多组点构造多个图并返回。
radius_graph(x, r[, p, self_loop, ...])	从一组点构造一个图，其中邻居位于给定距离内。
create_block(data_dict[, num_src_nodes, ...])	创建一个消息流图 (MFG) 作为 DGLBlock 对象。
block_to_graph(block)	将消息流图 (MFG)（一个 DGLBlock 对象）转换为 DGLGraph。
merge(graphs)	将图序列合并为一个图。

子图提取操作

用于提取和返回子图的操作符。

node_subgraph(graph, nodes, *[, ...])	返回在给定节点上诱导的子图。
edge_subgraph(graph, edges, *[, ...])	返回在给定边上诱导的子图。
node_type_subgraph(graph, ntypes[, ...])	返回在给定节点类型上诱导的子图。
edge_type_subgraph(graph, etypes[, ...])	返回在给定边类型上诱导的子图。
in_subgraph(graph, nodes, *[, ...])	返回在给定节点所有边类型的入边上诱导的子图。
out_subgraph(graph, nodes, *[, ...])	返回在给定节点所有边类型的出边上诱导的子图。
khop_in_subgraph(graph, nodes, k, *[, ...])	返回由指定节点 k 跳入邻居诱导的子图。
khop_out_subgraph(graph, nodes, k, *[, ...])	返回由指定节点 k 跳出邻居诱导的子图。

图转换操作

通过操作现有图的结构来生成新图的操作符。

add_edges(g, u, v[, data, etype])	向图中添加边并返回一个新图。
add_nodes(g, num[, data, ntype])	向图中添加给定数量的节点并返回一个新图。
add_reverse_edges(g[, readonly, copy_ndata, ...])	为输入图中的每条边添加一条反向边并返回一个新图。
add_self_loop(g[, edge_feat_names, ...])	为图中的每个节点添加自环并返回一个新图。
adj_product_graph(A, B, weight_name[, etype])	创建一个加权图，其邻接矩阵是给定两个图的邻接矩阵的乘积。
adj_sum_graph(graphs, weight_name)	创建一个加权图，其邻接矩阵是给定图的邻接矩阵之和，其中行代表源节点，列代表目标节点。
compact_graphs(graphs[, always_preserve, ...])	给定一组具有相同节点集的图，找到并消除所有图中共同的孤立节点。
khop_adj(g, k)	返回矩阵 \(A^k\)，其中 \(A\) 是图 \(g\) 的邻接矩阵。
khop_graph(g, k[, copy_ndata])	返回一个图，其边连接原始图的 k 跳邻居。
knn_graph(x, k[, algorithm, dist, exclude_self])	根据 k 近邻 (KNN) 从一组点构造一个图并返回。
laplacian_lambda_max(g)	返回图的归一化对称拉普拉斯矩阵的最大特征值。
line_graph(g[, backtracking, shared])	返回此图的线图。
metapath_reachable_graph(g, metapath)	返回一个图，其中任何节点 u 的后继节点是通过给定元路径从 u 可达的节点。
metis_partition(g, k[, extra_cached_hops, ...])	这是使用 Metis 分割算法对图进行分区。
metis_partition_assignment(g, k[, ...])	这使用 Metis 分割算法将节点分配到不同的分区。
norm_by_dst(g[, etype])	基于目标节点度计算每条边的归一化系数。
partition_graph_with_halo(g, node_part, ...)	对图进行分区。
radius_graph(x, r[, p, self_loop, ...])	从一组点构造一个图，其中邻居位于给定距离内。
remove_edges(g, eids[, etype, store_ids])	移除指定的边并返回一个新图。
remove_nodes(g, nids[, ntype, store_ids])	移除指定的节点并返回一个新图。
remove_self_loop(g[, etype])	移除图中每个节点的自环并返回一个新图。
reorder_graph(g[, node_permute_algo, ...])	返回一个新图，其节点和边根据指定的排列算法进行重新排序/重新标注。
reverse(g[, copy_ndata, copy_edata, ...])	返回一个新图，其中每条边都是输入图中的反向边。
segmented_knn_graph(x, k, segs[, algorithm, ...])	根据 k 近邻 (KNN) 从多组点构造多个图并返回。
sort_csr_by_tag(g, tag[, tag_offset_name, ...])	返回一个新图，其 CSR 矩阵按给定标签排序。
sort_csc_by_tag(g, tag[, tag_offset_name, ...])	返回一个新图，其 CSC 矩阵按给定标签排序。
to_bidirected(g[, copy_ndata, readonly])	将图转换为双向简单图并返回。
to_block(g[, dst_nodes, include_dst_in_src, ...])	将图转换为双向结构的 block 用于消息传递。
to_cugraph(g)	将 DGL 图转换为 cugraph.Graph 并返回。
to_double(g)	将此图的任何浮点边和节点特征数据转换为 float64（双精度）。
to_float(g)	将此图的任何浮点边和节点特征数据转换为 float32（单精度）。
to_half(g)	将此图的任何浮点边和节点特征数据转换为 float16（半精度）。
to_heterogeneous(G, ntypes, etypes[, ...])	将同构图转换为异构图并返回。
to_homogeneous(G[, ndata, edata, ...])	将异构图转换为同构图并返回。
to_networkx(g[, node_attrs, edge_attrs, ...])	将图转换为 NetworkX 图并返回。
to_simple(g[, return_counts, ...])	将图转换为没有平行边的简单图并返回。
to_simple_graph(g)	将图转换为没有多重边的简单图。

图位置编码操作：

用于生成每个节点位置编码的操作符。

random_walk_pe(g, k[, eweight_name])	随机游走位置编码，如论文 Graph Neural Networks with Learnable Structural and Positional Representations 中介绍。
lap_pe(g, k[, padding, return_eigval])	拉普拉斯位置编码，如论文 Benchmarking Graph Neural Networks 中介绍。
double_radius_node_labeling(g, src, dst)	双半径节点标注，如论文 Link Prediction Based on Graph Neural Networks 中介绍。
shortest_dist(g[, root, return_paths])	计算给定图上的最短距离和路径。
svd_pe(g, k[, padding, random_flip])	基于 SVD 的位置编码，如论文 Global Self-Attention as a Replacement for Graph Convolution 中介绍。

图分区工具

metis_partition(g, k[, extra_cached_hops, ...])	这是使用 Metis 分割算法对图进行分区。
metis_partition_assignment(g, k[, ...])	这使用 Metis 分割算法将节点分配到不同的分区。
partition_graph_with_halo(g, node_part, ...)	对图进行分区。

批量处理与读出操作

用于将多个图批量处理成一个图的操作符，以及用于计算单个图和批量图的图级别表示的操作符。

batch(graphs[, ndata, edata])	将一组 DGLGraph 批量处理成一个图，以实现更高效的图计算。
unbatch(g[, node_split, edge_split])	通过将给定图分割成小图列表来撤销批量操作。
slice_batch(g, gid[, store_ids])	从一批图中获取特定的图。
readout_nodes(graph, feat[, weight, op, ntype])	通过聚合节点特征 feat 生成图级别表示。
readout_edges(graph, feat[, weight, op, etype])	对 graph 中的边特征 feat 求和，可选地乘以边 weight。
sum_nodes(graph, feat[, weight, ntype])	dgl.readout_nodes(graph, feat, weight, ntype=ntype, op='sum') 的语法糖。
sum_edges(graph, feat[, weight, etype])	dgl.readout_edges(graph, feat, weight, etype=etype, op='sum') 的语法糖。
mean_nodes(graph, feat[, weight, ntype])	dgl.readout_nodes(graph, feat, weight, ntype=ntype, op='mean') 的语法糖。
mean_edges(graph, feat[, weight, etype])	dgl.readout_edges(graph, feat, weight, etype=etype, op='mean') 的语法糖。
max_nodes(graph, feat[, weight, ntype])	dgl.readout_nodes(graph, feat, weight, ntype=ntype, op='max') 的语法糖。
max_edges(graph, feat[, weight, etype])	dgl.readout_edges(graph, feat, weight, etype=etype, op='max') 的语法糖。
softmax_nodes(graph, feat, *[, ntype])	对节点特征执行图级别 softmax。
softmax_edges(graph, feat, *[, etype])	对边特征执行图级别 softmax。
broadcast_nodes(graph, graph_feat, *[, ntype])	生成一个等于图级别特征 graph_feat 的节点特征。
broadcast_edges(graph, graph_feat, *[, etype])	生成一个等于图级别特征 graph_feat 的边特征。
topk_nodes(graph, feat, k, *[, descending, ...])	通过对 graph 中节点特征 feat 按索引 sortby 的特征进行图级别 top-k 操作，返回一个图级别表示。
topk_edges(graph, feat, k, *[, descending, ...])	通过对 graph 中边特征 feat 按索引 sortby 的特征进行图级别 top-k 操作，返回一个图级别表示。

邻接关系相关工具

用于计算邻接矩阵和拉普拉斯矩阵的工具。

khop_adj(g, k)	返回矩阵 \(A^k\)，其中 \(A\) 是图 \(g\) 的邻接矩阵。
laplacian_lambda_max(g)	返回图的归一化对称拉普拉斯矩阵的最大特征值。

图遍历与消息传播

DGL 实现了图遍历算法，这些算法实现为 python 生成器，在每次迭代时返回访问过的节点集或边集（以 ID 张量形式）。命名约定是 <algorithm>_[nodes|edges]_generator。一个使用示例如下。

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

bfs_nodes_generator(graph, source[, reverse])	使用广度优先搜索生成节点前沿。
bfs_edges_generator(graph, source[, reverse])	使用广度优先搜索生成边前沿。
topological_nodes_generator(graph[, reverse])	使用拓扑遍历生成节点前沿。
dfs_edges_generator(graph, source[, reverse])	使用深度优先搜索 (DFS) 生成边前沿。
dfs_labeled_edges_generator(graph, source[, ...])	生成按类型标注的深度优先搜索 (DFS) 中的边。

DGL 提供了 API，可按照图遍历顺序执行消息传递。prop_nodes_XXX 调用遍历算法 XXX，并在每次迭代时对访问过的节点集触发 pull()。prop_edges_YYY 应用遍历算法 YYY，并在每次迭代时对访问过的边集触发 send_and_recv()。

prop_nodes(graph, nodes_generator[, ...])	dgl.DGLGraph.prop_nodes() 的函数式方法。
prop_nodes_bfs(graph, source, message_func, ...)	使用 BFS 生成的节点前沿进行消息传播。
prop_nodes_topo(graph, message_func, reduce_func)	使用拓扑顺序生成的节点前沿进行消息传播。
prop_edges(graph, edges_generator[, ...])	dgl.DGLGraph.prop_edges() 的函数式方法。
prop_edges_dfs(graph, source, message_func, ...)	使用标注的 DFS 生成的边前沿进行消息传播。

同配性度量

用于度量图同配性的工具

edge_homophily(graph, y)	来自论文 Beyond Homophily in Graph Neural Networks: Current Limitations and Effective Designs 的同配性度量
node_homophily(graph, y)	来自论文 Geom-GCN: Geometric Graph Convolutional Networks 的同配性度量
linkx_homophily(graph, y)	来自论文 Large Scale Learning on Non-Homophilous Graphs: New Benchmarks and Strong Simple Methods 的同配性度量
adjusted_homophily(graph, y)	论文 Characterizing Graph Datasets for Node Classification: Homophily-Heterophily Dichotomy and Beyond 中推荐的同配性度量

标签信息量度量

用于度量图标签信息量的工具

edge_label_informativeness(graph, y[, eps])	标签信息量（\(\mathrm{LI}\)）是标注图的一个特征，在论文 Characterizing Graph Datasets for Node Classification: Homophily-Heterophily Dichotomy and Beyond 中提出。
node_label_informativeness(graph, y[, eps])	标签信息量（\(\mathrm{LI}\)）是标注图的一个特征，在论文 Characterizing Graph Datasets for Node Classification: Homophily-Heterophily Dichotomy and Beyond 中提出。

工具集

其他用于控制随机性、保存和加载图、设置和获取运行时配置、将相同函数应用于容器中每个元素的函数等工具。

seed(val)	设置 DGL 的随机种子。
save_graphs(filename, g_list[, labels, formats])	将图及其可选的标签保存到文件。
load_graphs(filename[, idx_list])	从 save_graphs() 保存的文件中加载图及其可选的标签。
apply_each(data, fn, *args, **kwargs)	将函数应用于容器中的每个元素。
use_libxsmm(flag)	设置 DGL 是否在运行时使用 libxsmm。
is_libxsmm_enabled()	获取 use_libxsmm 标志是否开启。