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: 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 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: lenskit.algorithms.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