Ranking Methods#
The lenskit.algorithms.ranking
module contains various ranking methods:
algorithms that can use scores to produce ranks. This includes primary rankers, like
TopN
, and some re-rankers as well.
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.ranking.TopN(predictor, selector=None)#
Bases:
Recommender
,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 separately, the top-N recommender does not need to be fit. This can be useful when reusing a predictor in other contexts:pred = knn.ItemItem(20, feedback='implicit') select = UnratedItemCandidateSelector() topn = TopN(pred, select) pred.fit(ratings) select.fit(ratings) # topn.fit is unnecessary now
- 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 (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:
- 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:
pairs (pandas.DataFrame) – The user-item pairs, as
user
anditem
columns.ratings (pandas.DataFrame) – user-item rating data to replace memorized data.
- Returns:
The predicted scores for each user-item pair.
- Return type:
- 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:
Stochastic Recommenders#
The PlackettLuce
class implements a stochastic recommender. The underlying
relevance scores are kept the same, but the rankings are sampled from a Plackett-Luce
distribution instead using a deterministic top-N policy.
- class lenskit.algorithms.ranking.PlackettLuce(predictor, selector=None, *, rng_spec=None)#
Bases:
Recommender
Re-ranking algorithm that uses Plackett-Luce sampling on underlying scores. This uses the Gumbel trick [GWZE19] to efficiently simulate from a Plackett-Luce distribution.
- Parameters:
predictor (Predictor) – A predictor that can score candidate items.
selector (CandidateSelector) – The candidate selector. If
None
, defaults toUnratedItemsCandidateSelector
.rng_spec – A random number generator specification; see
derivable_rng()
.
- 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: