lenskit.als#

LensKit ALS implementations.

class lenskit.als.ALSBase(features, *, epochs=10, reg=0.1, save_user_features=True, rng=None)#

Bases: ABC, Component, Trainable

Base class for ALS models.

Parameters:
abstract property logger: Logger#

Overridden in implementation to provide the logger.

property is_trained: bool#

Check if this model has already been trained.

train(data)#

Run ALS to train a model.

Parameters:

  • ratings – the ratings data frame.

  • data (Dataset)

fit_iters(data, *, timer=None)#

Run ALS to train a model, yielding after each iteration.

Parameters:
Return type:

Iterator[Self]

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)#

Initialize the model parameters at the beginning of training.

Parameters:

data (TrainingData)

abstract initial_params(nrows, ncols, rng)#

Compute initial parameter values of the specified shape.

Parameters:
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:
Return type:

tuple[Tensor, float | None]

finalize_scores(user_num, items, user_bias)#

Perform any final transformation of scores prior to returning them.

Parameters:
Return type:

ItemList

class lenskit.als.BiasedMFScorer(features, *, epochs=10, reg=0.1, damping=5.0, rng=None, save_user_features=True)#

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.

Parameters:

  • features (int) – The number of features to train.

  • epochs (int) – The number of iterations to train.

  • reg (UITuple[float]) – The regularization factor; can also be a tuple (ureg, ireg) to specify separate user and item regularization terms.

  • damping (UITuple[float]) – Damping term for the bias model.

  • rng (lenskit.types.RNGInput) – Random number seed or generator.

  • save_user_features (bool)

property logger#

Overridden in implementation to provide the logger.

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:
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:
Return type:

tuple[Tensor, float | None]

finalize_scores(user_num, items, user_bias)#

Perform any final transformation of scores prior to returning them.

Parameters:
Return type:

ItemList

class lenskit.als.ImplicitMFScorer(features, *, epochs=20, reg=0.1, weight=40, use_ratings=False, save_user_features=True, rng=None)#

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.

See the base class MFPredictor for documentation on the estimated parameters you can extract from a trained model.

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

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.

Parameters:

  • features (int) – The number of features to train

  • epochs (int) – The number of iterations to train

  • reg (UITuple[float]) – The regularization factor

  • weight (float) – The scaling weight for positive samples (\(\alpha\) in [HKV08]).

  • use_ratings (bool) – Whether to use the rating column, if present. Defaults to False; when True, the values from the rating column are used, and multipled by weight; if False, ImplicitMF treats every rated user-item pair as having a rating of 1. save_user_feature: Whether to save the user feature vector in the model, or recompute it at scoring time.

  • rng (lenskit.types.RNGInput) – Random number seed or generator.

  • save_user_features (bool)

property logger#

Overridden in implementation to provide the logger.

train(data)#

Run ALS to train a model.

Parameters:

  • ratings – the ratings data frame.

  • data (Dataset)

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:
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:
Return type:

tuple[Tensor, None]