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 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, as well as exhaustive search over a set of parameters.
The name SurPRISE (roughly :) ) stands for Simple Python RecommendatIon System Engine.
Getting started, example
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, print_perf # 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(perf)
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
Here are the average RMSE, MAE and total execution time of various algorithms (with their default parameters) on a 5-folds cross-validation procedure. The datasets are the Movielens 100k and 1M datasets. The folds are the same for all the algorithms (the random seed is set to 0). All experiments are run on a small laptop with Intel Core i3 1.7 GHz, 4Go RAM. The execution time is the real execution time, as returned by the GNU time command.
|Movielens 100k||RMSE||MAE||Time (s)|
|Movielens 1M||RMSE||MAE||Time (min)|
Installation / Usage
The easiest way is to use pip (you'll need numpy):
$ pip install numpy $ pip install scikit-surprise
$ git clone https://github.com/NicolasHug/surprise.git $ python setup.py install
- Pierre-François Gimenez, for his valuable insights on software design.
- Maher Malaeb, for the GridSearch implementation.
Contributing, feedback, contact
Any kind of feedback/criticism would be greatly appreciated (software design, documentation, improvement ideas, spelling mistakes, etc...).
If you'd like to see some features or algorithms implemented in Surprise, please let us know! Some of the current ideas are:
- Bayesian PMF
- RBM for CF
Please feel free to contribute (see guidelines) and send pull requests!