LensKit ¶

Isolated Training¶

This function isn’t a batch function per se, as it doesn’t perform multiple operations, but it is primarily useful with batch operations. The train_isolated() function trains an algorithm in a subprocess, so all temporary resources are released by virtue of the training process exiting. It returns a shared memory serialization of the trained model, which can be passed directly to recommend() or predict() in lieu of an algorithm object, to reduce the total memory consumption.

Example usage:

algo = BiasedMF(50)
algo = Recommender.adapt(algo)
algo = batch.train_isolated(algo, train_ratings)
preds = batch.predict(algo, test_ratings)

lenskit.batch.train_isolated(algo, ratings, *, file=None, **kwargs)¶

Train an algorithm in a subprocess to isolate the training process. This function spawns a subprocess (in the same way that LensKit’s multiprocessing support does), calls lenskit.algorithms.Algorithm.fit() on it, and serializes the result for shared-memory use.

Training the algorithm in a single-purpose subprocess makes sure that any training resources, such as TensorFlow sessions, are cleaned up by virtue of the process terminating when model training is completed. It can also reduce memory use, because the original trained model and the shared memory version are not in memory at the same time. While the batch functions use shared memory to reduce memory overhead for parallel processing, naive use of these functions will still have 2 copies of the model in memory, the shared one and the original, because the sharing process does not tear down the original model. Training in a subprocess solves this problem elegantly.

Parameters

algo (lenskit.algorithms.Algorithm) – The algorithm to train.
ratings (pandas.DataFrame) – The rating data.
file (str or pathlib.Path or None) – The file in which to save the trained model. If None, uses a default file path or shared memory.
kwargs (dict) – Additional named parameters to lenskit.algorithms.Algorithm.fit().

Returns

The saved model object. This is the owner, so it needs to be closed when finished to free resources.

Return type

lenskit.sharing.PersistedObject

Scripting Evaluation¶

The MultiEval class is useful to build scripts that evaluate multiple algorithms or algorithm variants, simultaneously, across multiple data sets. It can extract parameters from algorithms and include them in the output, useful for hyperparameter search.

For example:

from lenskit.batch import MultiEval
from lenskit.crossfold import partition_users, SampleN
from lenskit.algorithms import basic, als
from lenskit.datasets import MovieLens
from lenskit import topn
import pandas as pd

ml = MovieLens('ml-latest-small')

eval = MultiEval('my-eval', recommend=20)
eval.add_datasets(partition_users(ml.ratings, 5, SampleN(5)), name='ML-Small')
eval.add_algorithms(basic.Popular(), name='Pop')
eval.add_algorithms([als.BiasedMF(f) for f in [20, 30, 40, 50]],
                    attrs=['features'], name='ALS')
eval.run()

The my-eval/runs.csv file will then contain the results of running these algorithms on this data set. A more complete example is available in the MultiEval notebook.

class lenskit.batch.MultiEval(path, *, predict=True, recommend=100, candidates=None, save_models=False, eval_n_jobs=None, combine=True, **kwargs)¶

Bases: object

A runner for carrying out multiple evaluations, such as parameter sweeps.

Parameters

path (str or pathlib.Path) – the working directory for this evaluation. It will be created if it does not exist.
predict (bool) – whether to generate rating predictions.
recommend (int) – the number of recommendations to generate per user. Any false-y value (None, False, 0) will disable top-n. The literal value True will generate recommendation lists of unlimited size.
candidates (function) – the default candidate set generator for recommendations. It should take the training data and return a candidate generator, itself a function mapping user IDs to candidate sets. Pass None to use the default candidate set configured for each algorithm (recommended).
save_models (bool or str) – save individual estimated models to disk. If True, models are pickled to .pkl files; if 'gzip', they are pickled to gzip-compressed .pkl.gz files.
eval_n_jobs (int or None) – Value to pass to the n_jobs parameter in lenskit.batch.predict() and lenskit.batch.recommend().
combine (bool) – whether to combine output; if False, output will be left in separate files, if True, it will be in a single set of files (runs, recommendations, and predictions).

add_algorithms(algos, attrs=[], **kwargs)¶

Add one or more algorithms to the run.

Parameters

algos (algorithm or list) – the algorithm(s) to add.
attrs (list of str) – a list of attributes to extract from the algorithm objects and include in the run descriptions.
kwargs – additional attributes to include in the run descriptions.

add_datasets(data, name=None, candidates=None, **kwargs)¶

Add one or more datasets to the run.

Parameters

data –
The input data set(s) to run. Can be one of the following:
- A tuple of (train, test) data.
- An iterable of (train, test) pairs, in which case the iterable is not consumed until it is needed.
- A function yielding either of the above, to defer data load until it is needed.
Data can be either data frames or paths; paths are loaded after detection using util.read_df_detect().
kwargs – additional attributes pertaining to these data sets.

persist_data()¶: Persist the data for an experiment, replacing in-memory data sets with file names. Once this has been called, the sweep can be pickled.

run_count()¶: Get the number of runs in this evaluation.

run(runs=None, *, progress=None)¶

Run the evaluation.

Parameters

runs (int or set-like) – If provided, a specific set of runs to run. Useful for splitting an experiment into individual runs. This is a set of 1-based run IDs, not 0-based indexes.
progress – A tqdm.tqdm()-compatible progress function.

