dgl.DGLGraph.pullο
- DGLGraph.pull(v, message_func, reduce_func, apply_node_func=None, etype=None)[source]ο
Pull messages from the specified node(s)β predecessors along the specified edge type, aggregate them to update the node features.
- Parameters:
v (node IDs) β
The node IDs. The allowed formats are:
int
: A single node.Int Tensor: Each element is a node ID. The tensor must have the same device type and ID data type as the graphβs.
iterable[int]: Each element is a node ID.
message_func (dgl.function.BuiltinFunction or callable) β The message function to generate messages along the edges. It must be either a DGL Built-in Function or a User-defined Functions.
reduce_func (dgl.function.BuiltinFunction or callable) β The reduce function to aggregate the messages. It must be either a DGL Built-in Function or a User-defined Functions.
apply_node_func (callable, optional) β An optional apply function to further update the node features after the message reduction. It must be a User-defined Functions.
etype (str or (str, str, str), optional) β
The type name 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.
Notes
If some of the given nodes
v
has no in-edges, DGL does not invoke message and reduce functions for these nodes and fill their aggregated messages with zero. Users can control the filled values viaset_n_initializer()
. DGL still invokesapply_node_func
if provided.DGL recommends using DGLβs bulit-in function for the
message_func
and thereduce_func
arguments, because DGL will invoke efficient kernels that avoids copying node features to edge features in this case.
Examples
>>> import dgl >>> import dgl.function as fn >>> import torch
Homogeneous graph
>>> g = dgl.graph(([0, 1, 2, 3], [1, 2, 3, 4])) >>> g.ndata['x'] = torch.ones(5, 2) >>> g.pull([0, 3, 4], fn.copy_u('x', 'm'), fn.sum('m', 'h')) >>> g.ndata['h'] tensor([[0., 0.], [0., 0.], [0., 0.], [1., 1.], [1., 1.]])
Heterogeneous graph
>>> g = dgl.heterograph({ ... ('user', 'follows', 'user'): ([0, 1], [1, 2]), ... ('user', 'plays', 'game'): ([0, 2], [0, 1]) ... }) >>> g.nodes['user'].data['h'] = torch.tensor([[0.], [1.], [2.]])
Pull.
>>> g['follows'].pull(2, fn.copy_u('h', 'm'), fn.sum('m', 'h'), etype='follows') >>> g.nodes['user'].data['h'] tensor([[0.], [1.], [1.]])