Basic and Utility Algorithms

The lenskit.algorithms.basic module contains baseline and utility algorithms for nonpersonalized recommendation and testing.

Personalized Mean Rating Prediction

class lenskit.algorithms.basic.Bias(items=True, users=True, damping=0.0)

Bases: lenskit.algorithms.Predictor

A user-item bias rating prediction algorithm. This implements the following predictor algorithm:

\[s(u,i) = \mu + b_i + b_u\]

where \(\mu\) is the 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*} \mu & = \frac{\sum_{r_{ui} \in R} r_{ui}}{|R|} & b_i & = \frac{\sum_{r_{ui} \in R_i} (r_{ui} - \mu)}{|R_i| + \beta_{\mathrm{i}}} & b_u & = \frac{\sum_{r_{ui} \in R_u} (r_{ui} - \mu - 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.

Parameters

  • items – whether to compute item biases

  • users – whether to compute user biases

  • damping (number or tuple) – 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.

mean_: double

The global mean rating.

item_offsets_: pandas.Series

The item offsets (\(b_i\) values)

user_offsets_: pandas.Series

The item offsets (\(b_u\) values)

fit(ratings, **kwargs)

Train the bias model on some rating data.

Parameters

ratings (DataFrame) – a data frame of ratings. Must have at least user, item, and rating columns.

Returns

the fit bias object.

Return type

Bias

transform(ratings, *, indexes=False)

Transform ratings by removing the bias term.

Parameters

  • ratings (pandas.DataFrame) – The ratings to transform. Must contain at least user, item, and rating columns.

  • indexes (bool) – if True, the resulting frame will include uidx and iidx columns containing the 0-based user and item indexes for each rating.

Returns

A data frame with rating transformed by subtracting user-item bias prediction.

Return type

pandas.DataFrame

inverse_transform(ratings)

Transform ratings by removing the bias term.

fit_transform(ratings, **kwargs)

Fit with ratings and return the training data transformed.

predict_for_user(user, items, ratings=None)

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

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, will be used to recompute the user’s bias at prediction time.

Returns

scores for the items, indexed by item id.

Return type

pandas.Series

property user_index

Get the user index from this (fit) bias.

property item_index

Get the item index from this (fit) bias.

Random Item Recommendation

The Random algorithm implements random-item recommendation.

class lenskit.algorithms.basic.Random(selector=None, rng_spec=None)

Bases: lenskit.algorithms.Recommender

A random-item recommender.

selector: CandidateSelector

Selects candidate items for recommendation. Default is UnratedItemCandidateSelector.

rng_spec

Seed or random state for generating recommendations. Pass 'user' to deterministically derive per-user RNGS from the user IDs for reproducibility.

fit(ratings, **kwargs)

Train a model using the specified ratings (or similar) data.

Parameters

  • ratings (pandas.DataFrame) – The ratings data.

  • kwargs – Additional training data the algorithm may require. Algorithms should avoid using the same keyword arguments for different purposes, so that they can be more easily hybridized.

Returns

The algorithm object.

recommend(user, n=None, candidates=None, ratings=None)

Compute recommendations for a user.

Parameters

  • user – the user ID

  • n (int) – the number of recommendations to produce (None for unlimited)

  • candidates (array-like) – The set of valid candidate items; if None, a default set will be used. For many algorithms, this is their CandidateSelector.

  • 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

a frame with an item column; if the recommender also produces scores, they will be in a score column.

Return type

pandas.DataFrame

Top-N Recommender

The TopN class implements a standard top-N recommender that wraps a Predictor and CandidateSelector and returns the top N candidate items by predicted rating. It is the type of recommender returned by Recommender.adapt() if the provided algorithm is not a recommender.

class lenskit.algorithms.basic.TopN(predictor, selector=None)

Bases: lenskit.algorithms.Recommender, lenskit.algorithms.Predictor

Basic recommender that implements top-N recommendation using a predictor.

Note

This class does not do anything of its own in fit(). If its predictor and candidate selector are both fit, the top-N recommender does not need to be fit.

Parameters
fit(ratings, **kwargs)

Fit the recommender.

Parameters

  • ratings (pandas.DataFrame) – The rating or interaction data. Passed changed to the predictor and candidate selector.

  • kwargs (args,) – Additional arguments for the predictor to use in its training process.

recommend(user, n=None, candidates=None, ratings=None)

Compute recommendations for a user.

Parameters

  • user – the user ID

  • n (int) – the number of recommendations to produce (None for unlimited)

  • candidates (array-like) – The set of valid candidate items; if None, a default set will be used. For many algorithms, this is their CandidateSelector.

  • 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

a frame with an item column; if the recommender also produces scores, they will be in a score column.

Return type

pandas.DataFrame

predict(pairs, ratings=None)

Compute predictions for user-item pairs. This method is designed to be compatible with the general SciKit paradigm; applications typically want to use predict_for_user().

Parameters
Returns

The predicted scores for each user-item pair.

Return type

pandas.Series

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

Unrated Item Candidate Selector

UnratedItemCandidateSelector is a candidate selector that remembers items users have rated, and returns a candidate set consisting of all unrated items. It is the default candidate selector for TopN.

class lenskit.algorithms.basic.UnratedItemCandidateSelector

Bases: lenskit.algorithms.CandidateSelector

CandidateSelector that selects items a user has not rated as candidates. When this selector is fit, it memorizes the rated items.

items_: pandas.Index

All known items.

users_: pandas.Index

All known users.

user_items_: CSR

Items rated by each known user, as positions in the items index.

fit(ratings, **kwargs)

Train a model using the specified ratings (or similar) data.

Parameters

  • ratings (pandas.DataFrame) – The ratings data.

  • kwargs – Additional training data the algorithm may require. Algorithms should avoid using the same keyword arguments for different purposes, so that they can be more easily hybridized.

Returns

The algorithm object.

candidates(user, ratings=None)

Select candidates for the user.

Parameters

  • user – The user key or ID.

  • ratings (pandas.Series or array-like) – Ratings or items to use instead of whatever ratings were memorized for this user. If a pandas.Series, the series index is used; if it is another array-like it is assumed to be an array of items.

Fallback Predictor

The Fallback rating predictor is a simple hybrid that takes a list of composite algorithms, and uses the first one to return a result to predict the rating for each item.

A common case is to fill in with Bias when a primary predictor cannot score an item.

class lenskit.algorithms.basic.Fallback(algorithms, *others)

Bases: lenskit.algorithms.Predictor

The Fallback algorithm predicts with its first component, uses the second to fill in missing values, and so forth.

fit(ratings, **kwargs)

Train a model using the specified ratings (or similar) data.

Parameters

  • ratings (pandas.DataFrame) – The ratings data.

  • kwargs – Additional training data the algorithm may require. Algorithms should avoid using the same keyword arguments for different purposes, so that they can be more easily hybridized.

Returns

The algorithm object.

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

Memorized Predictor

The Memorized recommender is primarily useful for test cases. It memorizes a set of rating predictions and returns them.

class lenskit.algorithms.basic.Memorized(scores)

Bases: lenskit.algorithms.Predictor

The memorized algorithm memorizes socres provided at construction time.

fit(*args, **kwargs)

Train a model using the specified ratings (or similar) data.

Parameters

  • ratings (pandas.DataFrame) – The ratings data.

  • kwargs – Additional training data the algorithm may require. Algorithms should avoid using the same keyword arguments for different purposes, so that they can be more easily hybridized.

Returns

The algorithm object.

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