2_basics.py 6.72 KB
Newer Older
1
2
3
"""
.. currentmodule:: dgl

4
5
DGLGraph and Node/edge Features
===============================
6
7
8
9

**Author**: `Minjie Wang <https://jermainewang.github.io/>`_, Quan Gan, Yu Gai,
Zheng Zhang

10
In this tutorial, you learn how to create a graph and how to read and write node and edge representations.
11
12
13
"""

###############################################################################
14
# Creating a graph
15
# ----------------
16
17
18
# The design of :class:`DGLGraph` was influenced by other graph libraries. You 
# can create a graph from networkx and convert it into a :class:`DGLGraph` and 
# vice versa.
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

import networkx as nx
import dgl

g_nx = nx.petersen_graph()
g_dgl = dgl.DGLGraph(g_nx)

import matplotlib.pyplot as plt
plt.subplot(121)
nx.draw(g_nx, with_labels=True)
plt.subplot(122)
nx.draw(g_dgl.to_networkx(), with_labels=True)

plt.show()


###############################################################################
Minjie Wang's avatar
Minjie Wang committed
36
37
# There are many ways to construct a :class:`DGLGraph`. Below are the allowed
# data types ordered by our recommendataion.
38
#
Minjie Wang's avatar
Minjie Wang committed
39
40
41
42
43
44
45
46
47
48
49
# * A pair of arrays ``(u, v)`` storing the source and destination nodes respectively.
#   They can be numpy arrays or tensor objects from the backend framework.
# * ``scipy`` sparse matrix representing the adjacency matrix of the graph to be
#   constructed.
# * ``networkx`` graph object.
# * A list of edges in the form of integer pairs.
#
# The examples below construct the same star graph via different methods.
#
# :class:`DGLGraph` nodes are a consecutive range of integers between 0 and
# :func:`number_of_nodes() <DGLGraph.number_of_nodes>`. 
50
# :class:`DGLGraph` edges are in order of their additions. Note that
Minjie Wang's avatar
Minjie Wang committed
51
52
# edges are accessed in much the same way as nodes, with one extra feature:
# *edge broadcasting*.
53
54

import torch as th
Minjie Wang's avatar
Minjie Wang committed
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
import numpy as np
import scipy.sparse as spp

# Create a star graph from a pair of arrays (using ``numpy.array`` works too).
u = th.tensor([0, 0, 0, 0, 0])
v = th.tensor([1, 2, 3, 4, 5])
star1 = dgl.DGLGraph((u, v))

# Create the same graph from a scipy sparse matrix (using ``scipy.sparse.csr_matrix`` works too).
adj = spp.coo_matrix((np.ones(len(u)), (u.numpy(), v.numpy())))
star3 = dgl.DGLGraph(adj)

###############################################################################
# You can also create a graph by progressively adding more nodes and edges.
# Although it is not as efficient as the above constructors, it is suitable
# for applications where the graph cannot be constructed in one shot.
71
72
73

g = dgl.DGLGraph()
g.add_nodes(10)
74
# A couple edges one-by-one
75
76
for i in range(1, 4):
    g.add_edge(i, 0)
77
# A few more with a paired list
78
79
80
81
82
83
src = list(range(5, 8)); dst = [0]*3
g.add_edges(src, dst)
# finish with a pair of tensors
src = th.tensor([8, 9]); dst = th.tensor([0, 0])
g.add_edges(src, dst)

84
# Edge broadcasting will do star graph in one go!
85
86
g = dgl.DGLGraph()
g.add_nodes(10)
87
88
89
src = th.tensor(list(range(1, 10)));
g.add_edges(src, 0)

Minjie Wang's avatar
Minjie Wang committed
90
# Visualize the graph.
91
92
93
94
nx.draw(g.to_networkx(), with_labels=True)
plt.show()

###############################################################################
95
# Assigning a feature
96
# -------------------
97
# You can also assign features to nodes and edges of a :class:`DGLGraph`.  The
98
99
100
101
102
103
104
105
# features are represented as dictionary of names (strings) and tensors,
# called **fields**.
#
# The following code snippet assigns each node a vector (len=3).
#
# .. note::
#
#    DGL aims to be framework-agnostic, and currently it supports PyTorch and
106
#    MXNet tensors. The following examples use PyTorch only.
107
108
109
110
111
112
113
114

