dgl.readout_edges

dgl.readout_edges(graph, feat, weight=None, *, op='sum', etype=None)[source]

Sum the edge feature feat in graph, optionally multiplies it by a edge weight.

The function is commonly used as a readout function on a batch of graphs to generate graph-level representation. Thus, the result tensor shape depends on the batch size of the input graph. Given a graph of batch size \(B\), and a feature size of \(D\), the result shape will be \((B, D)\), with each row being the aggregated edge features of each graph.

Parameters:

graph (DGLGraph.) – The input graph.
feat (str) – The edge feature name.
weight (str, optional) – The edge weight feature name. If None, no weighting will be performed, otherwise, weight each edge feature with field feat. for summation. The weight feature shape must be compatible with an element-wise multiplication with the feature tensor.
op (str, optional) – Readout operator. Can be ‘sum’, ‘max’, ‘min’, ‘mean’.
etype (str or (str, str, str), optional) –
The type names of the edges. The allowed type name formats are:
- (str, str, str) for source node type, edge type and destination node type.
- or one str edge type name if the name can uniquely identify a triplet format in the graph.
Can be omitted if the graph has only one type of edges.

Returns:

Result tensor.

Return type:

Tensor

Examples

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

Create two DGLGraph objects and initialize their edge features.

>>> g1 = dgl.graph(([0, 1], [1, 0]))              # Graph 1
>>> g1.edata['h'] = th.tensor([1., 2.])
>>> g2 = dgl.graph(([0, 1], [1, 2]))              # Graph 2
>>> g2.edata['h'] = th.tensor([2., 3.])

Sum over one graph:

>>> dgl.readout_edges(g1, 'h')
tensor([3.])  # 1 + 2

Sum over a batched graph:

>>> bg = dgl.batch([g1, g2])
>>> dgl.readout_edges(bg, 'h')
tensor([3., 5.])  # [1 + 2, 2 + 3]

Weighted sum:

>>> bg.edata['w'] = th.tensor([.1, .2, .1, .5])
>>> dgl.readout_edges(bg, 'h', 'w')
tensor([.5, 1.7])

Readout by max:

>>> dgl.readout_edges(bg, 'w', op='max')
tensor([2., 3.])