README

Overview
--------

Surprise is a Python
scikit for building and analyzing
recommender systems that deal with explicit rating data.

Surprise was designed with the
following purposes in mind:

- Give users perfect control over their experiments. To this end, a strong
  emphasis is laid on
  documentation, which we
  have tried to make as clear and precise as possible by pointing out every
  detail of the algorithms.
- Alleviate the pain of Dataset
  handling.
  Users can use both built-in datasets
  (Movielens,
  Jester), and their own custom
  datasets.
- Provide various ready-to-use prediction
  algorithms
  such as baseline
  algorithms,
  neighborhood
  methods, matrix
  factorization-based (
  SVD,
  PMF,
  SVD++,
  NMF),
  and many
  others.
  Also, various similarity
  measures
  (cosine, MSD, pearson...) are built-in.
- Make it easy to implement new algorithm
  ideas.
- Provide tools to evaluate,
  analyse
  and
  compare
  the algorithms' performance. Cross-validation procedures can be run very
  easily using powerful CV iterators (inspired by
  scikit-learn excellent tools), as well as
  exhaustive search over a set of
  parameters.


The name SurPRISE (roughly :) ) stands for Simple Python RecommendatIon
System Engine.

Please note that surprise does not support implicit ratings or content-based
information.


Getting started, example
------------------------

Here is a simple example showing how you can (down)load a dataset, split it for
5-fold cross-validation, and compute the MAE and RMSE of the
SVD
algorithm.


python
from surprise import SVD
from surprise import Dataset
from surprise.model_selection import cross_validate

 Load the movielens-100k dataset (download it if needed).
data = Dataset.load_builtin('ml-100k')

 Use the famous SVD algorithm.
algo = SVD()

 Run 5-fold cross-validation and print results.
cross_validate(algo, data, measures=['RMSE', 'MAE'], cv=5, verbose=True)


Output:


Evaluating RMSE, MAE of algorithm SVD on 5 split(s).

                  Fold 1  Fold 2  Fold 3  Fold 4  Fold 5  Mean    Std     
RMSE (testset)    0.9367  0.9355  0.9378  0.9377  0.9300  0.9355  0.0029  
MAE (testset)     0.7387  0.7371  0.7393  0.7397  0.7325  0.7375  0.0026  
Fit time          0.62    0.63    0.63    0.65    0.63    0.63    0.01    
Test time         0.11    0.11    0.14    0.14    0.14    0.13    0.02    


Surprise can do much more (e.g,
GridSearchCV)!
You'll find more usage
examples in the
documentation .


Benchmarks
----------

Here are the average RMSE, MAE and total execution time of various algorithms
(with their default parameters) on a 5-fold cross-validation procedure. The
datasets are the Movielens 100k and
1M datasets. The folds are the same for all the algorithms. All experiments are
run on a laptop with an intel i5 11th Gen 2.60GHz. The code
for generating these tables can be found in the benchmark
example.

| Movielens 100k                                                                         |   RMSE |   M