dgl.bipartite_from_scipy

dgl.bipartite_from_scipy(sp_mat, utype, etype, vtype, eweight_name=None, idtype=None, device=None)[source]

Create a uni-directional bipartite graph from a SciPy sparse matrix and return.

The created graph will have two types of nodes utype and vtype as well as one edge type etype whose edges are from utype to vtype.

Parameters:
  • sp_mat (scipy.sparse.spmatrix) – The graph adjacency matrix. Each nonzero entry sp_mat[i, j] represents an edge from node i of type utype to j of type vtype. Let the matrix shape be (N, M). There will be N nodes of type utype and M nodes of type vtype in the resulting graph.

  • utype (str, optional) – The name of the source node type.

  • etype (str, optional) – The name of the edge type.

  • vtype (str, optional) – The name of the destination node type.

  • eweight_name (str, optional) – The edata name for storing the nonzero values of sp_mat. If given, DGL will store the nonzero values of sp_mat in edata[eweight_name] of the returned graph.

  • idtype (int32 or int64, optional) – The data type for storing the structure-related graph information such as node and edge IDs. It should be a framework-specific data type object (e.g., torch.int32). By default, DGL uses int64.

  • device (device context, optional) – The device of the resulting graph. It should be a framework-specific device object (e.g., torch.device). By default, DGL stores the graph on CPU.

Returns:

The created graph.

Return type:

DGLGraph

Notes

  1. The function supports all kinds of SciPy sparse matrix classes (e.g., scipy.sparse.csr.csr_matrix). It converts the input matrix to the COOrdinate format using scipy.sparse.spmatrix.tocoo() before creates a DGLGraph. Creating from a scipy.sparse.coo.coo_matrix is hence the most efficient way.

  2. DGL internally maintains multiple copies of the graph structure in different sparse formats and chooses the most efficient one depending on the computation invoked. If memory usage becomes an issue in the case of large graphs, use dgl.DGLGraph.formats() to restrict the allowed formats.

Examples

The following example uses PyTorch backend.

>>> import dgl
>>> import numpy as np
>>> import torch
>>> from scipy.sparse import coo_matrix

Create a small three-edge graph.

>>> # Source nodes for edges (2, 1), (3, 2), (4, 3)
>>> src_ids = np.array([2, 3, 4])
>>> # Destination nodes for edges (2, 1), (3, 2), (4, 3)
>>> dst_ids = np.array([1, 2, 3])
>>> # Weight for edges (2, 1), (3, 2), (4, 3)
>>> eweight = np.array([0.2, 0.3, 0.5])
>>> sp_mat = coo_matrix((eweight, (src_ids, dst_ids)))
>>> g = dgl.bipartite_from_scipy(sp_mat, utype='_U', etype='_E', vtype='_V')

Retrieve the edge weights.

>>> g = dgl.bipartite_from_scipy(sp_mat, utype='_U', etype='_E', vtype='_V', eweight_name='w')
>>> g.edata['w']
tensor([0.2000, 0.3000, 0.5000], dtype=torch.float64)

Create a graph on the first GPU with data type int32.

>>> g = dgl.bipartite_from_scipy(sp_mat, utype='_U', etype='_E', vtype='_V',
...                              idtype=torch.int32, device='cuda:0')