Classic Matrix Factorization

LKPY provides classical matrix factorization implementations.

Common Support

The mf_common module contains common support code for matrix factorization algorithms.

class lenskit.algorithms.mf_common.MFPredictor

Common predictor for matrix factorization.

user_index_

Users in the model (length=:math:m).

Type:pandas.Index
item_index_

Items in the model (length=:math:n).

Type:pandas.Index
user_features_

The \(m \times k\) user-feature matrix.

Type:numpy.ndarray
item_features_

The \(n \times k\) item-feature matrix.

Type:numpy.ndarray
load(path)

Load a fit algorithm from a file. The default implementation unpickles the object and transplants its parameters and model into this object.

Parameters:file (path-like) – the file to load.
lookup_items(items)

Look up the indices for a set of items.

Parameters:items (array-like) – the item IDs to look up.
Returns:the item indices. Unknown items will have negative indices.
Return type:numpy.ndarray
lookup_user(user)

Look up the index for a user.

Parameters:user – the user ID to look up
Returns:the user index.
Return type:int
n_features

The number of features.

n_items

The number of items.

n_users

The number of users.

save(path)

Save a fit algorithm to a file. The default implementation pickles the object.

Parameters:file (path-like) – the file to save.
score(user, items)

Score a set of items for a user. User and item parameters must be indices into the matrices.

Parameters:
  • user (int) – the user index
  • items (array-like of int) – the item indices
  • raw (bool) – if True, do return raw scores without biases added back.
Returns:

the scores for the items.
Return type:

numpy.ndarray
class lenskit.algorithms.mf_common.BiasMFPredictor

Common model for biased matrix factorization.

user_index_

Users in the model (length=:math:m).

Type:pandas.Index
item_index_

Items in the model (length=:math:n).

Type:pandas.Index
global_bias_

The global bias term.

Type:double
user_bias_

The user bias terms.

Type:numpy.ndarray
item_bias_

The item bias terms.

Type:numpy.ndarray
user_features_

The \(m \times k\) user-feature matrix.

Type:numpy.ndarray
item_features_

The \(n \times k\) item-feature matrix.

Type:numpy.ndarray
load(path: pathlib.Path)

Load a fit algorithm from a file. The default implementation unpickles the object and transplants its parameters and model into this object.

Parameters:file (path-like) – the file to load.
save(path)

Save a fit algorithm to a file. The default implementation pickles the object.

Parameters:file (path-like) – the file to save.
score(user, items, raw=False)

Score a set of items for a user. User and item parameters must be indices into the matrices.

Parameters:
  • user (int) – the user index
  • items (array-like of int) – the item indices
  • raw (bool) – if True, do return raw scores without biases added back.
Returns:

the scores for the items.
Return type:

numpy.ndarray

Alternating Least Squares

LensKit provides alternating least squares implementations of matrix factorization suitable for explicit feedback data. These implementations are parallelized with Numba, and perform best with the MKL from Conda.

FunkSVD

FunkSVD is an SVD-like matrix factorization that uses stochastic gradient descent, configured much like coordinate descent, to train the user-feature and item-feature matrices.

class lenskit.algorithms.funksvd.FunkSVD(features, iterations=100, *, lrate=0.001, reg=0.015, damping=5, range=None, bias=True)

Algorithm class implementing FunkSVD matrix factorization.

Parameters:
  • features (int) – the number of features to train
  • iterations (int) – the number of iterations to train each feature
  • lrate (double) – the learning rate
  • reg (double) – the regularization factor
  • damping (double) – damping factor for the underlying mean
  • bias (Predictor) – the underlying bias model to fit. If True, then a basic.Bias model is fit with damping.
  • range (tuple) – the (min, max) rating values to clamp ratings, or None to leave predictions unclamped.
fit(ratings)

Train a FunkSVD model.

Parameters:ratings – the ratings data frame.
predict_for_user(user, items, ratings=None)

Compute predictions for a user and items.

Parameters:
  • user – the user ID
  • items (array-like) – the items to predict
  • ratings (pandas.Series) – the user’s ratings (indexed by item id); if provided, they may be used to override or augment the model’s notion of a user’s preferences.
Returns:

scores for the items, indexed by item id.
Return type:

pandas.Series