import dgl
import torch as th

x = th.randn(10, 3)
g.ndata['x'] = x

###############################################################################
Minjie Wang's avatar
Minjie Wang committed
115
116
117
# :func:`ndata <DGLGraph.ndata>` is a syntax sugar to access the feature
# data of all nodes. To get the features of some particular nodes, slice out
# the corresponding rows.
118

Minjie Wang's avatar
Minjie Wang committed
119
120
121
g.ndata['x'][0] = th.zeros(1, 3)
g.ndata['x'][[0, 1, 2]] = th.zeros(3, 3)
g.ndata['x'][th.tensor([0, 1, 2])] = th.randn((3, 3))
122
123

###############################################################################
124
125
# Assigning edge features is similar to that of node features,
# except that you can also do it by specifying endpoints of the edges.
126
127
128

g.edata['w'] = th.randn(9, 2)

129
# Access edge set with IDs in integer, list, or integer tensor
Minjie Wang's avatar
Minjie Wang committed
130
131
132
g.edata['w'][1] = th.randn(1, 2)
g.edata['w'][[0, 1, 2]] = th.zeros(3, 2)
g.edata['w'][th.tensor([0, 1, 2])] = th.zeros(3, 2)
133

Minjie Wang's avatar
Minjie Wang committed
134
135
136
137
138
# You can get the edge ids by giving endpoints, which are useful for accessing the features.
g.edata['w'][g.edge_id(1, 0)] = th.ones(1, 2)                   # edge 1 -> 0
g.edata['w'][g.edge_ids([1, 2, 3], [0, 0, 0])] = th.ones(3, 2)  # edges [1, 2, 3] -> 0
# Use edge broadcasting whenever applicable.
g.edata['w'][g.edge_ids([1, 2, 3], 0)] = th.ones(3, 2)          # edges [1, 2, 3] -> 0
139
140

###############################################################################
141
# After assignments, each node or edge field will be associated with a scheme
142
143
144
145
146
147
148
149
# containing the shape and data type (dtype) of its field value.

print(g.node_attr_schemes())
g.ndata['x'] = th.zeros((10, 4))
print(g.node_attr_schemes())


###############################################################################
150
# You can also remove node or edge states from the graph. This is particularly
151
152
153
154
155
156
157
# useful to save memory during inference.

g.ndata.pop('x')
g.edata.pop('w')


###############################################################################
158
# Working with multigraphs
159
# ~~~~~~~~~~~~~~~~~~~~~~~~
160
161
# Many graph applications need parallel edges,
# which class:DGLGraph supports by default.
162

163
g_multi = dgl.DGLGraph()
164
165
166
167
168
169
170
171
172
173
174
175
g_multi.add_nodes(10)
g_multi.ndata['x'] = th.randn(10, 2)

g_multi.add_edges(list(range(1, 10)), 0)
g_multi.add_edge(1, 0) # two edges on 1->0

g_multi.edata['w'] = th.randn(10, 2)
g_multi.edges[1].data['w'] = th.zeros(1, 2)
print(g_multi.edges())


###############################################################################
176
177
# An edge in multigraph cannot be uniquely identified by using its incident nodes
# :math:`u` and :math:`v`; query their edge IDs use ``edge_id`` interface.
178

179
_, _, eid_10 = g_multi.edge_id(1, 0, return_uv=True)
180
181
182
183
184
185
186
g_multi.edges[eid_10].data['w'] = th.ones(len(eid_10), 2)
print(g_multi.edata['w'])


###############################################################################
# .. note::
#
187
#    * Updating a feature of different schemes raises the risk of error on individual nodes (or
188
189
190
191
192
#      node subset).

###############################################################################
# Next steps
# ----------
193
# In the :doc:`next tutorial <3_pagerank>` you learn the
194
# DGL message passing interface by implementing PageRank.