lenskit.basic.bias#

Bias scoring model.

Classes

BiasModel(damping, global_bias[, items, ...])

User-item bias models learned from rating data.

BiasScorer([items, users, damping, ...])

A user-item bias rating prediction model.
class lenskit.basic.bias.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.

Parameters:
damping: UITuple[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, *, items=True, users=True)#

Learn a bias model and its parameters from a dataset.

Parameters:

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

  • damping (float | UITuple[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 (bool) – Whether to compute item biases

  • users (bool) – Whether to compute user biases

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.bias.BiasScorer(items=True, users=True, damping=0.0, *, user_damping=None, item_damping=None)#

Bases: Component

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

Parameters:

  • items (bool) – Whether to compute item biases.

  • users (bool) – Whether to compute user biases.

  • damping (float | UITuple[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.

  • user_damping (float | None)

  • item_damping (float | None)

IGNORED_CONFIG_FIELDS: ClassVar[list[str]] = ['user_damping', 'item_damping']#

Names of constructor parameters that should be excluded from the configuration dictionary.

damping: UITuple[float]#

The configured offset damping levels.

train(data)#

Train the bias model on some rating data.

Parameters:

  • ratings – The training data (must have ratings).

  • data (Dataset)

Returns:

The trained bias object.