Top Related Projects
TensorFlow Recommenders is a library for building recommender system models using TensorFlow.
Fast Python Collaborative Filtering for Implicit Feedback Datasets
A Python implementation of LightFM, a hybrid recommendation algorithm.
A unified, comprehensive and efficient recommendation library
Quick Overview
Surprise is a Python scikit for building and analyzing recommender systems. It provides various collaborative filtering algorithms, tools for dataset handling, and evaluation metrics. Surprise is designed to be user-friendly and efficient, making it suitable for both research and practical applications in recommendation systems.
Pros
- Easy to use with a scikit-learn inspired API
- Includes a variety of popular recommendation algorithms
- Provides built-in cross-validation and evaluation tools
- Supports custom datasets and algorithms
Cons
- Limited to collaborative filtering techniques
- May not be as scalable as some enterprise-level solutions
- Documentation could be more comprehensive
- Lacks some advanced features found in larger recommendation libraries
Code Examples
- Creating and training a basic SVD model:
from surprise import SVD, Dataset
from surprise import accuracy
# Load the movielens-100k dataset
data = Dataset.load_builtin('ml-100k')
trainset = data.build_full_trainset()
# Create and train the SVD algorithm
algo = SVD()
algo.fit(trainset)
# Make predictions
testset = trainset.build_anti_testset()
predictions = algo.test(testset)
# Compute RMSE
accuracy.rmse(predictions)
- Cross-validation with KNNBasic:
from surprise import KNNBasic, Dataset
from surprise.model_selection import cross_validate
# Load the movielens-100k dataset
data = Dataset.load_builtin('ml-100k')
# Perform 5-fold cross-validation
algo = KNNBasic()
results = cross_validate(algo, data, measures=['RMSE', 'MAE'], cv=5, verbose=True)
- Using a custom dataset:
from surprise import Dataset, Reader
from surprise import NormalPredictor
# Load data from a file
reader = Reader(line_format='user item rating', sep=',')
data = Dataset.load_from_file('my_ratings.csv', reader=reader)
# Use the NormalPredictor algorithm
algo = NormalPredictor()
trainset = data.build_full_trainset()
algo.fit(trainset)
# Predict a specific rating
uid = str(196) # raw user id
iid = str(302) # raw item id
pred = algo.predict(uid, iid)
print(pred)
Getting Started
To get started with Surprise, follow these steps:
- Install Surprise:
pip install scikit-surprise
- Import necessary modules and load a dataset:
from surprise import Dataset, SVD
from surprise.model_selection import train_test_split
# Load the movielens-100k dataset
data = Dataset.load_builtin('ml-100k')
trainset, testset = train_test_split(data, test_size=0.25)
- Create, train, and evaluate a model:
# Use SVD algorithm
algo = SVD()
# Train the algorithm on the trainset
algo.fit(trainset)
# Predict ratings for the testset
predictions = algo.test(testset)
# Compute and print RMSE
from surprise import accuracy
accuracy.rmse(predictions)
Competitor Comparisons
TensorFlow Recommenders is a library for building recommender system models using TensorFlow.
Pros of TensorFlow Recommenders
- Built on TensorFlow, offering scalability and GPU acceleration
- Supports advanced deep learning models for recommendations
- Integrates well with other TensorFlow libraries and tools
Cons of TensorFlow Recommenders
- Steeper learning curve, especially for those new to TensorFlow
- More complex setup and configuration compared to Surprise
- Potentially overkill for simpler recommendation tasks
Code Comparison
Surprise example:
from surprise import SVD, Dataset
data = Dataset.load_builtin('ml-100k')
algo = SVD()
algo.fit(data.build_full_trainset())
TensorFlow Recommenders example:
import tensorflow as tf
import tensorflow_recommenders as tfrs
model = tfrs.models.BasicRanking(
user_model=tf.keras.Sequential([...]),
item_model=tf.keras.Sequential([...]),
task=tfrs.tasks.Ranking()
)
model.compile(optimizer=tf.keras.optimizers.Adagrad(0.1))
Summary
Surprise is more straightforward and easier to use for traditional collaborative filtering algorithms, while TensorFlow Recommenders offers more advanced capabilities for complex, deep learning-based recommendation systems. The choice between the two depends on the specific requirements of the project and the user's familiarity with TensorFlow.
Fast Python Collaborative Filtering for Implicit Feedback Datasets
Pros of implicit
- Faster performance, especially for large datasets
- Supports more diverse recommendation algorithms (ALS, BPR, LMF)
- Better suited for implicit feedback scenarios
Cons of implicit
- Less user-friendly documentation compared to Surprise
- Fewer built-in evaluation metrics
- Steeper learning curve for beginners
Code comparison
Surprise example:
from surprise import SVD, Dataset
data = Dataset.load_builtin('ml-100k')
algo = SVD()
algo.fit(data.build_full_trainset())
predictions = algo.test(data.build_full_testset())
implicit example:
from implicit.als import AlternatingLeastSquares
import scipy.sparse as sparse
user_items = sparse.csr_matrix(...)
model = AlternatingLeastSquares()
model.fit(user_items)
recommendations = model.recommend(user_id, user_items[user_id])
Both libraries offer collaborative filtering capabilities, but implicit focuses on implicit feedback scenarios, while Surprise provides a broader range of algorithms for explicit feedback. implicit excels in performance and scalability, making it more suitable for large-scale production environments. Surprise, on the other hand, offers a more user-friendly interface and comprehensive documentation, making it ideal for beginners and research purposes.
A Python implementation of LightFM, a hybrid recommendation algorithm.
Pros of LightFM
- Supports hybrid recommendation systems, combining content-based and collaborative filtering
- Offers efficient implementation for large-scale datasets
- Provides built-in support for implicit feedback data
Cons of LightFM
- Less extensive documentation compared to Surprise
- Fewer built-in evaluation metrics
- Steeper learning curve for beginners
Code Comparison
Surprise example:
from surprise import SVD, Dataset
data = Dataset.load_builtin('ml-100k')
algo = SVD()
algo.fit(data.build_full_trainset())
predictions = algo.test(data.build_full_testset())
LightFM example:
from lightfm import LightFM
from lightfm.datasets import fetch_movielens
data = fetch_movielens()
model = LightFM(loss='warp')
model.fit(data['train'], epochs=10, num_threads=2)
predictions = model.predict(data['test_user_ids'], data['test_item_ids'])
Both libraries offer straightforward ways to load data, train models, and make predictions. Surprise focuses on traditional collaborative filtering algorithms, while LightFM provides hybrid models that can incorporate both user-item interactions and content features. LightFM's API is more flexible but may require more setup, whereas Surprise offers a more streamlined experience for common recommendation tasks.
A unified, comprehensive and efficient recommendation library
Pros of RecBole
- Offers a wider range of recommendation algorithms and models
- Provides more comprehensive evaluation metrics and tools
- Supports deep learning-based recommendation models
Cons of RecBole
- Steeper learning curve due to its more complex architecture
- Requires more computational resources for some advanced models
- Less beginner-friendly documentation compared to Surprise
Code Comparison
Surprise example:
from surprise import SVD, Dataset
data = Dataset.load_builtin('ml-100k')
algo = SVD()
algo.fit(data.build_full_trainset())
RecBole example:
from recbole.quick_start import run_recbole
run_recbole(model='SVD', dataset='ml-100k')
While both libraries offer collaborative filtering algorithms like SVD, RecBole provides a more streamlined approach with its run_recbole
function. However, Surprise's implementation allows for more granular control over the training process. RecBole's syntax is more concise but may require additional configuration for advanced use cases.
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual CopilotREADME
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.
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 | MAE | Time |
---|---|---|---|
SVD | 0.934 | 0.737 | 0:00:06 |
SVD++ (cache_ratings=False) | 0.919 | 0.721 | 0:01:39 |
SVD++ (cache_ratings=True) | 0.919 | 0.721 | 0:01:22 |
NMF | 0.963 | 0.758 | 0:00:06 |
Slope One | 0.946 | 0.743 | 0:00:09 |
k-NN | 0.98 | 0.774 | 0:00:08 |
Centered k-NN | 0.951 | 0.749 | 0:00:09 |
k-NN Baseline | 0.931 | 0.733 | 0:00:13 |
Co-Clustering | 0.963 | 0.753 | 0:00:06 |
Baseline | 0.944 | 0.748 | 0:00:02 |
Random | 1.518 | 1.219 | 0:00:01 |
Movielens 1M | RMSE | MAE | Time |
---|---|---|---|
SVD | 0.873 | 0.686 | 0:01:07 |
SVD++ (cache_ratings=False) | 0.862 | 0.672 | 0:41:06 |
SVD++ (cache_ratings=True) | 0.862 | 0.672 | 0:34:55 |
NMF | 0.916 | 0.723 | 0:01:39 |
Slope One | 0.907 | 0.715 | 0:02:31 |
k-NN | 0.923 | 0.727 | 0:05:27 |
Centered k-NN | 0.929 | 0.738 | 0:05:43 |
k-NN Baseline | 0.895 | 0.706 | 0:05:55 |
Co-Clustering | 0.915 | 0.717 | 0:00:31 |
Baseline | 0.909 | 0.719 | 0:00:19 |
Random | 1.504 | 1.206 | 0:00:19 |
Installation
With pip (you'll need a C compiler. Windows users might prefer using conda):
$ pip install scikit-surprise
With conda:
$ conda install -c conda-forge scikit-surprise
For the latest version, you can also clone the repo and build the source (you'll first need Cython and numpy):
$ git clone https://github.com/NicolasHug/surprise.git
$ cd surprise
$ pip install .
License and reference
This project is licensed under the BSD 3-Clause license, so it can be used for pretty much everything, including commercial applications.
I'd love to know how Surprise is useful to you. Please don't hesitate to open an issue and describe how you use it!
Please make sure to cite the paper if you use Surprise for your research:
@article{Hug2020,
doi = {10.21105/joss.02174},
url = {https://doi.org/10.21105/joss.02174},
year = {2020},
publisher = {The Open Journal},
volume = {5},
number = {52},
pages = {2174},
author = {Nicolas Hug},
title = {Surprise: A Python library for recommender systems},
journal = {Journal of Open Source Software}
}
Contributors
The following persons have contributed to Surprise:
ashtou, Abhishek Bhatia, bobbyinfj, caoyi, Chieh-Han Chen, Raphael-Dayan, Ðлег Ðемиденко, Charles-Emmanuel Dias, dmamylin, Lauriane Ducasse, Marc Feger, franckjay, Lukas Galke, Tim Gates, Pierre-François Gimenez, Zachary Glassman, Jeff Hale, Nicolas Hug, Janniks, jyesawtellrickson, Doruk Kilitcioglu, Ravi Raju Krishna, lapidshay, Hengji Liu, Ravi Makhija, Maher Malaeb, Manoj K, James McNeilis, Naturale0, nju-luke, Pierre-Louis Pécheux, Jay Qi, Lucas Rebscher, Craig Rodrigues, Skywhat, Hercules Smith, David Stevens, Vesna Tanko, TrWestdoor, Victor Wang, Mike Lee Williams, Jay Wong, Chenchen Xu, YaoZh1918.
Thanks a lot :) !
Development Status
Starting from version 1.1.0 (September 2019), I will only maintain the package, provide bugfixes, and perhaps sometimes perf improvements. I have less time to dedicate to it now, so I'm unabe to consider new features.
For bugs, issues or questions about Surprise, please avoid sending me emails; I will most likely not be able to answer). Please use the GitHub project page instead, so that others can also benefit from it.
Top Related Projects
TensorFlow Recommenders is a library for building recommender system models using TensorFlow.
Fast Python Collaborative Filtering for Implicit Feedback Datasets
A Python implementation of LightFM, a hybrid recommendation algorithm.
A unified, comprehensive and efficient recommendation library
Convert designs to code with AI
Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.
Try Visual Copilot