Welcome to Surprise’ documentation!¶

Getting Started¶

from surprise import SVD
from surprise import Dataset
from surprise import evaluate


# Load the movielens-100k dataset (download it if needed),
# and split it into 3 folds for cross-validation.
data = Dataset.load_builtin('ml-100k')
data.split(n_folds=3)

# We'll use the famous SVD algorithm.
algo = SVD()

# Evaluate performances of our algorithm on the dataset.
perf = evaluate(algo, data, measures=['RMSE', 'MAE'])

print(perf)

# path to dataset file
file_path = '/home/nico/.surprise_data/ml-100k/ml-100k/u.data'  # change this

# As we're loading a custom dataset, we need to define a reader. In the
# movielens-100k dataset, each line has the following format:
# 'user item rating timestamp', separated by '\t' characters.
reader = Reader(line_format='user item rating timestamp', sep='\t')

data = Dataset.load_from_file(file_path, reader=reader)
data.split(n_folds=5)

reader = Reader('ml-100k')

# path to dataset folder
files_dir = os.path.exapanduser('~/.surprise_data/ml-100k/ml-100k/')

# This time, we'll use the built-in reader.
reader = Reader('ml-100k')

# folds_files is a list of tuples containing file paths:
# [(u1.base, u1.test), (u2.base, u2.test), ... (u5.base, u5.test)]
train_file = files_dir + 'u%d.base'
test_file = files_dir + 'u%d.test'
folds_files = [(train_file % i, test_file % i) for i in (1, 2, 3, 4, 5)]

data = Dataset.load_from_folds(folds_files, reader=reader)

data = Dataset.load_builtin('ml-100k')
data.split(n_folds=3)

algo = BaselineOnly()

for trainset, testset in data.folds():

    # train and test algorithm.
    algo.train(trainset)
    predictions = algo.test(testset)

    # Compute and print Root Mean Squared Error
    rmse = accuracy.rmse(predictions, verbose=True)

data = Dataset.load_builtin('ml-100k')

# Retrieve the trainset.
trainset = data.build_full_trainset()

# Build an algorithm, and train it.
algo = KNNBasic()
algo.train(trainset)

uid = str(196)  # raw user id (as in the ratings file). They are **strings**!
iid = str(302)  # raw item id (as in the ratings file). They are **strings**!

# get a prediction for specific users and items.
pred = algo.predict(uid, iid, r=4, verbose=True)

Notation standards¶

In the documentation, you will find the following notation:

• \(R\) : the set of all ratings.
• \(R_{train}\), \(R_{test}\) and \(\hat{R}\) denote the training set, the test set, and the set of predicted ratings.
• \(U\) : the set of all users. \(u\) and \(v\) denotes users.
• \(I\) : the set of all items. \(i\) and \(j\) denotes items.
• \(U_i\) : the set of all users that have rated item \(i\).
• \(U_{ij}\) : the set of all users that have rated both items \(i\) and \(j\).
• \(I_u\) : the set of all items rated by user \(u\).
• \(I_{uv}\) : the set of all items rated by both users \(u\) and \(v\).
• \(r_{ui}\) : the true rating of user \(u\) for item \(i\).
• \(\hat{r}_{ui}\) : the estimated rating of user \(u\) for item \(i\).
• \(b_{ui}\) : the baseline rating of user \(u\) for item \(i\).
• \(\mu\) : the mean of all ratings.
• \(\mu_u\) : the mean of all ratings given by user \(u\).
• \(\mu_i\) : the mean of all ratings given to item \(i\).
• \(N_i^k(u)\) : the \(k\) nearest neighbors of user \(u\) that have rated item \(i\). This set is computed using a similarity metric.
• \(N_u^k(i)\) : the \(k\) nearest neighbors of item \(i\) that are rated by user \(u\). This set is computed using a similarity metric.

Prediction algorithms¶

Surprise provides with a bunch of built-in algorithms. You can find the details of each of these in the surprise.prediction_algorithms package documentation.

