How to build your own prediction algorithm — Surprise 1 documentation 3/6/22, 9:35 AM

Docs » How to build your own predic!on algorithm

How to build your own prediction algorithm

This page describes how to build a custom predic!on algorithm using Surprise.

The basics
Want to get your hands dirty? Cool.

Crea!ng your own predic!on algorithm is pre"y simple: an algorithm is nothing but a
class derived from AlgoBase that has an estimate method. This is the method that is
called by the predict() method. It takes in an inner user id, an inner item id (see this
̂ :
note), and returns the es!mated ra!ng 𝑟𝑢𝑖

From file examples/building_custom_algorithms/most_basic_algorithm.py

from surprise import AlgoBase

from surprise import Dataset
from surprise.model_selection import cross_validate

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

cross_validate(algo, data, verbose=True)

https://surprise.readthedocs.io/en/stable/building_custom_algo.html#building-custom-algo Page 1 of 5
How to build your own prediction algorithm — Surprise 1 documentation 3/6/22, 9:35 AM

This algorithm is the dumbest we could have thought of: it just predicts a ra!ng of 3,
regardless of users and items.

If you want to store addi!onal informa!on about the predic!on, you can also return a
dic!onary with given details:

def estimate(self, u, i):

details = {'info1' : 'That was',

'info2' : 'easy stuff :)'}
return 3, details

This dic!onary will be stored in the prediction as the details field and can be used
for later analysis.

The fit method

Now, let’s make a slightly cleverer algorithm that predicts the average of all the ra!ngs
of the trainset. As this is a constant value that does not depend on current user or item,
we would rather compute it once and for all. This can be done by defining the fit

method:

From file examples/building_custom_algorithms/most_basic_algorithm2.py

https://surprise.readthedocs.io/en/stable/building_custom_algo.html#building-custom-algo Page 2 of 5
How to build your own prediction algorithm — Surprise 1 documentation 3/6/22, 9:35 AM

class MyOwnAlgorithm(AlgoBase):

def __init__(self):

# Always call base method before doing anything.

AlgoBase.__init__(self)

def fit(self, trainset):

# Here again: call base method before doing anything.

AlgoBase.fit(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()])

return self

def estimate(self, u, i):

return self.the_mean

The fit method is called e.g. by the cross_validate func!on at each fold of a cross-
valida!on process, (but you can also call it yourself). Before doing anything, you should
call the base class fit() method.

Note that the fit() method returns self . This allows to use expression like
algo.fit(trainset).test(testset) .

The trainset attribute

Once the base class fit() method has returned, all the info you need about the
current training set (ra!ng values, etc…) is stored in the self.trainset a"ribute. This is
a Trainset object that has many a"ributes and methods of interest for predic!on.

To illustrate its usage, let’s make an algorithm that predicts an average between the
mean of all ra!ngs, the mean ra!ng of the user and the mean ra!ng for the item:

From file examples/building_custom_algorithms/mean_rating_user_item.py

https://surprise.readthedocs.io/en/stable/building_custom_algo.html#building-custom-algo Page 3 of 5
How to build your own prediction algorithm — Surprise 1 documentation 3/6/22, 9:35 AM

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

Note that it would have been a be"er idea to compute all the user means in the fit

method, thus avoiding the same computa!ons mul!ple !mes.

When the prediction is impossible

It’s up to your algorithm to decide if it can or cannot yield a predic!on. If the predic!on
is impossible, then you can raise the PredictionImpossible excep!on. You’ll need to
import it first:

from surprise import PredictionImpossible

This excep!on will be caught by the predict() ̂ will be

method, and the es!ma!on 𝑟𝑢𝑖
set according to the default_prediction() method, which can be overridden. By
default, it returns the average of all ra!ngs in the trainset.

Using similarities and baselines

Should your algorithm use a similarity measure or baseline es!mates, you’ll need to
accept bsl_options and sim_options as parameters to the __init__ method, and pass
them along to the Base class. See how to use these parameters in the Using predic!on
algorithms sec!on.

https://surprise.readthedocs.io/en/stable/building_custom_algo.html#building-custom-algo Page 4 of 5
How to build your own prediction algorithm — Surprise 1 documentation 3/6/22, 9:35 AM

Methods compute_baselines() and compute_similarities() can be called in the fit

method (or anywhere else).

From file examples/building_custom_algorithms/.with_baselines_or_sim.py

class MyOwnAlgorithm(AlgoBase):

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

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

def fit(self, trainset):

AlgoBase.fit(self, trainset)

# Compute baselines and similarities

self.bu, self.bi = self.compute_baselines()
self.sim = self.compute_similarities()

return self

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 unknown.')

# 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 ;)

Feel free to explore the predic!on_algorithms package source to get an idea of what
can be done.

https://surprise.readthedocs.io/en/stable/building_custom_algo.html#building-custom-algo Page 5 of 5