lenskit.als#

LensKit ALS implementations.

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

Bases: IterativeTraining, Component[ItemList, …], ABC

Base class for ALS models.

Stability:

Caller (see Stability Levels).

Parameters:

• config (ALSConfig)

• kwargs (Any)

training_loop(data, options)#

Run ALS to train a model.

Parameters:

• ratings – the ratings data frame.

• data (Dataset)

• options (TrainingOptions)

Returns:

True if the model was trained.

Return type:

Generator[dict[str, float], None, None]

abstract prepare_data(data)#

Prepare data for training this model. This takes in the ratings, and is supposed to do two things:

• Normalize or transform the rating/interaction data, as needed, for training.

• Store any parameters learned from the normalization (e.g. means) in the appropriate member variables.

• Return the training data object to use for model training.

Parameters:

data (Dataset)

Return type:

TrainingData

initialize_params(data, rng)#

Initialize the model parameters at the beginning of training.

Parameters:

• data (TrainingData)

• rng (Generator)

abstract initial_params(nrows, ncols, rng)#

Compute initial parameter values of the specified shape.

Parameters:

• nrows (int)

• ncols (int)

• rng (Generator)

Return type:

Tensor

abstract als_half_epoch(epoch, context)#

Run one half of an ALS training epoch.

Parameters:

• epoch (int)

• context (TrainContext)

Return type:

float

abstract new_user_embedding(user_num, items)#

Generate an embedding for a user given their current ratings.

Parameters:

• user_num (int | None)

• items (ItemList)

Return type:

tuple[Tensor, float | None]

finalize_scores(user_num, items, user_bias)#

Perform any final transformation of scores prior to returning them.

Parameters:

• user_num (int | None)

• items (ItemList)

• user_bias (float | None)

Return type:

ItemList

class lenskit.als.ALSConfig(*, embedding_size=50, epochs=10, regularization=0.1, user_embeddings=True)#

Bases: BaseModel

Configuration for ALS scorers.

Parameters:

• embedding_size (int)

• epochs (int)

• regularization (float | UIPair[float])

• user_embeddings (bool | Literal['prefer'])

embedding_size: int#

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

epochs: int#

The number of epochs to train.

regularization: float | UIPair[float]#

L2 regularization strength.

user_embeddings: bool | Literal['prefer']#

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.

model_config: ClassVar[ConfigDict] = {}#

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

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

Bases: ALSBase

Biased matrix factorization trained with alternating least squares [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 (BiasedMFConfig)

• kwargs (Any)

prepare_data(data)#

Prepare data for training this model. This takes in the ratings, and is supposed to do two things:

• Normalize or transform the rating/interaction data, as needed, for training.

• Store any parameters learned from the normalization (e.g. means) in the appropriate member variables.

• Return the training data object to use for model training.

Parameters:

data (Dataset)

initial_params(nrows, ncols, rng)#

Compute initial parameter values of the specified shape.

Parameters:

• nrows (int)

• ncols (int)

• rng (Generator)

Return type:

Tensor

als_half_epoch(epoch, context)#

Run one half of an ALS training epoch.

Parameters:

• epoch (int)

• context (TrainContext)

new_user_embedding(user_num, items)#

Generate an embedding for a user given their current ratings.

Parameters:

• user_num (int | None)

• items (ItemList)

Return type:

tuple[Tensor, float | None]

finalize_scores(user_num, items, user_bias)#

Perform any final transformation of scores prior to returning them.

Parameters:

• user_num (int | None)

• items (ItemList)

• user_bias (float | None)

Return type:

ItemList

class lenskit.als.BiasedMFConfig(*, embedding_size=50, epochs=10, regularization=0.1, user_embeddings=True, damping=5.0)#

Bases: ALSConfig

Parameters:

• embedding_size (int)

• epochs (int)

• regularization (float | UIPair[float])

• user_embeddings (bool | Literal['prefer'])

• damping (float | dict[Literal['user', 'item'], float])

damping: Damping#

Damping for the bias model.

model_config: ClassVar[ConfigDict] = {}#

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

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

Bases: 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}}^{\ast }+Rw$, where ${\mathbb{1}}^{\ast }$ 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 (ImplicitMFConfig)

• kwargs (Any)

prepare_data(data)#

Prepare data for training this model. This takes in the ratings, and is supposed to do two things:

• Normalize or transform the rating/interaction data, as needed, for training.

• Store any parameters learned from the normalization (e.g. means) in the appropriate member variables.

• Return the training data object to use for model training.

Parameters:

data (Dataset)

Return type:

TrainingData

initial_params(nrows, ncols, rng)#

Compute initial parameter values of the specified shape.

Parameters:

• nrows (int)

• ncols (int)

• rng (Generator)

Return type:

Tensor

als_half_epoch(epoch, context)#

Run one half of an ALS training epoch.

Parameters:

• epoch (int)

• context (TrainContext)

Return type:

float

new_user_embedding(user_num, user_items)#

Generate an embedding for a user given their current ratings.

Parameters:

• user_num (int | None)

• user_items (ItemList)

Return type:

tuple[Tensor, None]

class lenskit.als.ImplicitMFConfig(*, embedding_size=50, epochs=10, regularization=0.1, user_embeddings=True, weight=40, use_ratings=False)#

Bases: ALSConfig

Parameters:

• embedding_size (int)

• epochs (int)

• regularization (float | UIPair[float])

• user_embeddings (bool | Literal['prefer'])

• weight (float)

• use_ratings (bool)

weight: float#

The confidence weight for positive examples.

use_ratings: bool#

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

model_config: ClassVar[ConfigDict] = {}#

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