Every algorithm is part of the global Surprise namespace, so you only need to import their names from the Surprise package, for example:

from surprise import KNNBasic
algo = KNNBasic()

Some of these algorithms may use baseline estimates, some may use a similarity measure. We will here review how to configure the way baselines and similarities are computed.

print('Using ALS')
bsl_options = {'method': 'als',
               'n_epochs': 5,
               'reg_u': 12,
               'reg_i': 5
               }
algo = BaselineOnly(bsl_options=bsl_options)

print('Using SGD')
bsl_options = {'method': 'sgd',
               'learning_rate': .00005,
               }
algo = BaselineOnly(bsl_options=bsl_options)

bsl_options = {'method': 'als',
               'n_epochs': 20,
               }
sim_options = {'name': 'pearson_baseline'}
algo = KNNBasic(bsl_options=bsl_options, sim_options=sim_options)

sim_options = {'name': 'cosine',
               'user_based': False  # compute  similarities between items
               }
algo = KNNBasic(sim_options=sim_options)

sim_options = {'name': 'pearson_baseline',
               'shrinkage': 0  # no shrinkage
               }
algo = KNNBasic(sim_options=sim_options)

How to build you own prediction algorithm¶

This page describes how to build a custom prediction algorithm using Surprise.

from surprise import AlgoBase
from surprise import Dataset
from surprise import evaluate


class MyOwnAlgorithm(AlgoBase):

    def __init__(self):

        # Always call base method before doing anything.
        AlgoBase.__init__(self)

    def estimate(self, u, i):

        return 3

data = Dataset.load_builtin('ml-100k')
algo = MyOwnAlgorithm()

evaluate(algo, data)

def estimate(self, u, i):

    details = {'info1' : 'That was',
               'info2' : 'easy stuff :)'}
    return 3, details

class MyOwnAlgorithm(AlgoBase):

    def __init__(self):

        # Always call base method before doing anything.
        AlgoBase.__init__(self)

    def train(self, trainset):

        # Here again: call base method before doing anything.
        AlgoBase.train(self, trainset)

        # Compute the average rating. We might as well use the
        # trainset.global_mean attribute ;)
        self.the_mean = np.mean(
                        [r for (_, _, r) in self.trainset.all_ratings()])

    def estimate(self, u, i):

        return self.the_mean

    def estimate(self, u, i):

        sum_means = self.trainset.global_mean
        div = 1

        if self.trainset.knows_user(u):
            sum_means += np.mean([r for (_, r) in self.trainset.ur[u]])
            div += 1
        if self.trainset.knows_item(i):
            sum_means += np.mean([r for (_, r) in self.trainset.ir[i]])
            div += 1

        return sum_means / div

from surprise import PredictionImpossible

class MyOwnAlgorithm(AlgoBase):

    def __init__(self, sim_options={}, bsl_options={}):

        AlgoBase.__init__(self, sim_options=sim_options,
                          bsl_options=bsl_options)

    def train(self, trainset):

        AlgoBase.train(self, trainset)

        # Compute baselines and similarities
        self.bu, self.bi = self.compute_baselines()
        self.sim = self.compute_similarities()

    def estimate(self, u, i):

        if not (self.trainset.knows_user(u) and self.trainset.knows_item(i)):
            raise PredictionImpossible('User and/or item is unkown.')

        # Compute similarities between u and v, where v describes all other
        # users that have also rated item i.
        neighbors = [(v, self.sim[u, v]) for (v, r) in self.trainset.ir[i]]
        # Sort these neighbors by similarity
        neighbors = sorted(neighbors, key=lambda x: x[1], reverse=True)

        print('The 3 nearest neighbors of user', str(u), 'are:')
        for v, sim_uv in neighbors[:3]:
            print('user {0:} with sim {1:1.2f}'.format(v, sim_uv))

        # ... Aaaaand return the baseline estimate anyway ;)
        bsl = self.trainset.global_mean + self.bu[u] + self.bi[i]
        return bsl

prediction_algorithms package¶

