Surprise is an easy-to-use open source Python library for recommender systems. Its goal is to make life easier for reseachers who want to play around with new algorithms ideas, for teachers who want some teaching materials, and for students.
Surprise was designed with the following purposes in mind:
- Give the user perfect control over his 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 details of the algorithms.
- Alleviate the pain of Dataset handling. Users can use both built-in datasets (Movielens, Jester), and their own custom datasets.
- Provide with various ready-to-use prediction algorithms (Neighborhood approaches, SVD, SVD++...)
- Make it easy to implement new algorithm ideas.
- Provide with tools to evaluate, analyse and compare the algorithms performance. Cross-validation procedures can be run very easily.
The name SurPRISE (roughly) stands for Simple Python RecommendatIon System Engine.
The easiest way is to use pip (you'll need numpy):
$ pip install surprise
Or you can clone the repo and build the source (you'll need Cython and numpy):
$ git clone https://github.com/NicolasHug/surprise.git
$ python setup.py install
Here is a simple example showing how you can (down)load a dataset, split it for 3-folds cross-validation, and compute the MAE and RMSE of the SVD algorithm.
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)Output:
Evaluating RMSE, MAE of algorithm SVD.
Fold 1 Fold 2 Fold 3 Mean
MAE 0.7475 0.7447 0.7425 0.7449
RMSE 0.9461 0.9436 0.9425 0.9441
The following table shows the average RMSE and MAE and total execution time of various algorithms on a 5-folds cross-validation procedure. The dataset is the Movielens 100k dataset. All experiments are run on a laptop with Intel Core i3 1.7 GHz, 4Go Ram.
| RMSE | MAE | Time (s) | |
|---|---|---|---|
| NormalPredictor | 1.5228 | 1.2242 | 4 |
| BaselineOnly | .9445 | .7488 | 16 |
| KNNBasic | .9789 | .7732 | 27 |
| KNNWithMeans | .9514 | .7500 | 30 |
| KNNBaseline | .9306 | .7334 | 44 |
| SVD | .9392 | .7409 | 46 |
The documentation with many other usage examples is available online on ReadTheDocs.
This project is licensed under the BSD 3-Clause license.
- Pierre-François Gimenez, for his valuable insights on software design.
Any kind of feedback/criticism would be greatly appreciated (software design, documentation, improvement ideas, spelling mistakes, etc...). Please feel free to contribute and send pull requests!