dgl.sampling.global_uniform_negative_sampling

dgl.sampling.global_uniform_negative_sampling(g, num_samples, exclude_self_loops=True, replace=False, etype=None, redundancy=None)[source]

Performs negative sampling, which generate source-destination pairs such that edges with the given type do not exist.

Specifically, this function takes in an edge type and a number of samples. It returns two tensors src and dst, the former in the range of [0, num_src) and the latter in the range of [0, num_dst), where num_src and num_dst represents the number of nodes with the source and destination node type respectively. It guarantees that no edge will exist between the corresponding pairs of src with the source node type and dst with the destination node type.

Note

This negative sampler will try to generate as many negative samples as possible, but it may rarely return less than num_samples negative samples. This is more likely to happen when a graph is so small or dense that not many unique negative samples exist.

Parameters

  • g (DGLGraph) – The graph.

  • num_samples (int) – The number of desired negative samples to generate.

  • exclude_self_loops (bool, optional) –

    Whether to exclude self-loops from the negative samples. Only impacts the edge types whose source and destination node types are the same.

    Default: True.

  • replace (bool, optional) – Whether to sample with replacement. Setting it to True will make things faster. (Default: False)

  • etype (str or tuple of str, optional) – The edge type. Can be omitted if the graph only has one edge type.

  • redundancy (float, optional) –

    Indicates how much more negative samples to actually generate during rejection sampling before finding the unique pairs.

    Increasing it will increase the likelihood of getting num_samples negative samples, but will also take more time and memory.

    (Default: automatically determined by the density of graph)

Returns

The source and destination pairs.

Return type

tuple[Tensor, Tensor]

Examples

>>> g = dgl.graph(([0, 1, 2], [1, 2, 3]))
>>> dgl.sampling.global_uniform_negative_sampling(g, 3)
(tensor([0, 1, 3]), tensor([2, 0, 2]))