The prediction_algorithms package includes the prediction algorithms available for recommendation.

The available prediction algorithms are:

You may want to check the Notation standards before diving into the formulas.

similarities module¶

The similarities module includes tools to compute similarity metrics between users or items. You may need to refer to the Notation standards page. See also the Similarity measure configuration section of the User Guide.

Available similarity measures:

surprise.similarities.cosine()¶

Compute the cosine similarity between all pairs of users (or items).

Only common users (or items) are taken into account. The cosine similarity is defined as:

\[\text{cosine_sim}(u, v) = \frac{ \sum\limits_{i \in I_{uv}} r_{ui} \cdot r_{vi}} {\sqrt{\sum\limits_{i \in I_{uv}} r_{ui}^2} \cdot \sqrt{\sum\limits_{i \in I_{uv}} r_{vi}^2} }\]

or

\[\text{cosine_sim}(i, j) = \frac{ \sum\limits_{u \in U_{ij}} r_{ui} \cdot r_{uj}} {\sqrt{\sum\limits_{u \in U_{ij}} r_{ui}^2} \cdot \sqrt{\sum\limits_{u \in U_{ij}} r_{uj}^2} }\]

depending on the user_based field of sim_options (see Similarity measure configuration).

For details on cosine similarity, see on Wikipedia.

surprise.similarities.msd()¶

Compute the Mean Squared Difference similarity between all pairs of users (or items).

Only common users (or items) are taken into account. The Mean Squared Difference is defined as:

\[\text{msd}(u, v) = \frac{1}{|I_{uv}|} \cdot \sum\limits_{i \in I_{uv}} (r_{ui} - r_{vi})^2\]

or

\[\text{msd}(i, j) = \frac{1}{|U_{ij}|} \cdot \sum\limits_{u \in U_{ij}} (r_{ui} - r_{uj})^2\]

depending on the user_based field of sim_options (see Similarity measure configuration).

The MSD-similarity is then defined as:

\[\begin{split}\text{msd_sim}(u, v) &= \frac{1}{\text{msd}(u, v) + 1}\\ \text{msd_sim}(i, j) &= \frac{1}{\text{msd}(i, j) + 1}\end{split}\]

The \(+ 1\) term is just here to avoid dividing by zero.

For details on MSD, see third definition on Wikipedia.

surprise.similarities.pearson()¶

Compute the Pearson correlation coefficient between all pairs of users (or items).

Only common users (or items) are taken into account. The Pearson correlation coefficient can be seen as a mean-centered cosine similarity, and is defined as:

\[\text{pearson_sim}(u, v) = \frac{ \sum\limits_{i \in I_{uv}} (r_{ui} - \mu_u) \cdot (r_{vi} - \mu_{v})} {\sqrt{\sum\limits_{i \in I_{uv}} (r_{ui} - \mu_u)^2} \cdot \sqrt{\sum\limits_{i \in I_{uv}} (r_{vi} - \mu_{v})^2} }\]

or

\[\text{pearson_sim}(i, j) = \frac{ \sum\limits_{u \in U_{ij}} (r_{ui} - \mu_i) \cdot (r_{uj} - \mu_{j})} {\sqrt{\sum\limits_{u \in U_{ij}} (r_{ui} - \mu_i)^2} \cdot \sqrt{\sum\limits_{u \in U_{ij}} (r_{uj} - \mu_{j})^2} }\]

depending on the user_based field of sim_options (see Similarity measure configuration).

Note: if there are no common users or items, similarity will be 0 (and not -1).

For details on Pearson coefficient, see Wikipedia.

surprise.similarities.pearson_baseline()¶

Compute the (shrunk) Pearson correlation coefficient between all pairs of users (or items) using baselines for centering instead of means.

The shrinkage parameter helps to avoid overfitting when only few ratings are available (see Similarity measure configuration).

The Pearson-baseline correlation coefficient is defined as:

