lenskit.basic.bias#

Bias scoring model.

Attributes#

BiasEntity

Damping

Classes#

BiasModel

User-item bias models learned from rating data. The BiasScorer

BiasConfig

Configuration for BiasScorer.

BiasScorer

A user-item bias rating prediction model. This component uses

Functions#

entity_damping(damping, entity)

Look up the damping for a particular entity type.

Module Contents#

type lenskit.basic.bias.BiasEntity = Literal['user', 'item']#
type lenskit.basic.bias.Damping = float | dict[BiasEntity, float]#
class lenskit.basic.bias.BiasModel#

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).
damping: Damping#

The mean damping terms.

global_bias: float#

The global bias term.

items: lenskit.data.Vocabulary | None = None#

Vocabulary of items.

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

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

users: lenskit.data.Vocabulary | None = None#

Vocabulary of users.

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

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

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

Learn a bias model and its parameters from a dataset.

Parameters:

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

  • damping (Damping | 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 (collections.abc.Container[BiasEntity])

Return type:

Self

compute_for_items(items: lenskit.data.ItemList, user_id: lenskit.data.ID | None = None, user_items: lenskit.data.ItemList | None = None) → tuple[numpy.ndarray[tuple[int], numpy.dtype[numpy.float32]], float]#
compute_for_items(items: lenskit.data.ItemList, *, bias: float) → numpy.ndarray[tuple[int], numpy.dtype[numpy.float32]]

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 – The items to score.

  • user – The user identifier.

  • user_items – 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 – A pre-computed user bias.

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: scipy.sparse.coo_array) → scipy.sparse.coo_array#
transform_matrix(matrix: torch.Tensor) → torch.Tensor

Transform a sparse ratings matrix by subtracting biases.

Parameters:

matrix – The matrix to transform.

class lenskit.basic.bias.BiasConfig#

Bases: pydantic.BaseModel

Configuration for BiasScorer.

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.

damping: pydantic.NonNegativeFloat | dict[Literal['user', 'item'], pydantic.NonNegativeFloat] = 0.0#
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: lenskit.pipeline.components.Component[lenskit.data.ItemList], lenskit.training.Trainable

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

Parameters:

  • config (object | None) – The component configuration.

  • kwargs (Any)

Stability:
Caller (see Stability Levels).
config: BiasConfig#

The component configuration object. Component classes that support configuration must redefine this attribute with their specific configuration class type, which can be a Python dataclass or a Pydantic model class.

model: BiasModel#
is_trained()#

Query if this component has already been trained.

train(data, options=TrainingOptions())#

Train the bias model on some rating data.

Parameters:
Returns:

The trained bias object.

__call__(query, items)#

Compute predictions for a user and items. Unknown users and items are assumed to have zero bias.

Parameters:

  • query (lenskit.data.QueryInput) – The recommendation query. If the query has an item list with ratings, those ratings are used to compute a new bias instead of using the user’s recorded bias.

  • items (lenskit.data.ItemList) – The items to score.

Returns:

Scores for items.

Return type:

lenskit.data.ItemList

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

Look up the damping for a particular entity type.

Parameters:
Return type:

float

Exported Aliases#

lenskit.basic.bias.ID#

Re-exported alias for lenskit.data.ID.

class lenskit.basic.bias.Dataset#

Re-exported alias for lenskit.data.Dataset.

class lenskit.basic.bias.ItemList#

Re-exported alias for lenskit.data.ItemList.

lenskit.basic.bias.QueryInput#

Re-exported alias for lenskit.data.QueryInput.

class lenskit.basic.bias.RecQuery#

Re-exported alias for lenskit.data.RecQuery.

class lenskit.basic.bias.Vocabulary#

Re-exported alias for lenskit.data.Vocabulary.

class lenskit.basic.bias.Component#

Re-exported alias for lenskit.pipeline.components.Component.

lenskit.basic.bias.safe_tensor()#

Re-exported alias for lenskit.torch.safe_tensor().

class lenskit.basic.bias.Trainable#

Re-exported alias for lenskit.training.Trainable.

class lenskit.basic.bias.TrainingOptions#

Re-exported alias for lenskit.training.TrainingOptions.