Basic and Utility Algorithms¶
The lenskit.algorithms.basic
module contains baseline and utility algorithms
for nonpersonalized recommendation and testing.
Most Popular Item Recommendation¶
The Popular
algorithm implements mostpopularitem recommendation.

class
lenskit.algorithms.basic.
Popular
(selector=None)¶ Bases:
lenskit.Recommender
Recommend the most popular items.
 Parameters
selector (CandidateSelector) – The candidate selector to use. If
None
, uses a newUnratedItemCandidateSelector
.

item_pop_
¶ Item rating counts (popularity)
 Type

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 (arraylike) – The set of valid candidate items; if
None
, a default set will be used. For many algorithms, this is theirCandidateSelector
.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 ascore
column. Return type
Random Item Recommendation¶
The Random
algorithm implements randomitem recommendation.

class
lenskit.algorithms.basic.
Random
(selector=None, rng_spec=None)¶ Bases:
lenskit.Recommender
A randomitem recommender.

selector
¶ Selects candidate items for recommendation. Default is
UnratedItemCandidateSelector
. Type

rng_spec
¶ Seed or random state for generating recommendations. Pass
'user'
to deterministically derive peruser 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 (arraylike) – The set of valid candidate items; if
None
, a default set will be used. For many algorithms, this is theirCandidateSelector
.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 ascore
column. Return type

TopN Recommender¶
The TopN
class implements a standard topN 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.Recommender
,lenskit.Predictor
Basic recommender that implements topN 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 topN recommender does not need to be fit. Parameters
predictor (Predictor) – The underlying predictor.
selector (CandidateSelector) – The candidate selector. If
None
, usesUnratedItemCandidateSelector
.

fit
(ratings, **kwargs)¶ Fit the recommender.
 Parameters
ratings (pandas.DataFrame) – The rating or interaction data. Passed changed to the predictor and candidate selector.
args – Additional arguments for the predictor to use in its training process.
kwargs – 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 (arraylike) – The set of valid candidate items; if
None
, a default set will be used. For many algorithms, this is theirCandidateSelector
.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 ascore
column. Return type

predict
(pairs, ratings=None)¶ Compute predictions for useritem pairs. This method is designed to be compatible with the general SciKit paradigm; applications typically want to use
predict_for_user()
. Parameters
pairs (pandas.DataFrame) – The useritem pairs, as
user
anditem
columns.ratings (pandas.DataFrame) – useritem rating data to replace memorized data.
 Returns
The predicted scores for each useritem pair.
 Return type

predict_for_user
(user, items, ratings=None)¶ Compute predictions for a user and items.
 Parameters
user – the user ID
items (arraylike) – 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
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.CandidateSelector
CandidateSelector
that selects items a user has not rated as candidates. When this selector is fit, it memorizes the rated items.
items_
¶ All known items.
 Type

users_
¶ All known users.
 Type

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 arraylike) – 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 arraylike 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.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 (arraylike) – 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

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.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 (arraylike) – 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
