lenskit.als#

LensKit ALS implementations.

Classes#

ALSBase

Base class for ALS models.

ALSConfig

Configuration for ALS scorers.

BiasedMFConfig

Configuration for ALS scorers.

BiasedMFScorer

Biased matrix factorization trained with alternating least squares

ImplicitMFConfig

Configuration for ALS scorers.

ImplicitMFScorer

Implicit matrix factorization trained with alternating least squares

Package Contents#

class lenskit.als.ALSBase(config=None, **kwargs)#

Bases: lenskit.training.UsesTrainer, lenskit.pipeline.Component[lenskit.data.ItemList], abc.ABC

Base class for ALS models.

Stability:
Caller (see Stability Levels).
Parameters:

  • config (object | None)

  • kwargs (Any)

config: ALSConfig#

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.

users: lenskit.data.Vocabulary | None#
items: lenskit.data.Vocabulary#
user_embeddings: lenskit.data.types.NPMatrix | None#
item_embeddings: lenskit.data.types.NPMatrix#
property logger: structlog.stdlib.BoundLogger#
Return type:

structlog.stdlib.BoundLogger

__call__(query, items)#

Run the pipeline’s operation and produce a result. This is the key method for components to implement.

Parameters:
Return type:

lenskit.data.ItemList

abstractmethod new_user_embedding(user_num, items)#

Generate an embedding for a user given their current ratings.

Parameters:
Return type:

tuple[lenskit.data.types.NPVector[numpy.float32], float | None]

finalize_scores(user_num, items, user_bias)#

Perform any final transformation of scores prior to returning them.

Parameters:
Return type:

lenskit.data.ItemList

class lenskit.als.ALSConfig#

Bases: lenskit.config.common.EmbeddingSizeMixin, pydantic.BaseModel

Configuration for ALS scorers.

embedding_size: pydantic.PositiveInt#

The dimension of user and item embeddings (number of latent features to learn).

epochs: pydantic.PositiveInt = 10#

The number of epochs to train.

regularization: pydantic.PositiveFloat | lenskit.data.types.UIPair[pydantic.PositiveFloat] = 0.1#

L2 regularization strength.

user_embeddings: bool | Literal['prefer'] = True#

Whether to retain user embeddings after training. If True, they are retained, but are ignored if the query has historical items; if False, they are not. If set to "prefer", then the user embeddings from training time are used even if the query has a user history. This makes inference faster when histories only consist of the user’s items from the training set.

property user_reg: float#
Return type:

float

property item_reg: float#
Return type:

float

class lenskit.als.BiasedMFConfig#

Bases: lenskit.als._common.ALSConfig

Configuration for ALS scorers.

damping: lenskit.basic.Damping = 5.0#

Damping for the bias model.

class lenskit.als.BiasedMFScorer(config=None, **kwargs)#

Bases: lenskit.als._common.ALSBase

Biased matrix factorization trained with alternating least squares [PilaszyZT10, ZWSP08]. This is a prediction-oriented algorithm suitable for explicit feedback data, using the alternating least squares approach to compute \(P\) and \(Q\) to minimize the regularized squared reconstruction error of the ratings matrix.

See the base class ALSBase for documentation on the estimated parameters you can extract from a trained model. See BiasedMFConfig and ALSConfig for the configuration options for this component.

Stability:
Caller (see Stability Levels).
Parameters:

  • config (object | None)

  • kwargs (Any)

config: BiasedMFConfig#

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.

bias: lenskit.basic.BiasModel#
create_trainer(data, options)#

Create a model trainer to train this model.

new_user_embedding(user_num, items)#

Generate an embedding for a user given their current ratings.

Parameters:
Return type:

tuple[lenskit.data.types.NPVector, float | None]

finalize_scores(user_num, items, user_bias)#

Perform any final transformation of scores prior to returning them.

Parameters:
Return type:

lenskit.data.ItemList

class lenskit.als.ImplicitMFConfig#

Bases: lenskit.als._common.ALSConfig

Configuration for ALS scorers.

weight: float = 40#

The confidence weight for positive examples.

use_ratings: bool = False#

If True, use rating values instead of just presence or absence.

class lenskit.als.ImplicitMFScorer(config=None, **kwargs)#

Bases: lenskit.als._common.ALSBase

Implicit matrix factorization trained with alternating least squares [HKV08]. This algorithm outputs ‘predictions’, but they are not on a meaningful scale. If its input data contains rating values, these will be used as the ‘confidence’ values; otherwise, confidence will be 1 for every rated item.

With weight \(w\), this function decomposes the matrix \(\mathbb{1}^* + Rw\), where \(\mathbb{1}^*\) is an \(m \times n\) matrix of all 1s.

See the base class ALSBase for documentation on the estimated parameters you can extract from a trained model. See ImplicitMFConfig and ALSConfig for the configuration options for this component.

Changed in version 2025.1: ImplicitMFScorer no longer supports multiple training methods. It always uses Cholesky decomposition now.

Changed in version 0.14: By default, ImplicitMF ignores a rating column if one is present in the training data. This can be changed through the use_ratings option.

Changed in version 0.13: In versions prior to 0.13, ImplicitMF used the rating column if it was present. In 0.13, we added an option to control whether or not the rating column is used; it initially defaulted to True, but with a warning. In 0.14 it defaults to False.

Stability:
Caller (see Stability Levels).
Parameters:

  • config (object | None)

  • kwargs (Any)

config: ImplicitMFConfig#

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.

create_trainer(data, options)#

Create a model trainer to train this model.

new_user_embedding(user_num, user_items)#

Generate an embedding for a user given their current ratings.

Parameters:
Return type:

tuple[lenskit.data.types.NPVector, None]