lenskit.stochastic#

Components for generating sochastic outputs in LensKit pipelines.

class lenskit.stochastic.StochasticTopNConfig(n=None, rng=None, transform='softmax', scale=1.0)#

Bases: object

Configuration for StochasticTopNRanker.

Parameters:

  • n (int | None)

  • rng (int | Sequence[int] | None | Literal['user'] | tuple[int | ~typing.Sequence[int] | None, ~typing.Literal['user']])

  • transform (Literal['softmax', 'linear'] | None)

  • scale (float)

n: int | None = None#

The number of items to select. -1 or None to return all scored items.

rng: int | Sequence[int] | None | Literal['user'] | tuple[int | Sequence[int] | None, Literal['user']] = None#

Random number generator configuration.

scale: float = 1.0#

Scalar multiplier to apply to scores prior to transformation. This is equivalent to the \(\beta\) parameter for parameterized softmax transformation. Larger values will decrease the entropy of the sampled rankings.

transform: Literal['softmax', 'linear'] | None = 'softmax'#

Transformation to convert scores into ranking probabilities.

softmax

Use the softmax of the item scores as the selection probabilities.

linear

Linearly re-scale item scores to be selection probabilities. This equivalent to min-max scaling the scores, then re-scaling to sum to 1.

None

No transformation, except negative scores are clamped to (almost) zero. Not recommended unless your item scorer emits multinomial probabilities.

class lenskit.stochastic.StochasticTopNRanker(config=None, **kwargs)#

Bases: Component[ItemList, …]

Stochastic top-N ranking with optional weight transformation.

This uses the exponential sampling method, a more efficient approximation of Plackett-Luce sampling than even the Gumbell trick, as documented by `Tim Vieira`_. It expects a scored list of input items, and samples n items, with selection probabilities proportional to their scores. Scores can be optionally rescaled (inverse temperature) and transformed (e.g. softmax).

Note

When no transformation is used, negative scores are still clamped to (approximately) zero.

Stability:
Caller (see Stability Levels).
Parameters:

  • n – The number of items to return (-1 to return unlimited).

  • rng – The random number generator or specification (see Random Seeds). This class supports derivable RNGs.

  • config (StochasticTopNConfig)