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

参考：https://docs.dgl.ai/en/latest/api/python/batch_heterograph.html#

dgl.batched_heterograph 

class dgl.BatchedDGLHeteroGraph(graph_list, node_attrs, edge_attrs)

用于批处理DGLHeteroGraphs的类。

BatcheDGLHeteroGrapha基本上将一个小图的列表合并成一个巨大的图，这样就可以同时对一批图执行消息传递和读取

对于给定的节点/边缘类型，节点/边缘将使用批处理图中的新id重新索引，其规则如下：

项目	图1	图2	…	图k
原始编号	0，…，N1	0，...，N2	…	…，Nk
新编号	0，…，N1	N1 + 1，…，N1 + N2 + 1	…	…，N1 +…+ Nk + k-1

对BatchedGLHeteroGraphs中的特征进行修改对原始图没有影响。参见下面有关如何工作的示例。

参数：	graph_list（iterable）– DGLHeteroGraph要批处理的集合。 node_attrs (None or dict) –要批处理的节点属性。如果为None，则结果图将不具有特征属性。如果为dict，则将str映射为str或可迭代。键代表节点类型的名称，值代表要为相应类型批处理的节点特征。默认情况下，我们对所有类型的节点的所有特征都处理。 edge_attrs(None or dict) –与node_attrs的情况相同。

例子

>>> import dgl
>>> import torch as th

例子1

我们从一个简单的例子开始。

>>> # 为“user”类型的节点创建第一个图和设置特征属性
>>> g1 = dgl.heterograph({('user', 'plays', 'game'): [(0, 0), (1, 0)]})
>>> g1.nodes['user'].data['h1'] = th.tensor([[0.], [1.]])
>>> # 为“user”类型的节点创建第二个图并设置特征属性
>>> g2 = dgl.heterograph({('user', 'plays', 'game'): [(0, 0)]})
>>> g2.nodes['user'].data['h1'] = th.tensor([[0.]])
>>> # 批处理图
>>> bg = dgl.batch_hetero([g1, g2])

通过批处理操作，可以重新索引节点和边。

>>> bg.nodes('user')
tensor([0, 1, 2])

默认情况下，我们还将复制并连接所有节点和边特征。

>>> bg.nodes['user'].data['h1']
tensor([[0.],
        [1.],
        [0.]])

 

例子2

现在，我们将看到一个更复杂的示例，一个批处理图可以进行各种操作。

>>> g1 = dgl.heterograph({
...    ('user', 'follows', 'user'): [(0, 1), (1, 2)],
...    ('user', 'plays', 'game'): [(0, 0), (1, 0)]
... })
>>> g1.nodes['user'].data['h1'] = th.tensor([[0.], [1.], [2.]])
>>> g1.nodes['user'].data['h2'] = th.tensor([[3.], [4.], [5.]])
>>> g1.nodes['game'].data['h1'] = th.tensor([[0.]])
>>> g1.edges['plays'].data['h1'] = th.tensor([[0.], [1.]])

 

>>> g2 = dgl.heterograph({
...    ('user', 'follows', 'user'): [(0, 1), (1, 2)],
...    ('user', 'plays', 'game'): [(0, 0), (1, 0)]
... })
>>> g2.nodes['user'].data['h1'] = th.tensor([[0.], [1.], [2.]])
>>> g2.nodes['user'].data['h2'] = th.tensor([[3.], [4.], [5.]])
>>> g2.nodes['game'].data['h1'] = th.tensor([[0.]])
>>> g2.edges['plays'].data['h1'] = th.tensor([[0.], [1.]])

 

将两个DGLHeteroGraph对象合并为一个BatchedDGLHeteroGraph对象。合并图形列表时，我们可以选择仅包括属性的子集。

>>> # 对于边类型，只允许典型的边缘类型避免歧义。
>>> bg = dgl.batch_hetero([g1, g2], node_attrs={'user': ['h1', 'h2'], 'game': None},
...                       edge_attrs={('user', 'plays', 'game'): 'h1'})
>>> list(bg.nodes['user'].data.keys())
['h1', 'h2']
>>> list(bg.nodes['game'].data.keys())
[]
>>> list(bg.edges['follows'].data.keys())
[]
>>> list(bg.edges['plays'].data.keys())
['h1']

我们可以简要了解构成批处理图的图。

>>> bg.batch_size
2
>>> bg.batch_num_nodes('user')
[3, 3]
>>> bg.batch_num_edges(('user', 'plays', 'game'))
[2, 2]

