Return the subgraph induced by k-hop out-neighborhood of the specified node(s). We can expand a set of nodes by including the successors of them. From a specified node set, a k-hop out subgraph is obtained by first repeating the node set expansion for k times and then creating a node in
(
graph, nodes, k, *, relabel_nodes=True, store_ids=True, output_device=None
)
| 801 | |
| 802 | |
| 803 | def khop_out_subgraph( |
| 804 | graph, nodes, k, *, relabel_nodes=True, store_ids=True, output_device=None |
| 805 | ): |
| 806 | """Return the subgraph induced by k-hop out-neighborhood of the specified node(s). |
| 807 | |
| 808 | We can expand a set of nodes by including the successors of them. From a |
| 809 | specified node set, a k-hop out subgraph is obtained by first repeating the node set |
| 810 | expansion for k times and then creating a node induced subgraph. In addition to |
| 811 | extracting the subgraph, DGL also copies the features of the extracted nodes and |
| 812 | edges to the resulting graph. The copy is *lazy* and incurs data movement only |
| 813 | when needed. |
| 814 | |
| 815 | If the graph is heterogeneous, DGL extracts a subgraph per relation and composes |
| 816 | them as the resulting graph. Thus the resulting graph has the same set of relations |
| 817 | as the input one. |
| 818 | |
| 819 | Parameters |
| 820 | ---------- |
| 821 | graph : DGLGraph |
| 822 | The input graph. |
| 823 | nodes : nodes or dict[str, nodes] |
| 824 | The starting node(s) to expand, which cannot have any duplicate value. The result |
| 825 | will be undefined otherwise. The allowed formats are: |
| 826 | |
| 827 | * Int: ID of a single node. |
| 828 | * Int Tensor: Each element is a node ID. The tensor must have the same device |
| 829 | type and ID data type as the graph's. |
| 830 | * iterable[int]: Each element is a node ID. |
| 831 | |
| 832 | If the graph is homogeneous, one can directly pass the above formats. |
| 833 | Otherwise, the argument must be a dictionary with keys being node types |
| 834 | and values being the node IDs in the above formats. |
| 835 | k : int |
| 836 | The number of hops. |
| 837 | relabel_nodes : bool, optional |
| 838 | If True, it will remove the isolated nodes and relabel the rest nodes in the |
| 839 | extracted subgraph. |
| 840 | store_ids : bool, optional |
| 841 | If True, it will store the raw IDs of the extracted edges in the ``edata`` of the |
| 842 | resulting graph under name ``dgl.EID``; if ``relabel_nodes`` is ``True``, it will |
| 843 | also store the raw IDs of the extracted nodes in the ``ndata`` of the resulting |
| 844 | graph under name ``dgl.NID``. |
| 845 | output_device : Framework-specific device context object, optional |
| 846 | The output device. Default is the same as the input graph. |
| 847 | |
| 848 | Returns |
| 849 | ------- |
| 850 | DGLGraph |
| 851 | The subgraph. |
| 852 | Tensor or dict[str, Tensor], optional |
| 853 | The new IDs of the input :attr:`nodes` after node relabeling. This is returned |
| 854 | only when :attr:`relabel_nodes` is True. It is in the same form as :attr:`nodes`. |
| 855 | |
| 856 | Notes |
| 857 | ----- |
| 858 | |
| 859 | When k is 1, the result subgraph is different from the one obtained by |
| 860 | :func:`dgl.out_subgraph`. The 1-hop out subgraph also includes the edges |
nothing calls this directly
no test coverage detected