dgl.reverse

dgl.reverse(g, copy_ndata=True, copy_edata=False, *, share_ndata=None, share_edata=None)[source]

Return a new graph with every edges being the reverse ones in the input graph.

The reverse (also called converse, transpose) of a graph with edges (i1,j1),(i2,j2),β‹― of type (U, E, V) is a new graph with edges (j1,i1),(j2,i2),β‹― of type (V, E, U).

The returned graph shares the data structure with the original graph, i.e. dgl.reverse will not create extra storage for the reversed graph.

Parameters:
  • g (DGLGraph) – The input graph.

  • copy_ndata (bool, optional) – If True, the node features of the reversed graph are copied from the original graph. If False, the reversed graph will not have any node features. (Default: True)

  • copy_edata (bool, optional) – If True, the edge features of the reversed graph are copied from the original graph. If False, the reversed graph will not have any edge features. (Default: False)

Returns:

The reversed graph.

Return type:

DGLGraph

Notes

If copy_ndata or copy_edata is True, the resulting graph will share the node or edge feature tensors with the input graph. Hence, users should try to avoid in-place operations which will be visible to both graphs.

This function discards the batch information. Please use dgl.DGLGraph.set_batch_num_nodes() and dgl.DGLGraph.set_batch_num_edges() on the transformed graph to maintain the information.

Examples

Homogeneous graphs

Create a graph to reverse.

>>> import dgl
>>> import torch as th
>>> g = dgl.graph((th.tensor([0, 1, 2]), th.tensor([1, 2, 0])))
>>> g.ndata['h'] = th.tensor([[0.], [1.], [2.]])
>>> g.edata['h'] = th.tensor([[3.], [4.], [5.]])

Reverse the graph.

>>> rg = dgl.reverse(g, copy_edata=True)
>>> rg.ndata['h']
tensor([[0.],
        [1.],
        [2.]])

The i-th edge in the reversed graph corresponds to the i-th edge in the original graph. When copy_edata is True, they have the same features.

>>> rg.edges()
(tensor([1, 2, 0]), tensor([0, 1, 2]))
>>> rg.edata['h']
tensor([[3.],
        [4.],
        [5.]])

Heterogenenous graphs

>>> g = dgl.heterograph({
...     ('user', 'follows', 'user'): (th.tensor([0, 2]), th.tensor([1, 2])),
...     ('user', 'plays', 'game'): (th.tensor([1, 2, 1]), th.tensor([2, 1, 1]))
... })
>>> g.nodes['game'].data['hv'] = th.ones(3, 1)
>>> g.edges['plays'].data['he'] = th.zeros(3, 1)

The resulting graph will have edge types ('user', 'follows', 'user) and ('game', 'plays', 'user').

>>> rg = dgl.reverse(g, copy_ndata=True)
>>> rg
Graph(num_nodes={'game': 3, 'user': 3},
      num_edges={('user', 'follows', 'user'): 2, ('game', 'plays', 'user'): 3},
      metagraph=[('user', 'user'), ('game', 'user')])
>>> rg.edges(etype='follows')
(tensor([1, 2]), tensor([0, 2]))
>>> rg.edges(etype='plays')
(tensor([2, 1, 1]), tensor([1, 2, 1]))
>>> rg.nodes['game'].data['hv']
tensor([[1.],
        [1.],
        [1.]])
>>> rg.edges['plays'].data
{}