\[\text{pearson_baseline_sim}(u, v) = \hat{\rho}_{uv} = \frac{ \sum\limits_{i \in I_{uv}} (r_{ui} - b_{ui}) \cdot (r_{vi} - b_{vi})} {\sqrt{\sum\limits_{i \in I_{uv}} (r_{ui} - b_{ui})^2} \cdot \sqrt{\sum\limits_{i \in I_{uv}} (r_{vi} - b_{vi})^2}}\]

or

\[\text{pearson_baseline_sim}(i, j) = \hat{\rho}_{ij} = \frac{ \sum\limits_{u \in U_{ij}} (r_{ui} - b_{ui}) \cdot (r_{uj} - b_{uj})} {\sqrt{\sum\limits_{u \in U_{ij}} (r_{ui} - b_{ui})^2} \cdot \sqrt{\sum\limits_{u \in U_{ij}} (r_{uj} - b_{uj})^2}}\]

The shrunk Pearson-baseline correlation coefficient is then defined as:

\[\begin{split}\text{pearson_baseline_shrunk_sim}(u, v) &= \frac{|I_{uv}| - 1} {|I_{uv}| - 1 + \text{shrinkage}} \cdot \hat{\rho}_{uv}\end{split}\]\[\begin{split}\text{pearson_baseline_shrunk_sim}(i, j) &= \frac{|U_{ij}| - 1} {|U_{ij}| - 1 + \text{shrinkage}} \cdot \hat{\rho}_{ij}\end{split}\]

Obviously, a shrinkage parameter of 0 amounts to no shrinkage at all.

Note: here again, if there are no common users/items, similarity will be 0 (and not -1).

Motivations for such a similarity measure can be found on the Recommender System Handbook, section 5.4.1.

accuracy module¶

The surprise.accuracy module provides with tools for computing accuracy metrics on a set of predictions.

Available accuracy metrics:

surprise.accuracy.fcp(predictions, verbose=True)[source]¶

Compute FCP (Fraction of Concordant Pairs).

Computed as described in paper Collaborative Filtering on Ordinal User Feedback by Koren and Sill, section 5.2.

Parameters:	predictions (list of Prediction) – A list of predictions, as returned by the test method. verbose – If True, will print computed value. Default is True.
Returns:	The Fraction of Concordant Pairs.
Raises:	ValueError – When predictions is empty.

surprise.accuracy.mae(predictions, verbose=True)[source]¶

Compute MAE (Mean Absolute Error).

\[\text{MAE} = \frac{1}{|\hat{R}|} \sum_{\hat{r}_{ui} \in \hat{R}}|r_{ui} - \hat{r}_{ui}|\]

Parameters:	predictions (list of Prediction) – A list of predictions, as returned by the test method. verbose – If True, will print computed value. Default is True.
Returns:	The Mean Absolute Error of predictions.
Raises:	ValueError – When predictions is empty.

surprise.accuracy.rmse(predictions, verbose=True)[source]¶

Compute RMSE (Root Mean Squared Error).

\[\text{RMSE} = \sqrt{\frac{1}{|\hat{R}|} \sum_{\hat{r}_{ui} \in \hat{R}}(r_{ui} - \hat{r}_{ui})^2}.\]

Parameters:	predictions (list of Prediction) – A list of predictions, as returned by the test method. verbose – If True, will print computed value. Default is True.
Returns:	The Root Mean Squared Error of predictions.
Raises:	ValueError – When predictions is empty.

dataset module¶

the dataset module defines some tools for managing datasets.

Users may use both built-in and user-defined datasets (see the Getting Started page for examples). Right now, four built-in datasets are available:

• The movielens-100k dataset.
• The movielens-1m dataset.
• The Jester dataset 2.

Built-in datasets can all be loaded (or downloaded if you haven’t already) using the Dataset.load_builtin() method. For each built-in dataset, Surprise also provide predefined readers which are useful if you want to use a custom dataset that has the same format as a built-in one.

Summary:

class surprise.dataset.Dataset(reader)[source]¶

Base class for loading datasets.

