DGL官方教程--API--dgl.DGLHeteroGraph

 

class dgl.DGLHeteroGraph(gidx, ntypes, etypes, node_frames=None, edge_frames=None)

基本异构图类。

不要直接从该类实例化；使用conversion methods来代替。

异构图被定义为具有节点类型和边类型的图。

如果两个边缘是相同的边类型，则它们的源节点以及目标节点也具有相同的类型（源节点类型不必与目标节点类型相同）。

例子

假设我们要构造以下异构图：

 

 

并假设将用户，游戏和开发人员映射到以下ID：

用户名	Alice	Bob	Carol
用户ID	0	1	2

游戏名称	Tetris(俄罗斯方块)	Minecraft(我的世界)
游戏ID	0	1

开发者名称	Nintendo(任天堂)	Mojang
开发者编号	0	1

可以如下构建图形：

>>> follows_g = dgl.graph([(0, 1), (1, 2)], 'user', 'follows')
>>> plays_g = dgl.bipartite([(0, 0), (1, 0), (1, 1), (2, 1)], 'user', 'plays', 'game')
>>> devs_g = dgl.bipartite([(0, 0), (1, 1)], 'developer', 'develops', 'game')
>>> g = dgl.hetero_from_relations([follows_g, plays_g, devs_g])

 

或同等

>>> g = dgl.heterograph({
...     ('user', 'follows', 'user'): [(0, 1), (1, 2)],
...     ('user', 'plays', 'game'): [(0, 0), (1, 0), (1, 1), (2, 1)],
...     ('developer', 'develops', 'game'): [(0, 0), (1, 1)],
...     })

('user', 'follows', 'user')是直接指定的节点，边的类型

dgl.graph()和dgl.bipartite()可以根据多种数据类型创建图形，包括：

• 边列表
• 边元组
• networkx图
• scipy稀疏矩阵

单击函数名称以获取更多详细信息。

PS：https://docs.dgl.ai/en/latest/api/python/heterograph.html

然后，可以通过指定ntype或etype参数来查询图结构：

>>> g.number_of_nodes('user')
3
>>> g.number_of_edges('plays')
4
>>> g.out_degrees(etype='develops')  # 'develops' 关系的源节点的出度
tensor([1, 1])
>>> g.in_edges(0, etype='develops')  # 'develops' 关系的目的节点0的入度
(tensor([0]), tensor([0]))

或在边缘类型的切片图上：

>>> g['plays'].number_of_edges()
4
>>> g['develops'].out_degrees()
tensor([1, 1])
>>> g['develops'].in_edges(0)
(tensor([0]), tensor([0]))

节点类型名称必须是不同的（没有两个类型具有相同的名称）。边缘类型可以使用相同的名称，但是它们必须通过 (src_type,edge_type,dst_type)三元组来区分（称为规范边缘类型）。

例如，假设一个图形具有以下两种类型的关系“ user-watches-movie”和“ user-watches-TV”：

>>> g0 = dgl.bipartite([(0, 1), (1, 0), (1, 1)], 'user', 'watches', 'movie')
>>> g1 = dgl.bipartite([(0, 0), (1, 1)], 'user', 'watches', 'TV')
>>> GG = dgl.hetero_from_relations([g0, g1]) # Merge the two graphs

要区分两个“watches”边缘类型，必须指定完整的三元组：

>>> GG.number_of_edges(('user', 'watches', 'movie'))
3
>>> GG.number_of_edges(('user', 'watches', 'TV'))
2
>>> GG['user', 'watches', 'movie'].out_degrees()
tensor([1, 2])

仅使用一个单边类型字符串“ watches”是模棱两可的，并且会导致错误：

>>> GG.number_of_edges('watches')  # AMBIGUOUS!!

在许多情况下，只有一种类型的节点或一种类型的边缘，并且ntype和etype参数是可以省略。这在使用切片图时非常常见，该切片图通常仅包含一种边缘类型，有时仅包含一种节点类型：

>>> g['follows'].number_of_nodes()  # OK!! because g['follows'] only has one node type 'user'
3
>>> g['plays'].number_of_nodes()  # ERROR!! There are two types 'user' and 'game'.
>>> g['plays'].number_of_edges()  # OK!! because there is only one edge type 'plays'

