class_docstr: DGL collator to combine edges and their computation dependencies within a minibatch for
  training edge classification, edge regression, or link prediction on a single graph
  with neighborhood sampling.
  
  Given a set of edges, the collate function will yield
  
  * A tensor of input nodes necessary for computing the representation on edges, or
    a dictionary of node type names and such tensors.
  
  * A subgraph that contains only the edges in the minibatch and their incident nodes.
    Note that the graph has an identical metagraph with the original graph.
  
  * If a negative sampler is given, another graph that contains the "negative edges",
    connecting the source and destination nodes yielded from the given negative sampler.
  
  * A list of MFGs necessary for computing the representation of the incident nodes
    of the edges in the minibatch.
  
  Parameters
  ----------
  g : DGLGraph
      The graph from which the edges are iterated in minibatches and the subgraphs
      are generated.
  eids : Tensor or dict[etype, Tensor]
      The edge set in graph :attr:`g` to compute outputs.
  graph_sampler : dgl.dataloading.BlockSampler
      The neighborhood sampler.
  g_sampling : DGLGraph, optional
      The graph where neighborhood sampling and message passing is performed.
  
      Note that this is not necessarily the same as :attr:`g`.
  
      If None, assume to be the same as :attr:`g`.
  exclude : str, optional
      Whether and how to exclude dependencies related to the sampled edges in the
      minibatch.  Possible values are
  
      * None, which excludes nothing.
  
      * ``'self'``, which excludes the sampled edges themselves but nothing else.
  
      * ``'reverse_id'``, which excludes the reverse edges of the sampled edges.  The said
        reverse edges have the same edge type as the sampled edges.  Only works
        on edge types whose source node type is the same as its destination node type.
  
      * ``'reverse_types'``, which excludes the reverse edges of the sampled edges.  The
        said reverse edges have different edge types from the sampled edges.
  
      If ``g_sampling`` is given, ``exclude`` is ignored and will be always ``None``.
  reverse_eids : Tensor or dict[etype, Tensor], optional
      A tensor of reverse edge ID mapping.  The i-th element indicates the ID of
      the i-th edge's reverse edge.
  
      If the graph is heterogeneous, this argument requires a dictionary of edge
      types and the reverse edge ID mapping tensors.
  
      Required and only used when ``exclude`` is set to ``reverse_id``.
  
      For heterogeneous graph this will be a dict of edge type and edge IDs.  Note that
      only the edge types whose source node type is the same as destination node type
      are needed.
  reverse_etypes : dict[etype, etype], optional
      The mapping from the edge type to its reverse edge type.
  
      Required and only used when ``exclude`` is set to ``reverse_types``.
  negative_sampler : callable, optional
      The negative sampler.  Can be omitted if no negative sampling is needed.
  
      The negative sampler must be a callable that takes in the following arguments:
  
      * The original (heterogeneous) graph.
  
      * The ID array of sampled edges in the minibatch, or the dictionary of edge
        types and ID array of sampled edges in the minibatch if the graph is
        heterogeneous.
  
      It should return
  
      * A pair of source and destination node ID arrays as negative samples,
        or a dictionary of edge types and such pairs if the graph is heterogenenous.
  
      A set of builtin negative samplers are provided in
      :ref:`the negative sampling module <api-dataloading-negative-sampling>`.
  
  Examples
  --------
  The following example shows how to train a 3-layer GNN for edge classification on a
  set of edges ``train_eid`` on a homogeneous undirected graph. Each node takes
  messages from all neighbors.
  
  Say that you have an array of source node IDs ``src`` and another array of destination
  node IDs ``dst``.  One can make it bidirectional by adding another set of edges
  that connects from ``dst`` to ``src``:
  
  >>> g = dgl.graph((torch.cat([src, dst]), torch.cat([dst, src])))
  
  One can then know that the ID difference of an edge and its reverse edge is ``|E|``,
  where ``|E|`` is the length of your source/destination array.  The reverse edge
  mapping can be obtained by
  
  >>> E = len(src)
  >>> reverse_eids = torch.cat([torch.arange(E, 2 * E), torch.arange(0, E)])
  
  Note that the sampled edges as well as their reverse edges are removed from
  computation dependencies of the incident nodes.  This is a common trick to avoid
  information leakage.
  
  >>> sampler = dgl.dataloading.MultiLayerNeighborSampler([15, 10, 5])
  >>> collator = dgl.dataloading.EdgeCollator(
  ...     g, train_eid, sampler, exclude='reverse_id',
  ...     reverse_eids=reverse_eids)
  >>> dataloader = torch.utils.data.DataLoader(
  ...     collator.dataset, collate_fn=collator.collate,
  ...     batch_size=1024, shuffle=True, drop_last=False, num_workers=4)
  >>> for input_nodes, pair_graph, blocks in dataloader:
  ...     train_on(input_nodes, pair_graph, blocks)
  
  To train a 3-layer GNN for link prediction on a set of edges ``train_eid`` on a
  homogeneous graph where each node takes messages from all neighbors (assume the
  backend is PyTorch), with 5 uniformly chosen negative samples per edge:
  
  >>> sampler = dgl.dataloading.MultiLayerNeighborSampler([15, 10, 5])
  >>> neg_sampler = dgl.dataloading.negative_sampler.Uniform(5)
  >>> collator = dgl.dataloading.EdgeCollator(
  ...     g, train_eid, sampler, exclude='reverse_id',
  ...     reverse_eids=reverse_eids, negative_sampler=neg_sampler)
  >>> dataloader = torch.utils.data.DataLoader(
  ...     collator.dataset, collate_fn=collator.collate,
  ...     batch_size=1024, shuffle=True, drop_last=False, num_workers=4)
  >>> for input_nodes, pos_pair_graph, neg_pair_graph, blocks in dataloader:
  ...     train_on(input_nodse, pair_graph, neg_pair_graph, blocks)
  
  For heterogeneous graphs, the reverse of an edge may have a different edge type
  from the original edge.  For instance, consider that you have an array of
  user-item clicks, representated by a user array ``user`` and an item array ``item``.
  You may want to build a heterogeneous graph with a user-click-item relation and an
  item-clicked-by-user relation.
  
  >>> g = dgl.heterograph({
  ...     ('user', 'click', 'item'): (user, item),
  ...     ('item', 'clicked-by', 'user'): (item, user)})
  
  To train a 3-layer GNN for edge classification on a set of edges ``train_eid`` with
  type ``click``, you can write
  
  >>> sampler = dgl.dataloading.MultiLayerNeighborSampler([15, 10, 5])
  >>> collator = dgl.dataloading.EdgeCollator(
  ...     g, {'click': train_eid}, sampler, exclude='reverse_types',
  ...     reverse_etypes={'click': 'clicked-by', 'clicked-by': 'click'})
  >>> dataloader = torch.utils.data.DataLoader(
  ...     collator.dataset, collate_fn=collator.collate,
  ...     batch_size=1024, shuffle=True, drop_last=False, num_workers=4)
  >>> for input_nodes, pair_graph, blocks in dataloader:
  ...     train_on(input_nodes, pair_graph, blocks)
  
  To train a 3-layer GNN for link prediction on a set of edges ``train_eid`` with type
  ``click``, you can write
  
  >>> sampler = dgl.dataloading.MultiLayerNeighborSampler([15, 10, 5])
  >>> neg_sampler = dgl.dataloading.negative_sampler.Uniform(5)
  >>> collator = dgl.dataloading.EdgeCollator(
  ...     g, train_eid, sampler, exclude='reverse_types',
  ...     reverse_etypes={'click': 'clicked-by', 'clicked-by': 'click'},
  ...     negative_sampler=neg_sampler)
  >>> dataloader = torch.utils.data.DataLoader(
  ...     collator.dataset, collate_fn=collator.collate,
  ...     batch_size=1024, shuffle=True, drop_last=False, num_workers=4)
  >>> for input_nodes, pos_pair_graph, neg_pair_graph, blocks in dataloader:
  ...     train_on(input_nodes, pair_graph, neg_pair_graph, blocks)
  
  Notes
  -----
  For the concept of MFGs, please refer to
  :ref:`User Guide Section 6 <guide-minibatch>` and
  :doc:`Minibatch Training Tutorials <tutorials/large/L0_neighbor_sampling_overview>`.
