Algorithm Interfaces

LKPY’s batch routines and utility support for managing algorithms expect algorithms to implement consistent interfaces. This page describes those interfaces.

The interfaces are realized as abstract base classes with the Python abc module. Implementations must be registered with their interfaces, either by subclassing the interface or by calling abc.ABCMeta.register().

Base Algorithm

Algorithms follow the SciKit fit-predict paradigm for estimators, except they know natively how to work with Pandas objects.

The Algorithm interface defines common methods.

class lenskit.algorithms.Algorithm

Base class for LensKit algorithms. These algorithms follow the SciKit design pattern for estimators.

fit(ratings, *args, **kwargs)

Train a model using the specified ratings (or similar) data.

Parameters:
  • ratings (pandas.DataFrame) – The ratings data.
  • args – Additional training data the algorithm may require.
  • kwargs – Additional training data the algorithm may require.
Returns:

The algorithm object.
get_params(deep=True)

Get the parameters for this algorithm (as in scikit-learn). Algorithm parameters should match constructor argument names.

The default implementation returns all attributes that match a constructor parameter name. It should be compatible with scikit.base.BaseEstimator.get_params() method so that LensKit alogrithms can be cloned with scikit.base.clone() as well as lenskit.util.clone().

Returns:the algorithm parameters.
Return type:dict
load(file)

Load a fit algorithm from a file. The default implementation unpickles the object and transplants its parameters and model into this object.

Parameters:file (path-like) – the file to load.
save(file)

Save a fit algorithm to a file. The default implementation pickles the object.

Parameters:file (path-like) – the file to save.

Recommendation

The Recommender interface provides an interface to generating recommendations. Not all algorithms implement it; call Recommender.adapt() on an algorithm to get a recommender for any algorithm that at least implements Predictor. For example:

pred = Bias(damping=5)
rec = Recommender.adapt(pred)

Note

We are rethinking the ergonomics of this interface, and it may change in LensKit 0.6. We expect keep compatibility in the lenskit.batch.recommend() API, though.

class lenskit.algorithms.Recommender

Recommends lists of items for users.

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

Rating Prediction

class lenskit.algorithms.Predictor

Predicts user ratings of items. Predictions are really estimates of the user’s like or dislike, and the Predictor interface makes no guarantees about their scale or granularity.

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