lenskit.basic#

Basic and baseline pipeline components.

class lenskit.basic.BiasModel(damping, global_bias, items=None, item_biases=None, users=None, user_biases=None)#

Bases: object

User-item bias models learned from rating data. The BiasScorer class uses this model to score items in a pipeline; the model is reusable in other components that need user-item bias models.

This implements the following model:

\[b_{ui} = b_g + b_i + b_u\]

where \(b_g\) is the global bias (global mean rating), \(b_i\) is item bias, and \(b_u\) is the user bias. With the provided damping values \(\beta_{\mathrm{u}}\) and \(\beta_{\mathrm{i}}\), they are computed as follows:

\[\begin{align*} b_g & = \frac{\sum_{r_{ui} \in R} r_{ui}}{|R|} & b_i & = \frac{\sum_{r_{ui} \in R_i} (r_{ui} - b_g)}{|R_i| + \beta_{\mathrm{i}}} & b_u & = \frac{\sum_{r_{ui} \in R_u} (r_{ui} - b_g - b_i)}{|R_u| + \beta_{\mathrm{u}}} \end{align*}\]

The damping values can be interpreted as the number of default (mean) ratings to assume a priori for each user or item, damping low-information users and items towards a mean instead of permitting them to take on extreme values based on few ratings.

Stability:
Caller (see Stability Levels).
Parameters:
damping: float | dict[Literal['user', 'item'], float]#

The mean damping terms.

global_bias: float#

The global bias term.

items: Vocabulary | None = None#

Vocabulary of items.

item_biases: ndarray[int, dtype[float32]] | None = None#

The item offsets (\(b_i\) values).

users: Vocabulary | None = None#

Vocabulary of users.

user_biases: ndarray[int, dtype[float32]] | None = None#

The user offsets (\(b_u\) values).

classmethod learn(data, damping=0.0, *, entities=frozenset({'item', 'user'}))#

Learn a bias model and its parameters from a dataset.

Parameters:

  • data (Dataset) – The dataset from which to learn the bias model.

  • damping (float | dict[Literal['user', 'item'], float] | tuple[float, float]) – Bayesian damping to apply to computed biases. Either a number, to damp both user and item biases the same amount, or a (user,item) tuple providing separate damping values.

  • items – Whether to compute item biases

  • users – Whether to compute user biases

  • entities (Container[Literal['user', 'item']])

Return type:

Self

compute_for_items(items, user_id=None, user_items=None, *, bias=None)#

Compute the personalized biases for a set of itemsm and optionally a user. The user can be specified either by their identifier or by a list of ratings.

Parameters:

  • items (ItemList) – The items to score.

  • user – The user identifier.

  • user_items (ItemList | None) – The user’s items, with ratings (takes precedence over user if both are supplied). If the supplied list does not have a rating field, it is ignored.

  • bias (float | None) – A pre-computed user bias.

  • user_id (int | str | bytes | integer[Any] | str_ | bytes_ | object_ | None)

Returns:

A tuple of the overall bias scores for the specified items and user, and the user’s bias (needed to de-normalize scores efficiently later). If a user bias is provided instead of user information, only the composite bias scores are returned.

transform_matrix(matrix)#

Transform a sparse ratings matrix by subtracting biases.

Parameters:

matrix (Tensor)

class lenskit.basic.BiasScorer(config=None, **kwargs)#

Bases: Component[ItemList, …], Trainable

A user-item bias rating prediction model. This component uses BiasModel to predict ratings for users and items.

Parameters:

  • config (BiasConfig) – The component configuration.

  • kwargs (Any)

Stability:
Caller (see Stability Levels).
train(data, options=TrainingOptions(retrain=True, device=None, rng=None))#

Train the bias model on some rating data.

Parameters:
Returns:

The trained bias object.

class lenskit.basic.PopScorer(config=None, **kwargs)#

Bases: Component[ItemList, …], Trainable

Score items by their popularity. Use with TopN to get a most-popular-items recommender.

Stability:
Caller (see Stability Levels).
Parameters:
item_pop_#

Item popularity scores.

train(data, options=TrainingOptions(retrain=True, device=None, rng=None))#

Train the model to learn its parameters from a training dataset.

Parameters:
class lenskit.basic.TopNRanker(config=None, **kwargs)#

Bases: Component[ItemList, …]

Rank scored items by their score and take the top N. The ranking length can be passed either at runtime or at component instantiation time, with the latter taking precedence.

Stability:
Caller (see Stability Levels).
Parameters:
class lenskit.basic.RandomSelector(config=None, **kwargs)#

Bases: Component[ItemList, …]

Randomly select items from a candidate list.

Stability:
Caller (see Stability Levels).
Parameters:

  • n – The number of items to select, or -1 to randomly permute the items.

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

  • config (RandomConfig)

class lenskit.basic.SoftmaxRanker(config=None, **kwargs)#

Bases: Component[ItemList, …]

Stochastic top-N ranking with softmax sampling.

This uses the “softmax” 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.

Note

Negative scores are 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 (RandomConfig)

class lenskit.basic.UserTrainingHistoryLookup(config=None, **kwargs)#

Bases: Component[ItemList, …], Trainable

Look up a user’s history from the training data.

Stability:
Caller (see Stability Levels).
Parameters:
train(data, options=TrainingOptions(retrain=True, device=None, rng=None))#

Train the model to learn its parameters from a training dataset.

Parameters:
class lenskit.basic.UnratedTrainingItemsCandidateSelector(config=None, **kwargs)#

Bases: TrainingCandidateSelectorBase

Candidate selector that selects all known items from the training data that do not appear in the request user’s history (RecQuery.user_items). If no item history is available, then all training items are returned.

In order to look up the user’s history in the training data, this needs to be combined with a component like UserTrainingHistoryLookup.

Stability:
Caller (see Stability Levels).
Parameters:

  • config (None)

  • kwargs (Any)

class lenskit.basic.AllTrainingItemsCandidateSelector(config=None, **kwargs)#

Bases: TrainingCandidateSelectorBase

Candidate selector that selects all known items from the training data.

Stability:
Caller (see Stability Levels).
Parameters:

  • config (None)

  • kwargs (Any)

class lenskit.basic.FallbackScorer(config=None, **kwargs)#

Bases: Component[ItemList, …]

Scoring component that fills in missing scores using a fallback.

Stability:
Caller (see Stability Levels).
Parameters:

  • config (None)

  • kwargs (Any)

Modules

bias

Bias scoring model.

candidates

composite

history

Components that look up user history from the training data.

popularity

random

topn

Basic Top-N ranking.