dgl.readout_nodes(graph, feat, weight=None, *, op='sum', ntype=None)[source]

Generate a graph-level representation by aggregating node features feat.

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 node features of each graph.

Parameters
• graph (DGLGraph.) – Input graph.

• feat (str) – Node feature name.

• weight (str, optional) – Node weight name. None means aggregating without weights. Otherwise, multiply each node feature by node feature weight before aggregation. 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’.

• ntype (str, optional) – Node type. Can be omitted if there is only one node type in the graph.

Returns

Result tensor.

Return type

Tensor

Examples

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


Create two DGLGraph objects and initialize their node features.

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


Sum over one graph:

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


Sum over a batched graph:

>>> bg = dgl.batch([g1, g2])
tensor([3., 6.])  # [1 + 2, 1 + 2 + 3]


Weighted sum:

>>> bg.ndata['w'] = th.tensor([.1, .2, .1, .5, .2])

>>> dgl.readout_nodes(bg, 'h', op='max')