Note that you should never instantiate the Dataset class directly (same goes for its derived classes), but instead use one of the three available methods for loading datasets.

folds()[source]¶

Generator function to iterate over the folds of the Dataset.

See User Guide for usage.

Yields:	tuple – Trainset and testset of current fold.

classmethod load_builtin(name=u'ml-100k')[source]¶

Load a built-in dataset.

If the dataset has not already been loaded, it will be downloaded and saved. You will have to split your dataset using the split method. See an example in the User Guide.

Parameters:	name (string) – The name of the built-in dataset to load. Accepted values are ‘ml-100k’, ‘ml-1m’, and ‘jester’. Default is ‘ml-100k’.
Returns:	A Dataset object.
Raises:	ValueError – If the name parameter is incorrect.

classmethod load_from_file(file_path, reader)[source]¶

Load a dataset from a (custom) file.

Use this if you want to use a custom dataset and all of the ratings are stored in one file. You will have to split your dataset using the split method. See an example in the User Guide.

Parameters:	file_path (string) – The path to the file containing ratings. reader (Reader) – A reader to read the file.

classmethod load_from_folds(folds_files, reader)[source]¶

Load a dataset where folds (for cross-validation) are predifined by some files.

The purpose of this method is to cover a common use case where a dataset is already split into predefined folds, such as the movielens-100k dataset which defines files u1.base, u1.test, u2.base, u2.test, etc... It can also be used when you don’t want to perform cross-validation but still want to specify your training and testing data (which comes down to 1-fold cross-validation anyway). See an example in the User Guide.

Parameters:	folds_files (iterable of tuples) – The list of the folds. A fold is a tuple of the form (path_to_train_file, path_to_test_file). reader (Reader) – A reader to read the files.

class surprise.dataset.DatasetAutoFolds(ratings_file=None, reader=None)[source]¶

A derived class from Dataset for which folds (for cross-validation) are not predefined. (Or for when there are no folds at all).

build_full_trainset()[source]¶

Do not split the dataset into folds and just return a trainset as is, built from the whole dataset.

User can then query for predictions, as shown in the User Guide.

Returns:	The Trainset.

split(n_folds=5, shuffle=True)[source]¶

Split the dataset into folds for futur cross-validation.

If you forget to call split(), the dataset will be automatically shuffled and split for 5-folds cross-validation.

You can obtain repeatable splits over your all your experiments by seeding the RNG:

import random
random.seed(my_seed)  # call this before you call split!

Parameters:	n_folds (int) – The number of folds. shuffle (bool) – Whether to shuffle ratings before splitting. If False, folds will always be the same each time the experiment is run. Default is True.

class surprise.dataset.Reader(name=None, line_format=None, sep=None, rating_scale=(1, 5), skip_lines=0)[source]¶

The Reader class is used to parse a file containing ratings.

Such a file is assumed to specify only one rating per line, and each line needs to respect the following structure:

user ; item ; rating ; [timestamp]

where the order of the fields and the seperator (here ‘;’) may be arbitrarily defined (see below). brackets indicate that the timestamp field is optional.

Parameters:

name (string, optional) – If specified, a Reader for one of the built-in datasets is returned and any other parameter is ignored. Accepted values are ‘ml-100k’, ‘ml-1m’, and ‘jester’. Default is None. line_format (string) – The fields names, in the order at which they are encountered on a line. Example: 'item user rating'. sep (char) – the separator between fields. Example : ';'. rating_scale (tuple, optional) – The rating scale used for every rating. Default is (1, 5). skip_lines (int, optional) – Number of lines to skip at the beginning of the file. Default is 0.

class surprise.dataset.Trainset(rm, ur, ir, n_users, n_items, r_min, r_max, raw2inner_id_users, raw2inner_id_items)[source]¶

A trainset contains all useful data that constitutes a training set.

It is used by the train() method of every prediction algorithm. You should not try to built such an object on your own but rather use the Dataset.folds() method or the DatasetAutoFolds.build_full_trainset() method.

rm¶

defaultdict of int

