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 = item_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, uses UnratedItemCandidateSelector.

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 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

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 to UnratedItemsCandidateSelector.

  • 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 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