TODO（minjie）：关于单向二部图的文档字符串

对于每个异构图表，经常可以推断元图，即表示图中存在多少种节点和边的边连接模板，以及每种边类型如何在节点类型之间连接。

可以分析上面的示例游戏图，并计算出如下所示的图解：

 

参数：	gidx（HeteroGraphIndex）–图形索引对象。 ntypes（str的列表，str的列表对） -节点类型列表。ntypes[i]存储节点类型i的名称。如果给定一对，则创建的图是单向bipartite图，并且其SRC节点类型和DST节点类型按对给出。 etypes（str的列表）–边缘类型列表。etypes[i]存储边类型i的名称。 node_frames（FrameRef 列表，可选）–节点功能存储。如果为None，则创建空框架。否则，node_frames[i]存储节点类型为i的节点特征。（默认值：无） edge_frames（FrameRef 列表，可选）–边缘要素存储。如果为None，则创建空框架。否则，edge_frames[i]存储边缘类型为i的边缘特征。（默认值：无）

与异构图之间的转换

用于将图形与其他对象相互转换的模块。

graph(data[, ntype, etype, num_nodes, card, …])	创建具有一种类型的节点和边的图形。
bipartite(data[, utype, etype, vtype, …])	创建二部图。
hetero_from_relations(rel_graphs[, …])	从表示每个关系的连接的图创建异型图。
heterograph(data_dict[, num_nodes_dict])	根据边缘类型和边缘列表之间的字典创建异构图形。
to_hetero(G, ntypes, etypes[, ntype_field, …])	将给定的同构图转换为异构图。
to_homo(G)	将给定的异构图转换为同构图。
to_networkx(g[, node_attrs, edge_attrs])	转换为networkx图。
DGLHeteroGraph.adjacency_matrix([transpose, …])	返回给定边类型的边的邻接矩阵。
DGLHeteroGraph.incidence_matrix(typestr[, …])	返回具有给定边缘类型的边缘的入射矩阵表示形式。

查询元图结构

DGLHeteroGraph.ntypes	返回此图的节点类型列表。
DGLHeteroGraph.etypes	返回此图的边类型列表。
DGLHeteroGraph.canonical_etypes	返回此图的规范边缘类型的列表。
DGLHeteroGraph.metagraph	将元图作为networkx.MultiDiGraph返回。
DGLHeteroGraph.to_canonical_etype(etype)	将边线类型转换为规范的etype：（srctype，etype，dsttype）。
DGLHeteroGraph.get_ntype_id(ntype)	返回给定节点类型的ID。
DGLHeteroGraph.get_etype_id(etype)	返回给定边类型的ID。

查询图结构

DGLHeteroGraph.number_of_nodes([ntype])	返回异构图中给定类型的节点数。
DGLHeteroGraph.number_of_edges([etype])	返回异构图中给定类型的边数。
DGLHeteroGraph.is_multigraph	图是否为多图
DGLHeteroGraph.is_readonly	该图是否为只读
DGLHeteroGraph.has_node(vid[, ntype])	该图是否具有具有特定ID和类型的节点。
DGLHeteroGraph.has_nodes(vids[, ntype])	该图是否具有ID和特定类型的节点。
DGLHeteroGraph.has_edge_between(u, v[, etype])	图是否具有类型为etype的边（u，v）。
DGLHeteroGraph.has_edges_between(u, v[, etype])	图是否具有type的边etype。
DGLHeteroGraph.predecessors(v[, etype])	返回图中具有指定边类型的节点v的前任。
DGLHeteroGraph.successors(v[, etype])	返回具有指定边类型的图中节点v的后继。
DGLHeteroGraph.edge_id(u, v[, force_multi, …])	返回源节点u和目标节点v之间具有指定边缘类型的边缘ID或边缘ID数组
DGLHeteroGraph.edge_ids(u, v[, force_multi, …])	返回具有指定边缘类型的源节点阵列u和目标节点阵列v之间的所有边缘ID 。
DGLHeteroGraph.find_edges(eid[, etype])	给定具有指定类型的边缘ID数组，返回源和目标节点ID数组s和d。
DGLHeteroGraph.in_edges(v[, form, etype])	返回具有指定类型的节点的入站边缘。
DGLHeteroGraph.out_edges(u[, form, etype])	返回具有指定类型的节点的出站边缘。
DGLHeteroGraph.all_edges([form, order, etype])	返回具有指定类型的所有边。
DGLHeteroGraph.in_degree(v[, etype])	返回v边的类型为的节点的入度etype。
DGLHeteroGraph.in_degrees(v[, etype])	返回边类型为的节点v的度数etype。
DGLHeteroGraph.out_degree(u[, etype])	返回类型为的边u的出度etype。
DGLHeteroGraph.out_degrees(u[, etype])	返回类型为的边u的出度etype。

使用节点/边缘特征

DGLHeteroGraph.nodes	返回可用于设置/获取单个节点类型的要素数据的节点视图。
DGLHeteroGraph.ndata	返回所有节点的数据视图。
DGLHeteroGraph.edges	返回可用于设置/获取单个边缘类型的要素数据的边缘视图。
DGLHeteroGraph.edata	返回所有边的数据视图。
DGLHeteroGraph.node_attr_schemes([ntype])	返回指定类型的节点要素方案。
DGLHeteroGraph.edge_attr_schemes([etype])	返回指定类型的边缘特征方案。
DGLHeteroGraph.set_n_initializer(initializer)	为空节点功能设置初始化程序。
DGLHeteroGraph.set_e_initializer(initializer)	为空边缘特征设置初始值设定项。
DGLHeteroGraph.local_var()	返回可以在局部函数范围内使用的异形图对象。
DGLHeteroGraph.local_scope()	输入此图的本地范围上下文。

改造图

DGLHeteroGraph.subgraph(nodes)	返回在给定节点上诱导的子图。
DGLHeteroGraph.edge_subgraph(edges[, …])	返回在给定边上诱导的子图。
DGLHeteroGraph.node_type_subgraph(ntypes)	返回在给定节点类型上诱导的子图。
DGLHeteroGraph.edge_type_subgraph(etypes)	返回在给定边缘类型上诱导的子图。

使用DGLHeteroGraph计算

DGLHeteroGraph.apply_nodes(func[, v, ntype, …])	将功能应用于具有相同类型的节点以更新其功能。
DGLHeteroGraph.apply_edges(func[, edges, …])	将功能应用于相同类型的边缘以更新其功能。
DGLHeteroGraph.group_apply_edges(group_by, func)	按节点对边缘进行分组，并应用分组的边缘的功能以更新其特征。
DGLHeteroGraph.send(edges, message_func[, etype])	沿给定的边缘以相同的边缘类型发送消息。
DGLHeteroGraph.recv(v, reduce_func[, …])	接收和减少传入消息并更新节点的功能 vv。
DGLHeteroGraph.multi_recv（v，reducer_dict，...）	从多种边缘类型接收消息并执行聚合。
DGLHeteroGraph.send_and_recv(edges, …[, …])	沿着指定类型的边缘发送消息，并让目的地接收它们。
DGLHeteroGraph.multi_send_and_recv（…[，…]）	沿多种边缘类型发送和接收消息并执行聚合。
DGLHeteroGraph.pull（v，message_func，reduce_func）	从节点的前任提取消息，然后更新其功能。
DGLHeteroGraph.multi_pull（v，etype_dict，…）	沿多种边缘类型拉并接收给定节点的消息并执行聚合。
DGLHeteroGraph.push（u，message_func，reduce_func）	将消息从节点发送到其后继节点并进行更新。
DGLHeteroGraph.update_all（message_func，...）	通过所有边缘发送消息并更新所有节点。
DGLHeteroGraph.multi_update_all（etype_dict，...）	全方位发送和接收消息。
DGLHeteroGraph.prop_nodes（nodes_generator，...）	通过pull()在节点上顺序触发，使用图遍历传播消息。
DGLHeteroGraph.prop_edges（edges_generator，...）	通过沿边顺序触发send_and_recv()，使用图遍历传播消息。
DGLHeteroGraph.filter_nodes(predicate[, …])	返回满足给定谓词的给定节点类型的节点ID的张量。
DGLHeteroGraph.filter_edges(predicate[, …])	返回满足给定谓词的，具有给定边缘类型的边缘ID的张量。
DGLHeteroGraph.to(ctx)	将ndata和edata都移动到目标模式（cpu / gpu）与框架无关