dgl.bipartite

dgl.bipartite(data, utype='_U', etype='_E', vtype='_V', num_nodes=None, card=None, validate=True, restrict_format='auto', index_dtype='int64', **kwargs)[source]

Create a bipartite graph.

The result graph is directed and edges must be from utype nodes to vtype nodes. Nodes of each type have their own ID counts.

In the sparse matrix perspective, dgl.graph() creates a graph whose adjacency matrix must be square while dgl.bipartite() creates a graph that does not necessarily have square adjacency matrix.

Parameters:
  • data (graph data) –

    Data to initialize graph structure. Supported data formats are

    1. list of edge pairs (e.g. [(0, 2), (3, 1), …])
    2. pair of vertex IDs representing end nodes (e.g. ([0, 3, …], [2, 1, …]))
    3. scipy sparse matrix
    4. networkx graph
  • utype (str, optional) – Source node type name. (Default: _U)
  • etype (str, optional) – Edge type name. (Default: _E)
  • vtype (str, optional) – Destination node type name. (Default: _V)
  • num_nodes (2-tuple of int, optional) – Number of nodes in the source and destination group. If None, infer from input data, i.e. the largest node ID plus 1 for each type. (Default: None)
  • card (2-tuple of int, optional) – Deprecated (see num_nodes). Cardinality (number of nodes in the source and destination group). If None, infer from input data, i.e. the largest node ID plus 1 for each type. (Default: None)
  • validate (bool, optional) – If True, check if node ids are within cardinality, the check process may take some time. (Default: True) If False and card is not None, user would receive a warning.
  • restrict_format ('any', 'coo', 'csr', 'csc', 'auto', optional) – Force the storage format. Default: ‘auto’ (i.e. let DGL decide what to use).
  • index_dtype ('int32', 'int64', optional) – Force the index data type. Default: ‘int64’.
  • kwargs (key-word arguments, optional) –

    Other key word arguments. Only comes into effect when we are using a NetworkX graph. It can consist of:

    • edge_id_attr_name
      Str, key name for edge ids in the NetworkX graph. If not found, we will consider the graph not to have pre-specified edge ids.
Returns:

Return type:

DGLHeteroGraph

Examples

Create from pairs of edges

>>> g = dgl.bipartite([(0, 2), (0, 3), (1, 2)], 'user', 'plays', 'game')
>>> g.ntypes
['user', 'game']
>>> g.etypes
['plays']
>>> g.canonical_etypes
[('user', 'plays', 'game')]
>>> g.number_of_nodes('user')
2
>>> g.number_of_nodes('game')
4
>>> g.number_of_edges('plays')  # 'plays' could be omitted here
3

Create from source and destination vertex ID lists

>>> u = [0, 0, 1]
>>> v = [2, 3, 2]
>>> g = dgl.bipartite((u, v))

The IDs can also be stored in framework-specific tensors

>>> import torch
>>> u = torch.tensor([0, 0, 1])
>>> v = torch.tensor([2, 3, 2])
>>> g = dgl.bipartite((u, v))

Create from scipy sparse matrix. Since scipy sparse matrix has explicit shape, the cardinality of the result graph is derived from that.

>>> from scipy.sparse import coo_matrix
>>> spmat = coo_matrix(([1,1,1], ([0, 0, 1], [2, 3, 2])), shape=(4, 4))
>>> g = dgl.bipartite(spmat, 'user', 'plays', 'game')
>>> g.number_of_nodes('user')
4
>>> g.number_of_nodes('game')
4

Create from networkx graph. The given graph must follow the bipartite graph convention in networkx. Each node has a bipartite attribute with values 0 or 1. The result graph has two types of nodes and only edges from bipartite=0 to bipartite=1 will be included.

>>> import networkx as nx
>>> nxg = nx.complete_bipartite_graph(3, 4)
>>> g = dgl.bipartite(nxg, 'user', 'plays', 'game')
>>> g.number_of_nodes('user')
3
>>> g.number_of_nodes('game')
4
>>> g.edges()
(tensor([0, 0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2]), tensor([0, 1, 2, 3, 0, 1, 2, 3, 0, 1, 2, 3]))

Check if node ids are within num_nodes specified

>>> g = dgl.bipartite(([0, 1, 2], [1, 2, 3]), num_nodes=(2, 4), validate=True)
...
dgl._ffi.base.DGLError: Invalid node id 2 (should be less than cardinality 2).
>>> g = dgl.bipartite(([0, 1, 2], [1, 2, 3]), num_nodes=(3, 4), validate=True)
>>> g
Graph(num_nodes={'_U': 3, '_V': 4},
      num_edges={('_U', '_E', '_V'): 3},
      metagraph=[('_U', '_V')])