collect_results()¶: Collect the results from non-combined runs into combined output files.

Evaluating Recommender Output¶

LensKit’s evaluation support is based on post-processing the output of recommenders and predictors. The batch utilities provide support for generating these outputs.

We generally recommend using Jupyter notebooks for evaluation.

Prediction Accuracy Metrics¶

The lenskit.metrics.predict module contains prediction accuracy metrics. These are intended to be used as a part of a Pandas split-apply-combine operation on a data frame that contains both predictions and ratings; for convenience, the lenskit.batch.predict() function will include ratings in the prediction frame when its input user-item pairs contains ratings. So you can perform the following to compute per-user RMSE over some predictions:

from lenskit.datasets import MovieLens
from lenskit.algorithms.basic import Bias
from lenskit.batch import predict
from lenskit.metrics.predict import rmse
ratings = MovieLens('ml-small').ratings.sample(frac=10
test = ratings.iloc[:1000]
train = ratings.iloc[1000:]
algo = Bias()
algo.fit(train)
preds = predict(algo, pairs)
user_rmse = preds.groupby('user').apply(lambda df: rmse(df.prediction, df.rating))
user_rmse.mean()

Metric Functions¶

Prediction metric functions take two series, predictions and truth.

lenskit.metrics.predict.rmse(predictions, truth, missing='error')¶

Compute RMSE (root mean squared error).

Parameters

predictions (pandas.Series) – the predictions
truth (pandas.Series) – the ground truth ratings from data
missing (string) – how to handle predictions without truth. Can be one of 'error' or 'ignore'.

Returns

the root mean squared approximation error

Return type

double

lenskit.metrics.predict.mae(predictions, truth, missing='error')¶

Compute MAE (mean absolute error).

Parameters

predictions (pandas.Series) – the predictions
truth (pandas.Series) – the ground truth ratings from data
missing (string) – how to handle predictions without truth. Can be one of 'error' or 'ignore'.

Returns

the mean absolute approximation error

Return type

double

Working with Missing Data¶

LensKit rating predictors do not report predictions when their core model is unable to predict. For example, a nearest-neighbor recommender will not score an item if it cannot find any suitable neighbors. Following the Pandas convention, these items are given a score of NaN (when Pandas implements better missing data handling, it will use that, so use pandas.Series.isna()/pandas.Series.notna(), not the isnan versions.

However, this causes problems when computing predictive accuracy: recommenders are not being tested on the same set of items. If a recommender only scores the easy items, for example, it could do much better than a recommender that is willing to attempt more difficult items.

A good solution to this is to use a fallback predictor so that every item has a prediction. In LensKit, lenskit.algorithms.basic.Fallback implements this functionality; it wraps a sequence of recommenders, and for each item, uses the first one that generates a score.

You set it up like this:

cf = ItemItem(20)
base = Bias(damping=5)
algo = Fallback(cf, base)

Top-N Evaluation¶

LensKit’s support for top-N evaluation is in two parts, because there are some subtle complexities that make it more dfficult to get the right data in the right place for computing metrics correctly.

Top-N Analysis¶

The lenskit.topn module contains the utilities for carrying out top-N analysis, in conjucntion with lenskit.batch.recommend() and its wrapper in lenskit.batch.MultiEval.

The entry point to this is RecListAnalysis. This class encapsulates an analysis with one or more metrics, and can apply it to data frames of recommendations. An analysis requires two data frames: the recommendation frame contains the recommendations themselves, and the truth frame contains the ground truth data for the users. The analysis is flexible with regards to the columns that identify individual recommendation lists; usually these will consist of a user ID, data set identifier, and algorithm identifier(s), but the analysis is configurable and its defaults make minimal assumptions. The recommendation frame does need an item column with the recommended item IDs, and it should be in order within a single recommendation list.

The truth frame should contain (a subset of) the columns identifying recommendation lists, along with item and, if available, rating (if no rating is provided, the metrics that need a rating value will assume a rating of 1 for every item present). It can contain other items that custom metrics may find useful as well.

For example, a recommendation frame may contain:

DataSet
Partition
Algorithm
user
item
rank
score

And the truth frame:

DataSet
user
item
rating

The analysis will use this truth as the relevant item data for measuring the accuracy of the roecommendation lists. Recommendations will be matched to test ratings by data set, user, and item, using RecListAnalysis defaults.

class lenskit.topn.RecListAnalysis(group_cols=None, n_jobs=None)¶

Bases: object

Compute one or more top-N metrics over recommendation lists.

This method groups the recommendations by the specified columns, and computes the metric over each group. The default set of grouping columns is all columns except the following:

item
rank
score
rating

The truth frame, truth, is expected to match over (a subset of) the grouping columns, and contain at least an item column. If it also contains a rating column, that is used as the users’ rating for metrics that require it; otherwise, a rating value of 1 is assumed.

Warning

Currently, RecListAnalysis will silently drop users who received no recommendations. We are working on an ergonomic API for fixing this problem.

Parameters: group_cols (list) – The columns to group by, or None to use the default.

add_metric(metric, *, name=None, **kwargs)¶

Add a metric to the analysis.

A metric is a function of two arguments: the a single group of the recommendation frame, and the corresponding truth frame. The truth frame will be indexed by item ID. The recommendation frame will be in the order in the data. Many metrics are defined in lenskit.metrics.topn; they are re-exported from lenskit.topn for convenience.

Parameters

metric – The metric to compute.
name – The name to assign the metric. If not provided, the function name is used.
**kwargs – Additional arguments to pass to the metric.

compute(recs, truth, *, include_missing=False)¶

Run the analysis. Neither data frame should be meaningfully indexed.

Parameters

recs (pandas.DataFrame) – A data frame of recommendations.
truth (pandas.DataFrame) – A data frame of ground truth (test) data.
include_missing (bool) – True to include users from truth missing from recs. Matches are done via group columns that appear in both recs and truth.

Returns

The results of the analysis.

Return type

Metrics¶

The lenskit.metrics.topn module contains metrics for evaluating top-N recommendation lists.

Classification Metrics¶

These metrics treat the recommendation list as a classification of relevant items.

lenskit.metrics.topn.precision(recs, truth)¶: Compute recommendation precision.

lenskit.metrics.topn.recall(recs, truth)¶: Compute recommendation recall.

Ranked List Metrics¶

These metrics treat the recommendation list as a ranked list of items that may or may not be relevant.

lenskit.metrics.topn.recip_rank(recs, truth)¶

Compute the reciprocal rank of the first relevant item in a list of recommendations.

If no elements are relevant, the reciprocal rank is 0.

Utility Metrics¶

The NDCG function estimates a utility score for a ranked list of recommendations.

lenskit.metrics.topn.ndcg(recs, truth, discount=<ufunc 'log2'>)¶

Compute the normalized discounted cumulative gain.

Discounted cumultative gain is computed as:

\[\begin{align*} \mathrm{DCG}(L,u) & = \sum_{i=1}^{|L|} \frac{r_{ui}}{d(i)} \end{align*}\]

This is then normalized as follows:

\[\begin{align*} \mathrm{nDCG}(L, u) & = \frac{\mathrm{DCG}(L,u)}{\mathrm{DCG}(L_{\mathrm{ideal}}, u)} \end{align*}\]

Parameters

recs – The recommendation list.
truth – The user’s test data.
discount (ufunc) – The rank discount function. Each item’s score will be divided the discount of its rank, if the discount is greater than 1.

We also expose the internal DCG computation directly.

lenskit.metrics.topn._dcg(scores, discount=<ufunc 'log2'>)¶

Compute the Discounted Cumulative Gain of a series of recommended items with rating scores. These should be relevance scores; they can be \({0,1}\) for binary relevance data.

This is not a true top-N metric, but is a utility function for other metrics.

Parameters

scores (array-like) – The utility scores of a list of recommendations, in recommendation order.
discount (ufunc) – the rank discount function. Each item’s score will be divided the discount of its rank, if the discount is greater than 1.

Returns

the DCG of the scored items.

Return type

double

Loading Outputs¶

We typically store the output of recommendation runs in LensKit experiments in CSV or Parquet files. The lenskit.batch.MultiEval class arranges to run a set of algorithms over a set of data sets, and store the results in a collection of Parquet files in a specified output directory.

There are several files:

runs.parquet: The _runs_, algorithm-dataset combinations. This file contains the names & any associated properties of each algorithm and data set run, such as a feature count.
recommendations.parquet: The recommendations, with columns RunId, user, rank, item, and rating.
predictions.parquet: The rating predictions, if the test data includes ratings.

For example, if you want to examine nDCG by neighborhood count for a set of runs on a single data set, you can do:

import pandas as pd
from lenskit.metrics import topn as lm

runs = pd.read_parquet('eval-dir/runs.parquet')
recs = pd.read_parquet('eval-dir/recs.parquet')
meta = runs.loc[:, ['RunId', 'max_neighbors']]

# compute each user's nDCG
user_ndcg = recs.groupby(['RunId', 'user']).rating.apply(lm.ndcg)
user_ndcg = user_ndcg.reset_index(name='nDCG')
# combine with metadata for feature count
user_ndcg = pd.merge(user_ndcg, meta)
# group and aggregate
nbr_ndcg = user_ndcg.groupby('max_neighbors').nDCG.mean()
nbr_ndcg.plot()

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().

Serialization¶

Like SciKit models, all LensKit algorithms are pickleable, and this is how we recommend saving models to disk for later use. This can be done with pickle, but we recommend using binpickle for more automatically-optimized storage. For example, to save a fully-configured ALS module with fairly aggressive ZSTD compression:

algo = Recommender.adapt(ImplicitMF(50))
algo.fit(ratings)
binpickle.dump(algo, binpickle.codecs.Blosc('zstd', 9))

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.Algorithm¶

Bases: object

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

Canonical: lenskit.Algorithm

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

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

class algorithms.Algorithm¶: This is an alias of lenskit.Algorithm.

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)

If the algorithm already implements Recommender, it is returned, so it is safe to always call Recommender.adapt() before fitting an algorithm you will need for top-N recommendations to mak sure it is suitable.

class lenskit.Recommender¶

Bases: lenskit.algorithms.Algorithm

Recommends lists of items for users.

abstract 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

classmethod adapt(algo)¶

Ensure that an algorithm is a Recommender. If it is not a recommender, it is wrapped in a lenskit.basic.TopN with a default candidate selector.

Note

Since 0.6.0, since algorithms are fit directly, you should call this method before calling Algorithm.fit(), unless you will always be passing explicit candidate sets to recommend().

Parameters: algo (Predictor) – the underlying rating predictor.

class algorithms.Recommender¶: This is an alias of lenskit.Recommender.

Candidate Selection¶

Some recommenders use a candidate selector to identify possible items to recommend. These are also treated as algorithms, mainly so that they can memorize users’ prior ratings to exclude them from recommendation.

class lenskit.CandidateSelector¶

Bases: lenskit.algorithms.Algorithm

Select candidates for recommendation for a user, possibly with some additional ratings.

UnratedItemCandidateSelector is the default and most common implementation of this interface.

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

static rated_items(ratings)¶: Utility function for converting a series or array into an array of item IDs. Useful in implementations of candidates().

class algorithms.CandidateSelector¶: This is an alias of lenskit.CandidateSelector.

Rating Prediction¶

The Predictor class impelemnts ‘rating prediction’, as well as any other personalized item scoring that may not be predictions of actual ratings. Most algorithms actually implement this interface.

class lenskit.Predictor¶

Bases: lenskit.algorithms.Algorithm

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

pairs (pandas.DataFrame) – The user-item pairs, as user and item columns.
ratings (pandas.DataFrame) – user-item rating data to replace memorized data.

Returns

The predicted scores for each user-item pair.

Return type

abstract 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 algorithms.Predictor¶: This is an alias of lenskit.Predictor.

Algorithm Summary¶

LKPY provides general algorithmic concepts, along with implementations of several algorithms. These algorithm interfaces are based on the SciKit design patterns [SKAPI], adapted for Pandas-based data structures.

All algorithms implement the standard interfaces.

Basic Algorithms¶

`basic.Bias`([items, users, damping])	A user-item bias rating prediction algorithm.
`basic.Popular`([selector])	Recommend the most popular items.
`basic.TopN`(predictor[, selector])	Basic recommender that implements top-N recommendation using a predictor.
`basic.Fallback`(algorithms, *others)	The Fallback algorithm predicts with its first component, uses the second to fill in missing values, and so forth.
`basic.UnratedItemCandidateSelector`()	`CandidateSelector` that selects items a user has not rated as candidates.
`basic.Memorized`(scores)	The memorized algorithm memorizes socres provided at construction time.

k-NN Algorithms¶

`user_knn.UserUser`(nnbrs[, min_nbrs, …])	User-user nearest-neighbor collaborative filtering with ratings.
`item_knn.ItemItem`(nnbrs[, min_nbrs, …])	Item-item nearest-neighbor collaborative filtering with ratings.

Matrix Factorization¶

`als.BiasedMF`(features, *[, iterations, reg, …])	Biased matrix factorization trained with alternating least squares [ZWSP2008].
`als.ImplicitMF`(features, *[, iterations, …])	Implicit matrix factorization trained with alternating least squares [HKV2008].
`funksvd.FunkSVD`(features[, iterations, …])	Algorithm class implementing FunkSVD matrix factorization.

TensorFlow¶

`tf.BiasedMF`([features, bias, damping, …])	Biased matrix factorization model for explicit feedback, optimized with TensorFlow.
`tf.IntegratedBiasMF`([features, epochs, …])	Biased matrix factorization model for explicit feedback, optimizing both bias and embeddings with TensorFlow.
`tf.BPR`([features, epochs, batch_size, reg, …])	Bayesian Personalized Ranking with matrix factorization, optimized with TensorFlow.

External Library Wrappers¶

`implicit.BPR`(args, *kwargs)	LensKit interface to `implicit.bpr`.
`implicit.ALS`(args, *kwargs)	LensKit interface to `implicit.als`.
`hpf.HPF`(features, **kwargs)	Hierarchical Poisson factorization, provided by hpfrec.

References¶

SKAPI: Lars Buitinck, Gilles Louppe, Mathieu Blondel, Fabian Pedregosa, Andreas Mueller, Olivier Grisel, Vlad Niculae, Peter Prettenhofer, Alexandre Gramfort, Jaques Grobler, Robert Layton, Jake Vanderplas, Arnaud Joly, Brian Holt, and Gaël Varoquaux. 2013. API design for machine learning software: experiences from the scikit-learn project. arXiv:1309.0238 [cs.LG].

Basic and Utility Algorithms¶

The lenskit.algorithms.basic module contains baseline and utility algorithms for nonpersonalized recommendation and testing.

Personalized Mean Rating Prediction¶

class lenskit.algorithms.basic.Bias(items=True, users=True, damping=0.0)¶

A user-item bias rating prediction algorithm. This implements the following predictor algorithm:

\[s(u,i) = \mu + b_i + b_u\]

where \(\mu\) is the global mean rating, \(b_i\) is item bias, and \(b_u\) is the user bias. With the provided damping values \(\beta_{\mathrm{u}}\) and \(\beta_{\mathrm{i}}\), they are computed as follows:

\[\begin{align*} \mu & = \frac{\sum_{r_{ui} \in R} r_{ui}}{|R|} & b_i & = \frac{\sum_{r_{ui} \in R_i} (r_{ui} - \mu)}{|R_i| + \beta_{\mathrm{i}}} & b_u & = \frac{\sum_{r_{ui} \in R_u} (r_{ui} - \mu - b_i)}{|R_u| + \beta_{\mathrm{u}}} \end{align*}\]

The damping values can be interpreted as the number of default (mean) ratings to assume a priori for each user or item, damping low-information users and items towards a mean instead of permitting them to take on extreme values based on few ratings.

Parameters

items – whether to compute item biases
users – whether to compute user biases
damping (number or tuple) – Bayesian damping to apply to computed biases. Either a number, to damp both user and item biases the same amount, or a (user,item) tuple providing separate damping values.

mean_: double¶: The global mean rating.

item_offsets_: pandas.Series¶: The item offsets (\(b_i\) values)

user_offsets_: pandas.Series¶: The item offsets (\(b_u\) values)

fit(ratings, **kwargs)¶

Train the bias model on some rating data.

Parameters: ratings (DataFrame) – a data frame of ratings. Must have at least user, item, and rating columns.
Returns: the fit bias object.
Return type: Bias

transform(ratings, *, indexes=False)¶

Transform ratings by removing the bias term.

Parameters

ratings (pandas.DataFrame) – The ratings to transform. Must contain at least user, item, and rating columns.
indexes (bool) – if True, the resulting frame will include uidx and iidx columns containing the 0-based user and item indexes for each rating.

Returns

A data frame with rating transformed by subtracting user-item bias prediction.

Return type

inverse_transform(ratings)¶: Transform ratings by removing the bias term.

fit_transform(ratings, **kwargs)¶: Fit with ratings and return the training data transformed.

predict_for_user(user, items, ratings=None)¶

Compute predictions for a user and items. Unknown users and items are assumed to have zero bias.

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, will be used to recompute the user’s bias at prediction time.

Returns

scores for the items, indexed by item id.

Return type

property user_index¶: Get the user index from this (fit) bias.

property item_index¶: Get the item index from this (fit) bias.

Most Popular Item Recommendation¶

The Popular algorithm implements most-popular-item recommendation.

class lenskit.algorithms.basic.Popular(selector=None)¶

Bases: lenskit.algorithms.Recommender

Recommend the most popular items.

Parameters: selector (CandidateSelector) – The candidate selector to use. If None, uses a new UnratedItemCandidateSelector.

item_pop_: pandas.Series¶: Item rating counts (popularity)

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

Random Item Recommendation¶

The Random algorithm implements random-item recommendation.

class lenskit.algorithms.basic.Random(selector=None, rng_spec=None)¶

Bases: lenskit.algorithms.Recommender

A random-item recommender.

selector: CandidateSelector¶: Selects candidate items for recommendation. Default is UnratedItemCandidateSelector.

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

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.basic.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, the top-N recommender does not need to be fit.

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.
kwargs (args,) – 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

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

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

CandidateSelector that selects items a user has not rated as candidates. When this selector is fit, it memorizes the rated items.

items_: pandas.Index¶: All known items.

users_: pandas.Index¶: All known users.

user_items_: CSR¶: Items rated by each known user, as positions in the items index.

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

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

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

k-NN Collaborative Filtering¶

LKPY provides user- and item-based classical k-NN collaborative Filtering implementations. These lightly-configurable implementations are intended to capture the behavior of the Java-based LensKit implementations to provide a good upgrade path and enable basic experiments out of the box.

Item-based k-NN¶

class lenskit.algorithms.item_knn.ItemItem(nnbrs, min_nbrs=1, min_sim=1e-06, save_nbrs=None, center=True, aggregate='weighted-average')¶

Item-item nearest-neighbor collaborative filtering with ratings. This item-item implementation is not terribly configurable; it hard-codes design decisions found to work well in the previous Java-based LensKit code.

Parameters

nnbrs (int) – the maximum number of neighbors for scoring each item (None for unlimited)
min_nbrs (int) – the minimum number of neighbors for scoring each item
min_sim (double) – minimum similarity threshold for considering a neighbor
save_nbrs (double) – the number of neighbors to save per item in the trained model (None for unlimited)
center (bool) – whether to normalize (mean-center) rating vectors. Turn this off when working with unary data and other data types that don’t respond well to centering.
aggregate – the type of aggregation to do. Can be weighted-average or sum.

item_index_: pandas.Index¶: the index of item IDs.

item_means_: numpy.ndarray¶: the mean rating for each known item.

item_counts_: numpy.ndarray¶: the number of saved neighbors for each item.

sim_matrix_: matrix.CSR¶: the similarity matrix.

user_index_: pandas.Index¶: the index of known user IDs for the rating matrix.

rating_matrix_: matrix.CSR¶: the user-item rating matrix for looking up users’ ratings.

fit(ratings, **kwargs)¶

Train a model.

The model-training process depends on save_nbrs and min_sim, but not on other algorithm parameters.

Parameters: ratings (pandas.DataFrame) – (user,item,rating) data for computing item similarities.

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

User-based k-NN¶

class lenskit.algorithms.user_knn.UserUser(nnbrs, min_nbrs=1, min_sim=0, center=True, aggregate='weighted-average')¶

User-user nearest-neighbor collaborative filtering with ratings. This user-user implementation is not terribly configurable; it hard-codes design decisions found to work well in the previous Java-based LensKit code.

Parameters

nnbrs (int) – the maximum number of neighbors for scoring each item (None for unlimited)
min_nbrs (int) – the minimum number of neighbors for scoring each item
min_sim (double) – minimum similarity threshold for considering a neighbor
center (bool) – whether to normalize (mean-center) rating vectors. Turn this off when working with unary data and other data types that don’t respond well to centering.
aggregate – the type of aggregation to do. Can be weighted-average or sum.

user_index_: pandas.Index¶: User index.

item_index_: pandas.Index¶: Item index.

user_means_: numpy.ndarray¶: User mean ratings.

rating_matrix_: matrix.CSR¶: Normalized user-item rating matrix.

transpose_matrix_: matrix.CSR¶: Transposed un-normalized rating matrix.

fit(ratings, **kwargs)¶

“Train” a user-user CF model. This memorizes the rating data in a format that is usable for future computations.

Parameters: ratings (pandas.DataFrame) – (user, item, rating) data for collaborative filtering.
Returns: a memorized model for efficient user-based CF computation.
Return type: UUModel

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, will be used to recompute the user’s bias at prediction time.

Returns

scores for the items, indexed by item id.

Return type

Classic Matrix Factorization¶

LKPY provides classical matrix factorization implementations.

Common Support
Alternating Least Squares
SciKit SVD
FunkSVD

Common Support ¶

The mf_common module contains common support code for matrix factorization algorithms. These classes, MFPredictor and BiasMFPredictor, define the parameters that are estimated during the Algorithm.fit() process on common matrix factorization algorithms.

class lenskit.algorithms.mf_common.MFPredictor¶

Common predictor for matrix factorization.

user_index_: pandas.Index¶: Users in the model (length=:math:m).

item_index_: pandas.Index¶: Items in the model (length=:math:n).

user_features_: numpy.ndarray¶: The \(m \times k\) user-feature matrix.

item_features_: numpy.ndarray¶: The \(n \times k\) item-feature matrix.

property n_features¶: The number of features.

property n_users¶: The number of users.

property n_items¶: The number of items.

lookup_user(user)¶

Look up the index for a user.

Parameters: user – the user ID to look up
Returns: the user index.
Return type: int

lookup_items(items)¶

Look up the indices for a set of items.

Parameters: items (array-like) – the item IDs to look up.
Returns: the item indices. Unknown items will have negative indices.
Return type: numpy.ndarray

score(user, items)¶

Score a set of items for a user. User and item parameters must be indices into the matrices.

Parameters

user (int) – the user index
items (array-like of int) – the item indices
raw (bool) – if True, do return raw scores without biases added back.

Returns

the scores for the items.

Return type

numpy.ndarray

class lenskit.algorithms.mf_common.BiasMFPredictor¶

Bases: lenskit.algorithms.mf_common.MFPredictor

Common model for biased matrix factorization.

user_index_: pandas.Index¶: Users in the model (length=:math:m).

item_index_: pandas.Index¶: Items in the model (length=:math:n).

global_bias_: double¶: The global bias term.

user_bias_: numpy.ndarray¶: The user bias terms.

item_bias_: numpy.ndarray¶: The item bias terms.

user_features_: numpy.ndarray¶: The \(m \times k\) user-feature matrix.

item_features_: numpy.ndarray¶: The \(n \times k\) item-feature matrix.

score(user, items, raw=False)¶

Score a set of items for a user. User and item parameters must be indices into the matrices.

Parameters

user (int) – the user index
items (array-like of int) – the item indices
raw (bool) – if True, do return raw scores without biases added back.

Returns

the scores for the items.

Return type

numpy.ndarray

Alternating Least Squares ¶

LensKit provides alternating least squares implementations of matrix factorization suitable for explicit feedback data. These implementations are parallelized with Numba, and perform best with the MKL from Conda.

class lenskit.algorithms.als.BiasedMF(features, *, iterations=20, reg=0.1, damping=5, bias=True, method='cd', rng_spec=None, progress=None)¶

Bases: lenskit.algorithms.mf_common.BiasMFPredictor

Biased matrix factorization trained with alternating least squares [ZWSP2008]. This is a prediction-oriented algorithm suitable for explicit feedback data.

It provides two solvers for the optimization step (the method parameter):

'cd' (the default): Coordinate descent [TPT2011], adapted for a separately-trained bias model and to use weighted regularization as in the original ALS paper [ZWSP2008].
'lu': A direct implementation of the original ALS concept [ZWSP2008] using LU-decomposition to solve for the optimized matrices.

See the base class BiasMFPredictor for documentation on the estimated parameters you can extract from a trained model.

ZWSP2008(1,2,3): Yunhong Zhou, Dennis Wilkinson, Robert Schreiber, and Rong Pan. 2008. Large-Scale Parallel Collaborative Filtering for the Netflix Prize. In +Algorithmic Aspects in Information and Management_, LNCS 5034, 337–348. DOI 10.1007/978-3-540-68880-8_32.
TPT2011: Gábor Takács, István Pilászy, and Domonkos Tikk. 2011. Applications of the Conjugate Gradient Method for Implicit Feedback Collaborative Filtering.

Parameters

features (int) – the number of features to train
iterations (int) – the number of iterations to train
reg (float) – the regularization factor; can also be a tuple (ureg, ireg) to specify separate user and item regularization terms.
damping (float) – damping factor for the underlying mean
bias (bool or Bias) – the bias model. If True, fits a Bias with damping damping.
method (str) – the solver to use (see above).
rng_spec – Random number generator or state (see lenskit.util.random.rng()).
progress – a tqdm.tqdm()-compatible progress bar function

fit(ratings, **kwargs)¶

Run ALS to train a model.

Parameters: ratings – the ratings data frame.
Returns: The algorithm (for chaining).

fit_iters(ratings, **kwargs)¶

Run ALS to train a model, returning each iteration as a generator.

Parameters: ratings – the ratings data frame.
Returns: The algorithm (for chaining).

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.als.ImplicitMF(features, *, iterations=20, reg=0.1, weight=40, method='cg', rng_spec=None, progress=None)¶

Bases: lenskit.algorithms.mf_common.MFPredictor

Implicit matrix factorization trained with alternating least squares [HKV2008]. This algorithm outputs ‘predictions’, but they are not on a meaningful scale. If its input data contains rating values, these will be used as the ‘confidence’ values; otherwise, confidence will be 1 for every rated item.

'cd' (the default): Conjugate gradient method [TPT2011].
'lu': A direct implementation of the original implicit-feedback ALS concept [HKV2008] using LU-decomposition to solve for the optimized matrices.

See the base class MFPredictor for documentation on the estimated parameters you can extract from a trained model.

HKV2008(1,2,3): Y. Hu, Y. Koren, and C. Volinsky. 2008. Collaborative Filtering for Implicit Feedback Datasets. In _Proceedings of the 2008 Eighth IEEE International Conference on Data Mining_, 263–272. DOI 10.1109/ICDM.2008.22
TPT2011: Gábor Takács, István Pilászy, and Domonkos Tikk. 2011. Applications of the Conjugate Gradient Method for Implicit Feedback Collaborative Filtering.

Parameters

features (int) – the number of features to train
iterations (int) – the number of iterations to train
reg (double) – the regularization factor
weight (double) – the scaling weight for positive samples (\(\alpha\) in [HKV2008]).
rng_spec – Random number generator or state (see lenskit.util.random.rng()).
progress – a tqdm.tqdm()-compatible progress bar function

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

SciKit SVD ¶

This code implements a traditional SVD using scikit-learn. It requires scikit-learn to be installed in order to function.

class lenskit.algorithms.svd.BiasedSVD(features, *, damping=5, bias=True, algorithm='randomized')¶

Biased matrix factorization for implicit feedback using SciKit-Learn’s SVD solver (sklearn.decomposition.TruncatedSVD). It operates by first computing the bias, then computing the SVD of the bias residuals.

You’ll generally want one of the iterative SVD implementations such as lennskit.algorithms.als.BiasedMF; this is here primarily as an example and for cases where you want to evaluate a pure SVD implementation.

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

FunkSVD ¶

FunkSVD is an SVD-like matrix factorization that uses stochastic gradient descent, configured much like coordinate descent, to train the user-feature and item-feature matrices. We generally don’t recommend using it in new applications or experiments; the ALS-based algorithms are less sensitive to hyperparameters, and the TensorFlow algorithms provide more optimized gradient descent training of the same prediction model.

class lenskit.algorithms.funksvd.FunkSVD(features, iterations=100, *, lrate=0.001, reg=0.015, damping=5, range=None, bias=True, random_state=None)¶

Bases: lenskit.algorithms.mf_common.BiasMFPredictor

Algorithm class implementing FunkSVD matrix factorization. FunkSVD is a regularized biased matrix factorization technique trained with featurewise stochastic gradient descent.

See the base class BiasMFPredictor for documentation on the estimated parameters you can extract from a trained model.

Parameters

features (int) – the number of features to train
iterations (int) – the number of iterations to train each feature
lrate (double) – the learning rate
reg (double) – the regularization factor
damping (double) – damping factor for the underlying mean
bias (Predictor) – the underlying bias model to fit. If True, then a basic.Bias model is fit with damping.
range (tuple) – the (min, max) rating values to clamp ratings, or None to leave predictions unclamped.
random_state – The random state for shuffling the data prior to training.

fit(ratings, **kwargs)¶

Train a FunkSVD model.

Parameters: ratings – the ratings data frame.

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

TensorFlow Algorithms¶

LKPY provides several algorithm implementations, particularly matrix factorization, using TensorFlow. These algorithms serve two purposes:

Provide classic algorithms ready to use for recommendation or as baselines for new techniques.
Demonstrate how to connect TensorFlow to LensKit for use in your own experiments.

Biased MF¶

These models implement the standard biased matrix factorization model, like lenskit.algorithms.als.BiasedMF, but learn the model parameters using TensorFlow’s gradient descent instead of the alternating least squares algorithm.

Bias-Based¶

class lenskit.algorithms.tf.BiasedMF(features=50, *, bias=True, damping=5, epochs=5, batch_size=10000, reg=0.02, rng_spec=None)¶

Bases: lenskit.algorithms.mf_common.BiasMFPredictor

Biased matrix factorization model for explicit feedback, optimized with TensorFlow.

This is a basic TensorFlow implementation of the biased matrix factorization model for rating prediction:

\[s(i|u) = b + b_u + b_i + \vec{p}_u \cdot \vec{q_i}\]

User and item embedding matrices are regularized with \(L_2\) regularization, governed by a regularization term \(\lambda\). Regularizations for the user and item embeddings are then computed as follows:

\[\begin{split}\lambda_u = \lambda / |U| \\ \lambda_i = \lambda / |I| \\\end{split}\]

This rescaling allows the regularization term to be independent of the number of users and items.

Because the model is very simple, this algorithm works best with large batch sizes.

This implementation uses lenskit.algorithms.basic.Bias for computing the biases, and uses TensorFlow to fit a matrix factorization on the residuals. It then extracts the resulting matrices, and relies on BiasedMFPredictor to implement the prediction logic, like lenskit.algorithms.als.BiasedMF. Its code is suitable as an example of how to build a Keras/TensorFlow algorithm implementation for LensKit where TF is only used in the train stage.

A variety of resources informed the design, most notably this one.

Parameters

features (int) – The number of latent features to learn.
bias – The bias model to use.
damping – The bias damping, if bias is True.
epochs (int) – The number of epochs to train.
batch_size (int) – The Keras batch size.
reg (double) – The regularization term \(\lambda\) used to derive embedding vector regularizations.
rng_spec – The random number generator initialization.

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

Fully Integrated¶

class lenskit.algorithms.tf.IntegratedBiasMF(features=50, *, epochs=5, batch_size=10000, reg=0.02, bias_reg=0.2, rng_spec=None)¶

Biased matrix factorization model for explicit feedback, optimizing both bias and embeddings with TensorFlow.

This is a basic TensorFlow implementation of the biased matrix factorization model for rating prediction:

\[s(i|u) = b + b_u + b_i + \vec{p}_u \cdot \vec{q_i}\]

User and item embedding matrices are regularized with \(L_2\) regularization, governed by a regularization term \(\lambda\). Regularizations for the user and item embeddings are then computed as follows:

\[\begin{split}\lambda_u = \lambda / |U| \\ \lambda_i = \lambda / |I| \\\end{split}\]

This rescaling allows the regularization term to be independent of the number of users and items. The same rescaling applies to the bias regularization.

Because the model is very simple, this algorithm works best with large batch sizes.

This implementation uses TensorFlow to fit the entire model, including user/item biases and residuals, and uses TensorFlow to do the final predictions as well. Its code is suitable as an example of how to build a Keras/TensorFlow algorithm implementation for LensKit where TF used for the entire process.

A variety of resources informed the design, most notably this one and `Chin-chi Hsu's example code`_.

Parameters

features (int) – The number of latent features to learn.
epochs (int) – The number of epochs to train.
batch_size (int) – The Keras batch size.
reg (double) – The regularization term for the embedding vectors.
bias_reg (double) – The regularization term for the bias vectors.
rng_spec – The random number generator initialization.

model¶: The Keras model.

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

Bayesian Personalized Rating¶

class lenskit.algorithms.tf.BPR(features=50, *, epochs=5, batch_size=10000, reg=0.02, neg_count=1, rng_spec=None)¶

Bayesian Personalized Ranking with matrix factorization, optimized with TensorFlow.

This is a basic TensorFlow implementation of the BPR algorithm _[BPR].

User and item embedding matrices are regularized with \(L_2\) regularization, governed by a regularization term \(\lambda\). Regularizations for the user and item embeddings are then computed as follows:

\[\begin{split}\lambda_u = \lambda / |U| \\ \lambda_i = \lambda / |I| \\\end{split}\]

This rescaling allows the regularization term to be independent of the number of users and items.

Because the model is relatively simple, optimization works best with large batch sizes.

Parameters

features (int) – The number of latent features to learn.
epochs (int) – The number of epochs to train.
batch_size (int) – The Keras batch size. This is the number of positive examples to sample in each batch. If neg_count is greater than 1, the batch size will be similarly multipled.
reg (double) – The regularization term for the embedding vectors.
neg_count (int) – The number of negative examples to sample for each positive one.
rng_spec – The random number generator initialization.

model¶: The Keras model.

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

Hierarchical Poisson Factorization¶

This module provides a LensKit bridge to the hpfrec library implementing hierarchical Poisson factorization [GHB2013].

GHB2013: Prem Gopalan, Jake M. Hofman, and David M. Blei. 2013. Scalable Recommendation with Poisson Factorization. arXiv:1311.1704 [cs, stat] (November 2013). Retrieved February 9, 2017 from http://arxiv.org/abs/1311.1704.

class lenskit.algorithms.hpf.HPF(features, **kwargs)¶

Bases: lenskit.algorithms.mf_common.MFPredictor

Hierarchical Poisson factorization, provided by hpfrec.

Parameters

features (int) – the number of features
**kwargs – arguments passed to hpfrec.HPF.

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