lenskit.basic.bias#

Bias scoring model.

Functions

entity_damping(damping, entity)

Look up the damping for a particular entity type.

Classes

BiasConfig(*[, entities, damping])

Configuration for BiasScorer.

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

User-item bias models learned from rating data.

BiasScorer([config])

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.

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.bias.BiasConfig(*, entities={'item', 'user'}, damping=0)#

Bases: BaseModel

Configuration for BiasScorer.

Parameters:

  • entities (Annotated[set[Literal['user', 'item']], ~pydantic.functional_serializers.PlainSerializer(func=~lenskit.basic.bias.<lambda>, return_type=list[str], when_used=always)])

  • damping (Annotated[float, Ge(ge=0)] | dict[Literal['user', 'item'], ~typing.Annotated[float, ~annotated_types.Ge(ge=0)]])

model_config: ClassVar[ConfigDict] = {'extra': 'forbid'}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

entities: Annotated[set[Literal['user', 'item']], PlainSerializer(lambda s: sorted(s), return_type=list[str])]#

The entities to compute biases for, in addition to global bais. Defaults to users and items.

entity_damping(entity)#

Look up the damping for a particular entity type.

Parameters:

entity (Literal['user', 'item'])

Return type:

float

class lenskit.basic.bias.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.

lenskit.basic.bias.entity_damping(damping, entity)#

Look up the damping for a particular entity type.

Parameters:
Return type:

float