.. DO NOT EDIT. .. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY. .. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE: .. "tutorials/blitz/2_dglgraph.py" .. LINE NUMBERS ARE GIVEN BELOW. .. only:: html .. note:: :class: sphx-glr-download-link-note :ref:`Go to the end ` to download the full example code. .. rst-class:: sphx-glr-example-title .. _sphx_glr_tutorials_blitz_2_dglgraph.py: How Does DGL Represent A Graph? =============================== By the end of this tutorial you will be able to: - Construct a graph in DGL from scratch. - Assign node and edge features to a graph. - Query properties of a DGL graph such as node degrees and connectivity. - Transform a DGL graph into another graph. - Load and save DGL graphs. (Time estimate: 16 minutes) .. GENERATED FROM PYTHON SOURCE LINES 20-32 DGL Graph Construction ---------------------- DGL represents a directed graph as a ``DGLGraph`` object. You can construct a graph by specifying the number of nodes in the graph as well as the list of source and destination nodes. Nodes in the graph have consecutive IDs starting from 0. For instance, the following code constructs a directed star graph with 5 leaves. The center node's ID is 0. The edges go from the center node to the leaves. .. GENERATED FROM PYTHON SOURCE LINES 32-51 .. code-block:: Python import os os.environ["DGLBACKEND"] = "pytorch" import dgl import numpy as np import torch g = dgl.graph(([0, 0, 0, 0, 0], [1, 2, 3, 4, 5]), num_nodes=6) # Equivalently, PyTorch LongTensors also work. g = dgl.graph( (torch.LongTensor([0, 0, 0, 0, 0]), torch.LongTensor([1, 2, 3, 4, 5])), num_nodes=6, ) # You can omit the number of nodes argument if you can tell the number of nodes from the edge list alone. g = dgl.graph(([0, 0, 0, 0, 0], [1, 2, 3, 4, 5])) .. GENERATED FROM PYTHON SOURCE LINES 52-56 Edges in the graph have consecutive IDs starting from 0, and are in the same order as the list of source and destination nodes during creation. .. GENERATED FROM PYTHON SOURCE LINES 56-61 .. code-block:: Python # Print the source and destination nodes of every edge. print(g.edges()) .. rst-class:: sphx-glr-script-out .. code-block:: none (tensor([0, 0, 0, 0, 0]), tensor([1, 2, 3, 4, 5])) .. GENERATED FROM PYTHON SOURCE LINES 62-72 .. note:: ``DGLGraph``'s are always directed to best fit the computation pattern of graph neural networks, where the messages sent from one node to the other are often different between both directions. If you want to handle undirected graphs, you may consider treating it as a bidirectional graph. See `Graph Transformations`_ for an example of making a bidirectional graph. .. GENERATED FROM PYTHON SOURCE LINES 75-88 Assigning Node and Edge Features to Graph ----------------------------------------- Many graph data contain attributes on nodes and edges. Although the types of node and edge attributes can be arbitrary in real world, ``DGLGraph`` only accepts attributes stored in tensors (with numerical contents). Consequently, an attribute of all the nodes or edges must have the same shape. In the context of deep learning, those attributes are often called *features*. You can assign and retrieve node and edge features via ``ndata`` and ``edata`` interface. .. GENERATED FROM PYTHON SOURCE LINES 88-99 .. code-block:: Python # Assign a 3-dimensional node feature vector for each node. g.ndata["x"] = torch.randn(6, 3) # Assign a 4-dimensional edge feature vector for each edge. g.edata["a"] = torch.randn(5, 4) # Assign a 5x4 node feature matrix for each node. Node and edge features in DGL can be multi-dimensional. g.ndata["y"] = torch.randn(6, 5, 4) print(g.edata["a"]) .. rst-class:: sphx-glr-script-out .. code-block:: none tensor([[-0.9894, -0.0224, -1.7663, 1.3087], [ 0.0341, 0.1191, 1.1839, -0.3885], [ 1.7283, -0.0608, 0.2489, 0.1390], [-0.3573, 1.8923, 1.0561, -1.3444], [-0.9847, -0.4223, -0.4814, -1.3532]]) .. GENERATED FROM PYTHON SOURCE LINES 100-116 .. note:: The vast development of deep learning has provided us many ways to encode various types of attributes into numerical features. Here are some general suggestions: - For categorical attributes (e.g. gender, occupation), consider converting them to integers or one-hot encoding. - For variable length string contents (e.g. news article, quote), consider applying a language model. - For images, consider applying a vision model such as CNNs. You can find plenty of materials on how to encode such attributes into a tensor in the `PyTorch Deep Learning Tutorials `__. .. GENERATED FROM PYTHON SOURCE LINES 119-124 Querying Graph Structures ------------------------- ``DGLGraph`` object provides various methods to query a graph structure. .. GENERATED FROM PYTHON SOURCE LINES 124-133 .. code-block:: Python print(g.num_nodes()) print(g.num_edges()) # Out degrees of the center node print(g.out_degrees(0)) # In degrees of the center node - note that the graph is directed so the in degree should be 0. print(g.in_degrees(0)) .. rst-class:: sphx-glr-script-out .. code-block:: none 6 5 5 0 .. GENERATED FROM PYTHON SOURCE LINES 134-137 Graph Transformations --------------------- .. GENERATED FROM PYTHON SOURCE LINES 140-143 DGL provides many APIs to transform a graph to another such as extracting a subgraph: .. GENERATED FROM PYTHON SOURCE LINES 143-150 .. code-block:: Python # Induce a subgraph from node 0, node 1 and node 3 from the original graph. sg1 = g.subgraph([0, 1, 3]) # Induce a subgraph from edge 0, edge 1 and edge 3 from the original graph. sg2 = g.edge_subgraph([0, 1, 3]) .. GENERATED FROM PYTHON SOURCE LINES 151-155 You can obtain the node/edge mapping from the subgraph to the original graph by looking into the node feature ``dgl.NID`` or edge feature ``dgl.EID`` in the new graph. .. GENERATED FROM PYTHON SOURCE LINES 155-166 .. code-block:: Python # The original IDs of each node in sg1 print(sg1.ndata[dgl.NID]) # The original IDs of each edge in sg1 print(sg1.edata[dgl.EID]) # The original IDs of each node in sg2 print(sg2.ndata[dgl.NID]) # The original IDs of each edge in sg2 print(sg2.edata[dgl.EID]) .. rst-class:: sphx-glr-script-out .. code-block:: none tensor([0, 1, 3]) tensor([0, 2]) tensor([0, 1, 2, 4]) tensor([0, 1, 3]) .. GENERATED FROM PYTHON SOURCE LINES 167-170 ``subgraph`` and ``edge_subgraph`` also copies the original features to the subgraph: .. GENERATED FROM PYTHON SOURCE LINES 170-181 .. code-block:: Python # The original node feature of each node in sg1 print(sg1.ndata["x"]) # The original edge feature of each node in sg1 print(sg1.edata["a"]) # The original node feature of each node in sg2 print(sg2.ndata["x"]) # The original edge feature of each node in sg2 print(sg2.edata["a"]) .. rst-class:: sphx-glr-script-out .. code-block:: none tensor([[ 0.0581, -0.0762, 0.6251], [ 0.9268, -2.8135, -1.7942], [-1.9347, -1.4650, 1.0004]]) tensor([[-0.9894, -0.0224, -1.7663, 1.3087], [ 1.7283, -0.0608, 0.2489, 0.1390]]) tensor([[ 0.0581, -0.0762, 0.6251], [ 0.9268, -2.8135, -1.7942], [ 0.4024, -0.7683, -0.7260], [ 0.0686, 0.1226, -0.8712]]) tensor([[-0.9894, -0.0224, -1.7663, 1.3087], [ 0.0341, 0.1191, 1.1839, -0.3885], [-0.3573, 1.8923, 1.0561, -1.3444]]) .. GENERATED FROM PYTHON SOURCE LINES 182-190 Another common transformation is to add a reverse edge for each edge in the original graph with ``dgl.add_reverse_edges``. .. note:: If you have an undirected graph, it is better to convert it into a bidirectional graph first via adding reverse edges. .. GENERATED FROM PYTHON SOURCE LINES 190-195 .. code-block:: Python newg = dgl.add_reverse_edges(g) print(newg.edges()) .. rst-class:: sphx-glr-script-out .. code-block:: none (tensor([0, 0, 0, 0, 0, 1, 2, 3, 4, 5]), tensor([1, 2, 3, 4, 5, 0, 0, 0, 0, 0])) .. GENERATED FROM PYTHON SOURCE LINES 196-202 Loading and Saving Graphs ------------------------- You can save a graph or a list of graphs via ``dgl.save_graphs`` and load them back with ``dgl.load_graphs``. .. GENERATED FROM PYTHON SOURCE LINES 202-216 .. code-block:: Python # Save graphs dgl.save_graphs("graph.dgl", g) dgl.save_graphs("graphs.dgl", [g, sg1, sg2]) # Load graphs (g,), _ = dgl.load_graphs("graph.dgl") print(g) (g, sg1, sg2), _ = dgl.load_graphs("graphs.dgl") print(g) print(sg1) print(sg2) .. rst-class:: sphx-glr-script-out .. code-block:: none Graph(num_nodes=6, num_edges=5, ndata_schemes={'y': Scheme(shape=(5, 4), dtype=torch.float32), 'x': Scheme(shape=(3,), dtype=torch.float32)} edata_schemes={'a': Scheme(shape=(4,), dtype=torch.float32)}) Graph(num_nodes=6, num_edges=5, ndata_schemes={'y': Scheme(shape=(5, 4), dtype=torch.float32), 'x': Scheme(shape=(3,), dtype=torch.float32)} edata_schemes={'a': Scheme(shape=(4,), dtype=torch.float32)}) Graph(num_nodes=3, num_edges=2, ndata_schemes={'_ID': Scheme(shape=(), dtype=torch.int64), 'y': Scheme(shape=(5, 4), dtype=torch.float32), 'x': Scheme(shape=(3,), dtype=torch.float32)} edata_schemes={'_ID': Scheme(shape=(), dtype=torch.int64), 'a': Scheme(shape=(4,), dtype=torch.float32)}) Graph(num_nodes=4, num_edges=3, ndata_schemes={'_ID': Scheme(shape=(), dtype=torch.int64), 'y': Scheme(shape=(5, 4), dtype=torch.float32), 'x': Scheme(shape=(3,), dtype=torch.float32)} edata_schemes={'_ID': Scheme(shape=(), dtype=torch.int64), 'a': Scheme(shape=(4,), dtype=torch.float32)}) .. GENERATED FROM PYTHON SOURCE LINES 217-233 What’s next? ------------ - See :ref:`here ` for a list of graph structure query APIs. - See :ref:`here ` for a list of subgraph extraction routines. - See :ref:`here ` for a list of graph transformation routines. - API reference of :func:`dgl.save_graphs` and :func:`dgl.load_graphs` .. GENERATED FROM PYTHON SOURCE LINES 233-237 .. code-block:: Python # Thumbnail credits: Wikipedia # sphinx_gallery_thumbnail_path = '_static/blitz_2_dglgraph.png' .. rst-class:: sphx-glr-timing **Total running time of the script:** (0 minutes 0.015 seconds) .. _sphx_glr_download_tutorials_blitz_2_dglgraph.py: .. only:: html .. container:: sphx-glr-footer sphx-glr-footer-example .. container:: sphx-glr-download sphx-glr-download-jupyter :download:`Download Jupyter notebook: 2_dglgraph.ipynb <2_dglgraph.ipynb>` .. container:: sphx-glr-download sphx-glr-download-python :download:`Download Python source code: 2_dglgraph.py <2_dglgraph.py>` .. container:: sphx-glr-download sphx-glr-download-zip :download:`Download zipped: 2_dglgraph.zip <2_dglgraph.zip>` .. only:: html .. rst-class:: sphx-glr-signature `Gallery generated by Sphinx-Gallery `_