A dictionary containing all known ratings. Keys are tuples (user_inner__id, item_inner_id), values are ratings. rm stands for ratings matrix, even though it’s not a proper matrix object.

ur¶

defaultdict of list

A dictionary containing lists of tuples of the form (item_inner_id, rating). Keys are user inner ids. ur stands for user ratings.

ir¶

defaultdict of list

A dictionary containing lists of tuples of the form (user_inner_id, rating). Keys are item inner ids. ir stands for item ratings.

n_users¶

Total number of users \(|U|\).

n_items¶

Total number of items \(|I|\).

n_ratings¶

Total number of ratings \(|R_{train}|\).

r_min¶

Minimum value of the rating scale.

r_max¶

Maximum value of the rating scale.

global_mean¶

The mean of all ratings \(\mu\).

all_items()[source]¶

Generator function to iterate over all items.

Yields:	Inner id of items.

all_ratings()[source]¶

Generator function to iterate over all ratings.

Yields:	A tuple (uid, iid, rating) where ids are inner ids.

all_users()[source]¶

Generator function to iterate over all users.

Yields:	Inner id of users.

global_mean

Return the mean of all ratings.

It’s only computed once.

knows_item(iid)[source]¶

Indicate if the item is part of the trainset.

An item is part of the trainset if the item was rated at least once.

Parameters:	iid – The (inner) item id. See this note.
Returns:	True if item is part of the trainset, else False.

knows_user(uid)[source]¶

Indicate if the user is part of the trainset.

A user is part of the trainset if the user has at least one rating.

Parameters:	uid – The (inner) user id. See this note.
Returns:	True if user is part of the trainset, else False.

to_inner_iid(riid)[source]¶

Convert a raw item id to an inner id.

See this note.

Parameters:	riid – The item raw id.
Returns:	The item inner id.
Raises:	ValueError – When item is not part of the trainset.

to_inner_uid(ruid)[source]¶

Convert a raw user id to an inner id.

See this note.

Parameters:	ruid – The user raw id.
Returns:	The user inner id.
Raises:	ValueError – When user is not part of the trainset.

evaluate module¶

The evaluate module defines the evaluate() function.

surprise.evaluate.evaluate(algo, data, measures=[u'rmse', u'mae'], with_dump=False, dump_dir=None, verbose=1)[source]¶

Evaluate the performance of the algorithm on given data.

Depending on the nature of the data parameter, it may or may not perform cross validation.

Parameters:

algo (AlgoBase) – The algorithm to evaluate. data (Dataset) – The dataset on which to evaluate the algorithm. measures (list of string) – The performance measures to compute. Allowed names are function names as defined in the accuracy module. Default is ['rmse', 'mae']. with_dump (bool) – If True, the predictions, the trainsets and the algorithm parameters will be dumped for later further analysis at each fold (see User Guide). The file names will be set as: '<date>-<algorithm name>-<fold number>'. Default is False. dump_dir (str) – The directory where to dump to files. Default is '~/.surprise_data/dumps/'. verbose (int) – Level of verbosity. If 0, nothing is printed. If 1 (default), accuracy measures for each folds are printed, with a final summary. If 2, every prediction is printed.

Returns:

A dictionary containing measures as keys and lists as values. Each list contains one entry per fold.

dump module¶

The dump module defines the dump() function.

surprise.dump.dump(file_name, predictions, trainset=None, algo=None)[source]¶

Dump a list of predictions for future analysis, using Pickle.

If needed, the trainset object and the algorithm can also be dumped. What is dumped is a dictionnary with keys 'predictions, 'trainset', and 'algo'.

The dumped algorithm won’t be a proper algorithm object but simply a dictionnary with the algorithm attributes as keys-values (technically, the algo.__dict__ attribute).

See User Guide for usage.

Parameters:	file_name (str) – The name (with full path) specifying where to dump the predictions. predictions (list of Prediction) – The predictions to dump. trainset (Trainset, optional) – The trainset to dump. algo (Algorithm, optional) – algorithm to dump.