Basic and Utility Algorithms
The lenskit.algorithms.basic
module contains baseline and utility algorithms
for nonpersonalized recommendation and testing.
Most Popular Item Recommendation
The PopScore
algorithm scores items by their populariy for enabling most-popular-item recommendation.
- class lenskit.algorithms.basic.PopScore(score_method='quantile')
Bases:
Predictor
Score items by their popularity. Use with
TopN
to get a most-popular-items recommender.- Parameters
score_type (str) –
The method for computing popularity scores. Can be one of the following:
'quantile'
(the default)'rank'
'count'
- item_pop_
Item popularity scores.
- 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.
- 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
- class lenskit.algorithms.basic.Popular(selector=None)
Bases:
Recommender
Recommend the most popular items.
The
PopScore
class is more flexible, and recommended for new code.- 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 (array-like) – 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 random-item recommendation.
- class lenskit.algorithms.basic.Random(selector=None, rng_spec=None)
Bases:
Recommender
A random-item 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 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 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
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:
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
- user_items_
Items rated by each known user, as positions in the
items
index.- Type
CSR
- 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:
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
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:
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