更新批处理图的属性对原始图没有影响。

>>> bg.nodes['game'].data['h1'] = th.tensor([[1.], [1.]])
>>> g2.nodes['game'].data['h1']
tensor([[0.]])

相反，我们可以将批处理的图分解回图列表，然后使用它们来替换原始图。

>>> g3, g4 = dgl.unbatch_hetero(bg) # returns a list of DGLHeteroGraph objects
>>> g4.nodes['game'].data['h1']
tensor([[1.]])

 

 

dgl.batch_hetero 

dgl.batch_hetero(graph_list,node_attrs ='__ ALL__',edge_attrs ='__ ALL__')

批处理的集合，DGLHeteroGraph并返回 BatchedDGLHeteroGraph独立于的对象graph_list。

参数：	graph_list（iterable）– DGLHeteroGraph要批处理的集合。 node_attrs(None or dict)–要批处理的节点属性。如果为None，则结果图将不具有特征属性。如果为dict，则将str映射为str或可迭代。键代表节点类型的名称，值代表要为相应类型批处理的节点特征。默认情况下，我们对所有类型的节点的所有特征都处理。 edge_attrs (None or dict)–与的情况相同node_attrs。
返回值：	一个batched heterograph对象
返回类型：	BatchedDGLHeteroGraph

 

 

dgl.unbatch_hetero 

dgl.unbatch_hetero(graph)

返回此批处理中的异构图列表。

参数：	graph（BatchedDGLHeteroGraph）–批处理异位图。
返回值：	BatcheDGLHeteroGraph对象的列表，其属性是通过划分该图的属性来获得的。列表的长度与图的批处理大小相同。
返回类型：	list

笔记

取消批处理会将批处理图的每个字段张量分成较小的分区。

对于诸如节点/边缘状态聚合之类的简单任务，请尝试沿边缘类型对图形进行切片并使用读出功能。

 

 

dgl.BatchedDGLHeteroGraph.batch_size 

BatchedDGLHeteroGraph.batch_size

此批次中的图形数。

返回值：	此批次中的图形数。
返回类型：	整型

 

dgl.BatchedDGLHeteroGraph.batch_num_nodes 

BatchedDGLHeteroGraph.batch_num_nodes(ntype = None)

返回批处理中所有异构图的给定类型的节点数。

参数：	ntype（str，可选）–节点类型。如果图中只有一种节点类型，则可以省略。（默认：无）
返回值：	返回值中第i个元素给出了第i个异构图中指定类型的节点数。
返回类型：	整数列表

例子

>>> g1 = dgl.heterograph({
...      ('user', 'follows', 'user'): [(0, 1), (1, 2)],
...      ('user', 'plays', 'game'): [(0, 0), (1, 0), (2, 1), (3, 1)]
...      })
>>> g2 = dgl.heterograph({
...      ('user', 'follows', 'user'): [(0, 1), (1, 2)],
...      ('user', 'plays', 'game'): [(0, 0), (1, 0), (2, 1)]
...      })
>>> bg = dgl.batch_hetero([g1, g2])
>>> bg.batch_num_nodes('user')
[4, 3]
>>> bg.batch_num_nodes('game')
[2, 2]

 

dgl.BatchedDGLHeteroGraph.batch_num_edges 

BatchedDGLHeteroGraph.batch_num_edges(etype = None)

返回批处理中所有异构图的给定类型的边数。

参数：	etype（str的str或tuple ，可选）–边类型。如果图形中只有一种边缘类型，则可以省略。
返回值：	返回值中第i个元素给出了第i个异构图中指定类型的边数。
返回类型：	整数列表

例子

>>> g1 = dgl.heterograph({
...      ('user', 'follows', 'user'): [(0, 1), (1, 2)],
...      ('user', 'follows', 'developer'): [(0, 1), (1, 2)],
...      ('user', 'plays', 'game'): [(0, 0), (1, 0), (2, 1), (3, 1)]
...      })
>>> g2 = dgl.heterograph({
...      ('user', 'follows', 'user'): [(0, 1), (1, 2)],
...      ('user', 'follows', 'developer'): [(0, 1), (1, 2)],
...      ('user', 'plays', 'game'): [(0, 0), (1, 0), (2, 1)]
...      })
>>> bg = dgl.batch_hetero([g1, g2])
>>> bg.batch_num_edges('plays')
[4, 3]
>>> # 'follows' is ambiguous and we use ('user', 'follows', 'user') instead.
>>> bg.batch_num_edges(('user', 'follows', 'user'))
[2, 2]