Return a subgraph induced on the given nodes. A node-induced subgraph is a graph with edges whose endpoints are both in the specified node set. In addition to extracting the subgraph, DGL also copies the features of the extracted nodes and edges to the resulting graph. The copy is *
(
graph, nodes, *, relabel_nodes=True, store_ids=True, output_device=None
)
| 24 | |
| 25 | |
| 26 | def node_subgraph( |
| 27 | graph, nodes, *, relabel_nodes=True, store_ids=True, output_device=None |
| 28 | ): |
| 29 | """Return a subgraph induced on the given nodes. |
| 30 | |
| 31 | A node-induced subgraph is a graph with edges whose endpoints are both in the |
| 32 | specified node set. In addition to extracting the subgraph, DGL also copies |
| 33 | the features of the extracted nodes and edges to the resulting graph. The copy |
| 34 | is *lazy* and incurs data movement only when needed. |
| 35 | |
| 36 | If the graph is heterogeneous, DGL extracts a subgraph per relation and composes |
| 37 | them as the resulting graph. Thus, the resulting graph has the same set of relations |
| 38 | as the input one. |
| 39 | |
| 40 | Parameters |
| 41 | ---------- |
| 42 | graph : DGLGraph |
| 43 | The graph to extract subgraphs from. |
| 44 | nodes : nodes or dict[str, nodes] |
| 45 | The nodes to form the subgraph, which cannot have any duplicate value. The result |
| 46 | will be undefined otherwise. The allowed nodes formats are: |
| 47 | |
| 48 | * Int Tensor: Each element is a node ID. The tensor must have the same device type |
| 49 | and ID data type as the graph's. |
| 50 | * iterable[int]: Each element is a node ID. |
| 51 | * Bool Tensor: Each :math:`i^{th}` element is a bool flag indicating whether |
| 52 | node :math:`i` is in the subgraph. |
| 53 | |
| 54 | If the graph is homogeneous, one can directly pass the above formats. |
| 55 | Otherwise, the argument must be a dictionary with keys being node types |
| 56 | and values being the node IDs in the above formats. |
| 57 | relabel_nodes : bool, optional |
| 58 | If True, the extracted subgraph will only have the nodes in the specified node set |
| 59 | and it will relabel the nodes in order. |
| 60 | store_ids : bool, optional |
| 61 | If True, it will store the raw IDs of the extracted edges in the ``edata`` of the |
| 62 | resulting graph under name ``dgl.EID``; if ``relabel_nodes`` is ``True``, it will |
| 63 | also store the raw IDs of the specified nodes in the ``ndata`` of the resulting |
| 64 | graph under name ``dgl.NID``. |
| 65 | output_device : Framework-specific device context object, optional |
| 66 | The output device. Default is the same as the input graph. |
| 67 | |
| 68 | Returns |
| 69 | ------- |
| 70 | G : DGLGraph |
| 71 | The subgraph. |
| 72 | |
| 73 | Notes |
| 74 | ----- |
| 75 | |
| 76 | This function discards the batch information. Please use |
| 77 | :func:`dgl.DGLGraph.set_batch_num_nodes` |
| 78 | and :func:`dgl.DGLGraph.set_batch_num_edges` on the transformed graph |
| 79 | to maintain the information. |
| 80 | |
| 81 | Examples |
| 82 | -------- |
| 83 | The following example uses PyTorch backend. |
no test coverage detected