class_docstr_tok: ["DGL","collator","to","combine","edges","and","their","computation","dependencies","within","a","minibatch","for","training","edge","classification",",","edge","regression",",","or","link","prediction","on","a","single","graph","with","neighborhood","sampling",".","Given","a","set","of","edges",",","the","collate","function","will","yield","*","A","tensor","of","input","nodes","necessary","for","computing","the","representation","on","edges",",","or","a","dictionary","of","node","type","names","and","such","tensors",".","*","A","subgraph","that","contains","only","the","edges","in","the","minibatch","and","their","incident","nodes",".","Note","that","the","graph","has","an","identical","metagraph","with","the","original","graph",".","*","If","a","negative","sampler","is","given",",","another","graph","that","contains","the","``","negative","edges","''",",","connecting","the","source","and","destination","nodes","yielded","from","the","given","negative","sampler",".","*","A","list","of","MFGs","necessary","for","computing","the","representation","of","the","incident","nodes","of","the","edges","in","the","minibatch",".","Parameters","--","--","--","--","--","g",":","DGLGraph","The","graph","from","which","the","edges","are","iterated","in","minibatches","and","the","subgraphs","are","generated",".","eids",":","Tensor","or","dict","[","etype",",","Tensor","]","The","edge","set","in","graph",":","attr",":","`","g","`","to","compute","outputs",".","graph_sampler",":","dgl.dataloading.BlockSampler","The","neighborhood","sampler",".","g_sampling",":","DGLGraph",",","optional","The","graph","where","neighborhood","sampling","and","message","passing","is","performed",".","Note","that","this","is","not","necessarily","the","same","as",":","attr",":","`","g","`",".","If","None",",","assume","to","be","the","same","as",":","attr",":","`","g","`",".","exclude",":","str",",","optional","Whether","and","how","to","exclude","dependencies","related","to","the","sampled","edges","in","the","minibatch",".","Possible","values","are","*","None",",","which","excludes","nothing",".","*","``","'self","'","``",",","which","excludes","the","sampled","edges","themselves","but","nothing","else",".","*","``","'reverse_id","'","``",",","which","excludes","the","reverse","edges","of","the","sampled","edges",".","The","said","reverse","edges","have","the","same","edge","type","as","the","sampled","edges",".","Only","works","on","edge","types","whose","source","node","type","is","the","same","as","its","destination","node","type",".","*","``","'reverse_types","'","``",",","which","excludes","the","reverse","edges","of","the","sampled","edges",".","The","said","reverse","edges","have","different","edge","types","from","the","sampled","edges",".","If","``","g_sampling","``","is","given",",","``","exclude","``","is","ignored","and","will","be","always","``","None","``",".","reverse_eids",":","Tensor","or","dict","[","etype",",","Tensor","]",",","optional","A","tensor","of","reverse","edge","ID","mapping",".","The","i-th","element","indicates","the","ID","of","the","i-th","edge","'s","reverse","edge",".","If","the","graph","is","heterogeneous",",","this","argument","requires","a","dictionary","of","edge","types","and","the","reverse","edge","ID","mapping","tensors",".","Required","and","only","used","when","``","exclude","``","is","set","to","``","reverse_id","``",".","For","heterogeneous","graph","this","will","be","a","dict","of","edge","type","and","edge","IDs",".","Note","that","only","the","edge","types","whose","source","node","type","is","the","same","as","destination","node","type","are","needed",".","reverse_etypes",":","dict","[","etype",",","etype","]",",","optional","The","mapping","from","the","edge","type","to","its","reverse","edge","type",".","Required","and","only","used","when","``","exclude","``","is","set","to","``","reverse_types","``",".","negative_sampler",":","callable",",","optional","The","negative","sampler",".","Can","be","omitted","if","no","negative","sampling","is","needed",".","The","negative","sampler","must","be","a","callable","that","takes","in","the","following","arguments",":","*","The","original","(","heterogeneous",")","graph",".","*","The","ID","array","of","sampled","edges","in","the","minibatch",",","or","the","dictionary","of","edge","types","and","ID","array","of","sampled","edges","in","the","minibatch","if","the","graph","is","heterogeneous",".","It","should","return","*","A","pair","of","source","and","destination","node","ID","arrays","as","negative","samples",",","or","a","dictionary","of","edge","types","and","such","pairs","if","the","graph","is","heterogenenous",".","A","set","of","builtin","negative","samplers","are","provided","in",":","ref",":","`","the","negative","sampling","module","<","api-dataloading-negative-sampling",">","`",".","Examples","--","--","--","--","The","following","example","shows","how","to","train","a","3-layer","GNN","for","edge","classification","on","a","set","of","edges","``","train_eid","``","on","a","homogeneous","undirected","graph",".","Each","node","takes","messages","from","all","neighbors",".","Say","that","you","have","an","array","of","source","node","IDs","``","src","``","and","another","array","of","destination","node","IDs","``","dst","``",".","One","can","make","it","bidirectional","by","adding","another","set","of","edges","that","connects","from","``","dst","``","to","``","src","``",":",">",">",">","g","=","dgl.graph","(","(","torch.cat","(","[","src",",","dst","]",")",",","torch.cat","(","[","dst",",","src","]",")",")",")","One","can","then","know","that","the","ID","difference","of","an","edge","and","its","reverse","edge","is","``","|E|","``",",","where","``","|E|","``","is","the","length","of","your","source\/destination","array",".","The","reverse","edge","mapping","can","be","obtained","by",">",">",">","E","=","len","(","src",")",">",">",">","reverse_eids","=","torch.cat","(","[","torch.arange","(","E",",","2","*","E",")",",","torch.arange","(","0",",","E",")","]",")","Note","that","the","sampled","edges","as","well","as","their","reverse","edges","are","removed","from","computation","dependencies","of","the","incident","nodes",".","This","is","a","common","trick","to","avoid","information","leakage",".",">",">",">","sampler","=","dgl.dataloading.MultiLayerNeighborSampler","(","[","15",",","10",",","5","]",")",">",">",">","collator","=","dgl.dataloading.EdgeCollator","(","...","g",",","train_eid",",","sampler",",","exclude='reverse_id","'",",","...","reverse_eids=reverse_eids",")",">",">",">","dataloader","=","torch.utils.data.DataLoader","(","...","collator.dataset",",","collate_fn=collator.collate",",","...","batch_size=1024",",","shuffle=True",",","drop_last=False",",","num_workers=4",")",">",">",">","for","input_nodes",",","pair_graph",",","blocks","in","dataloader",":","...","train_on","(","input_nodes",",","pair_graph",",","blocks",")","To","train","a","3-layer","GNN","for","link","prediction","on","a","set","of","edges","``","train_eid","``","on","a","homogeneous","graph","where","each","node","takes","messages","from","all","neighbors","(","assume","the","backend","is","PyTorch",")",",","with","5","uniformly","chosen","negative","samples","per","edge",":",">",">",">","sampler","=","dgl.dataloading.MultiLayerNeighborSampler","(","[","15",",","10",",","5","]",")",">",">",">","neg_sampler","=","dgl.dataloading.negative_sampler.Uniform","(","5",")",">",">",">","collator","=","dgl.dataloading.EdgeCollator","(","...","g",",","train_eid",",","sampler",",","exclude='reverse_id","'",",","...","reverse_eids=reverse_eids",",","negative_sampler=neg_sampler",")",">",">",">","dataloader","=","torch.utils.data.DataLoader","(","...","collator.dataset",",","collate_fn=collator.collate",",","...","batch_size=1024",",","shuffle=True",",","drop_last=False",",","num_workers=4",")",">",">",">","for","input_nodes",",","pos_pair_graph",",","neg_pair_graph",",","blocks","in","dataloader",":","...","train_on","(","input_nodse",",","pair_graph",",","neg_pair_graph",",","blocks",")","For","heterogeneous","graphs",",","the","reverse","of","an","edge","may","have","a","different","edge","type","from","the","original","edge",".","For","instance",",","consider","that","you","have","an","array","of","user-item","clicks",",","representated","by","a","user","array","``","user","``","and","an","item","array","``","item","``",".","You","may","want","to","build","a","heterogeneous","graph","with","a","user-click-item","relation","and","an","item-clicked-by-user","relation",".",">",">",">","g","=","dgl.heterograph","(","{","...","(","'user","'",",","'click","'",",","'item","'",")",":","(","user",",","item",")",",","...","(","'item","'",",","'clicked-by","'",",","'user","'",")",":","(","item",",","user",")","}",")","To","train","a","3-layer","GNN","for","edge","classification","on","a","set","of","edges","``","train_eid","``","with","type","``","click","``",",","you","can","write",">",">",">","sampler","=","dgl.dataloading.MultiLayerNeighborSampler","(","[","15",",","10",",","5","]",")",">",">",">","collator","=","dgl.dataloading.EdgeCollator","(","...","g",",","{","'click","'",":","train_eid","}",",","sampler",",","exclude='reverse_types","'",",","...","reverse_etypes=","{","'click","'",":","'clicked-by","'",",","'clicked-by","'",":","'click","'","}",")",">",">",">","dataloader","=","torch.utils.data.DataLoader","(","...","collator.dataset",",","collate_fn=collator.collate",",","...","batch_size=1024",",","shuffle=True",",","drop_last=False",",","num_workers=4",")",">",">",">","for","input_nodes",",","pair_graph",",","blocks","in","dataloader",":","...","train_on","(","input_nodes",",","pair_graph",",","blocks",")","To","train","a","3-layer","GNN","for","link","prediction","on","a","set","of","edges","``","train_eid","``","with","type","``","click","``",",","you","can","write",">",">",">","sampler","=","dgl.dataloading.MultiLayerNeighborSampler","(","[","15",",","10",",","5","]",")",">",">",">","neg_sampler","=","dgl.dataloading.negative_sampler.Uniform","(","5",")",">",">",">","collator","=","dgl.dataloading.EdgeCollator","(","...","g",",","train_eid",",","sampler",",","exclude='reverse_types","'",",","...","reverse_etypes=","{","'click","'",":","'clicked-by","'",",","'clicked-by","'",":","'click","'","}",",","...","negative_sampler=neg_sampler",")",">",">",">","dataloader","=","torch.utils.data.DataLoader","(","...","collator.dataset",",","collate_fn=collator.collate",",","...","batch_size=1024",",","shuffle=True",",","drop_last=False",",","num_workers=4",")",">",">",">","for","input_nodes",",","pos_pair_graph",",","neg_pair_graph",",","blocks","in","dataloader",":","...","train_on","(","input_nodes",",","pair_graph",",","neg_pair_graph",",","blocks",")","Notes","--","--","-","For","the","concept","of","MFGs",",","please","refer","to",":","ref",":","`","User","Guide","Section","6","<","guide-minibatch",">","`","and",":","doc",":","`","Minibatch","Training","Tutorials","<","tutorials\/large\/L0_neighbor_sampling_overview",">","`","."]
code: def dataset(self):
      return self._dataset
  
imports: import inspect
  from abc import ABC, abstractmethod, abstractproperty
  from collections.abc import Mapping
  from ..None import backend, transforms, utils
  from ..base import EID, NID
  from ..convert import heterograph
  from ..distributed import DistDataLoader
label_desc: Use image node_id 2 for calling the EdgeCollator obj's underlying member method code with example usage: obj.dataset() and returns: self