BasicNegativeSampler

class BasicNegativeSampler(*, corruption_scheme: Collection[Literal['head', 'relation', 'tail']] | None = None, **kwargs)[source]

Bases: NegativeSampler

A basic negative sampler.

This negative sampler that corrupts positive triples \((h,r,t) \in \mathcal{K}\) by replacing either \(h\), \(r\) or \(t\) based on the chosen corruption scheme. The corruption scheme can contain \(h\), \(r\) and \(t\) or any subset of these.

Steps:

  1. Randomly (uniformly) determine whether \(h\), \(r\) or \(t\) shall be corrupted for a positive triple \((h,r,t) \in \mathcal{K}\).

  2. Randomly (uniformly) sample an entity \(e \in \mathcal{E}\) or relation \(r' \in \mathcal{R}\) for selection to corrupt the triple.

    • If \(h\) was selected before, the corrupted triple is \((e,r,t)\)

    • If \(r\) was selected before, the corrupted triple is \((h,r',t)\)

    • If \(t\) was selected before, the corrupted triple is \((h,r,e)\)

  3. If filtered is set to True, all proposed corrupted triples that also exist as actual positive triples \((h,r,t) \in \mathcal{K}\) will be removed.

Note

corrupt_batch_grouped() splits num_negs_per_pos per positive, i.e., every positive triple gets the same target mix, whereas corrupt_batch() splits the flattened (b·k) axis into contiguous chunks, i.e., different positives within a batch may get a different target mix. This is a deliberate difference, and the reason why grouped corruption is opt-in.

Initialize the basic negative sampler with the given entities.

Parameters:

  • corruption_scheme (Collection[Literal['head', 'relation', 'tail']] | None) – What sides (‘h’, ‘r’, ‘t’) should be corrupted. Defaults to head and tail (‘h’, ‘t’).

  • kwargs – Additional keyword based arguments passed to NegativeSampler.

Attributes Summary

supports_grouped_corruption

this sampler supports grouped corruption, cf.

Methods Summary

corrupt_batch(positive_batch)

Generate negative samples from the positive batch without application of any filter.

corrupt_batch_grouped(positive_batch)

Generate negative samples from the positive batch, grouped by corrupted target.

Attributes Documentation

supports_grouped_corruption: ClassVar[bool] = True

this sampler supports grouped corruption, cf. corrupt_batch_grouped()

Methods Documentation

corrupt_batch(positive_batch: Tensor) → Tensor[source]

Generate negative samples from the positive batch without application of any filter.

Parameters:

positive_batch (Tensor) – shape: (*batch_dims, 3) The positive triples.

Returns:

shape: (*batch_dims, num_negs_per_pos, 3) The negative triples. result[*bi, :, :] contains the negative examples generated from positive_batch[*bi, :].

Return type:

Tensor

corrupt_batch_grouped(positive_batch: Tensor) → Mapping[Literal['head', 'relation', 'tail'], Tensor][source]

Generate negative samples from the positive batch, grouped by corrupted target.

Unlike corrupt_batch(), this keeps the replacement IDs grouped by which column of the triple they replace, which allows scoring each group with a single call to e.g. score_t() instead of scoring num_negs_per_pos independent triples via score_hrt().

Parameters:

positive_batch (Tensor) – shape: (*batch_dims, 3) The positive triples.

Returns:

a mapping from corrupted target to the replacement IDs, shape: (*batch_dims, k_target), with sum(k_target for k_target in ...) == num_negs_per_pos.

Raises:

NotImplementedError – if this sampler does not support grouped corruption, cf. supports_grouped_corruption.

Return type:

Mapping[Literal[‘head’, ‘relation’, ‘tail’], ~torch.Tensor]