Surprise

Surprise: A Python library for recommender systems - Published in JOSS (2020)

https://github.com/nicolashug/surprise

Science Score: 95.0%

This score indicates how likely this project is to be science-related based on various indicators:

○
CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 8 DOI reference(s) in README and JOSS metadata
✓
Academic publication links
Links to: joss.theoj.org
✓
Committers with academic emails
1 of 44 committers (2.3%) from academic institutions
○
Institutional organization owner
✓
JOSS paper metadata
Published in Journal of Open Source Software

Keywords

factorization machine-learning matrix recommendation recommender svd systems

Last synced: 4 months ago · JSON representation

Repository

A Python scikit for building and analyzing recommender systems

Basic Info

Host: GitHub
Owner: NicolasHug
License: bsd-3-clause
Language: Python
Default Branch: master
Homepage: http://surpriselib.com
Size: 6.36 MB

Statistics

Stars: 6,655
Watchers: 140
Forks: 1,042
Open Issues: 93
Releases: 0

Topics

factorization machine-learning matrix recommendation recommender svd systems

Created about 9 years ago · Last pushed 5 months ago

Metadata Files

Readme Changelog Contributing License

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.modelselection import crossvalidate

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.

Owner

Name: Nicolas Hug
Login: NicolasHug
Kind: user
Location: London

Website: http://nicolas-hug.com
Twitter: hug_nicolas
Repositories: 5
Profile: https://github.com/NicolasHug

ML engineer, Scikit-learn core-dev, working on PyTorch at Meta AI

JOSS Publication

Surprise: A Python library for recommender systems

Published

August 05, 2020

DOI

10.21105/joss.02174

Volume 5, Issue 52, Page 2174

Authors

Nicolas Hug

Columbia University, Data Science Institute, New York City, New York, United States of America

Editor

Yuan Tang

GitHub Events

Total

Issues event: 5
Watch event: 291
Issue comment event: 16
Push event: 1
Pull request event: 4
Fork event: 38

Last Year

Issues event: 5
Watch event: 291
Issue comment event: 16
Push event: 1
Pull request event: 4
Fork event: 39

Committers

Last synced: 5 months ago

All Time

Total Commits: 620
Total Committers: 44
Avg Commits per committer: 14.091
Development Distribution Score (DDS): 0.097

Past Year

Commits: 0
Committers: 0
Avg Commits per committer: 0.0
Development Distribution Score (DDS): 0.0

Top Committers

Name	Email	Commits
Nicolas Hug	n**g@g**m	560
Nicolas Hug	d**l@l**t	4
PF	t**l@g**m	4
Charles-Emmanuel	C**s@e**r	3
Hengji Liu	h**u@o**m	3
Jannik	6****s	2
Manoj K	5****0	2
Sihyung-Park	t**h@k**r	2
Tim Gates	t**s@i**m	2
Maher Malaeb	m**b@g**m	2
TomatenMarc	m**r@h**e	2
z1mvader	z**r@p**m	2
Jay Qi	j****i	1
James McNeilis	j**1@d**k	1
Hercules Smith	3****s	1
Doruk Kilitcioglu	d**c@g**m	1
Dmitry	d**n@g**m	1
David Stevens	3****h	1
Ashkan	a**i@g**m	1
Aimee C. Chen ✌️	l****h	1
Abhishek Bhatia	3****3	1
Oleg	o**o@g**m	1
verashira	v**a@g**m	1
skywhat	i@s****m	1
nju-luke	n**b@g**m	1
lucas rebscher	L**r@w**e	1
lapidshay	3****y	1
franckjay	f**y@g**m	1
caoyi	c**5@1**m	1
bobbyinfj	r**o@g**m	1
and 14 more...

Committer Domains (Top 20 + Academic)

mike.place: 1 lpag.de: 1 foxmail.com: 1 163.com: 1 skywhat.com: 1 dcs.bbk.ac.uk: 1 hhu.de: 1 iress.com: 1 korea.ac.kr: 1 etu.upmc.fr: 1

Issues and Pull Requests

Last synced: 4 months ago

All Time

Total issues: 86
Total pull requests: 47
Average time to close issues: 2 months
Average time to close pull requests: 6 months
Total issue authors: 83
Total pull request authors: 21
Average comments per issue: 3.24
Average comments per pull request: 0.64
Merged pull requests: 25
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 4
Pull requests: 7
Average time to close issues: N/A
Average time to close pull requests: 1 minute
Issue authors: 4
Pull request authors: 4
Average comments per issue: 1.25
Average comments per pull request: 0.71
Merged pull requests: 0
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

sumit-mandal (2)
SaschaAtOmina (2)
bodymostafa123 (2)
sukalyanM (1)
dongwonmoon (1)
DiegoCorrea (1)
seanv507 (1)
oanaale95 (1)
soliverc (1)
nitayalon (1)
zhenglaizhang (1)
mtilda (1)
benhaf (1)
abdollahpouri (1)
BabulalS (1)

Pull Request Authors

NicolasHug (25)
miguelgfierro (2)
harryw1 (2)
SaschaAtOmina (2)
abhi8893 (2)
mtilda (2)
rodrigc (2)
ProfHercules (2)
mhdthariq (1)
moomoofarm1 (1)
lapidshay (1)
lenatech (1)
Sklavit (1)
sbrnaderi (1)
ppecheux (1)

Top Labels

Issue Labels

enhancement (1)

Pull Request Labels

Packages

Total packages: 4
Total downloads:
- pypi 128,799 last-month
Total docker downloads: 918

Total dependent packages: 5
(may contain duplicates)
Total dependent repositories: 458
(may contain duplicates)
Total versions: 48
Total maintainers: 1

pypi.org: scikit-surprise

An easy-to-use library for recommender systems.

Documentation: https://scikit-surprise.readthedocs.io/
License: Copyright (c) 2016, Nicolas Hug All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Latest release: 1.1.4
published over 1 year ago

Versions: 12
Dependent Packages: 5
Dependent Repositories: 453
Downloads: 128,799 Last month
Docker Downloads: 918

Rankings

Dependent repos count: 0.7%

Downloads: 0.9%

Average: 1.1%

Dependent packages count: 1.3%

Docker downloads count: 1.6%

Maintainers (1)

NicolasHug

Last synced: 4 months ago

proxy.golang.org: github.com/NicolasHug/Surprise

Documentation: https://pkg.go.dev/github.com/NicolasHug/Surprise#section-documentation
License: bsd-3-clause
Latest release: v1.1.4
published over 1 year ago

Versions: 14
Dependent Packages: 0
Dependent Repositories: 1

Rankings

Stargazers count: 0.9%

Forks count: 0.9%

Average: 4.0%

Dependent repos count: 4.7%

Dependent packages count: 9.6%

Last synced: 4 months ago

proxy.golang.org: github.com/nicolashug/surprise

Documentation: https://pkg.go.dev/github.com/nicolashug/surprise#section-documentation
License: bsd-3-clause
Latest release: v1.1.4
published over 1 year ago

Versions: 14
Dependent Packages: 0
Dependent Repositories: 0

Rankings

Dependent packages count: 7.0%

Average: 8.2%

Dependent repos count: 9.3%

Last synced: 4 months ago

conda-forge.org: scikit-surprise

Homepage: http://surpriselib.com
License: BSD-3-Clause
Latest release: 1.1.3
published over 3 years ago

Versions: 8
Dependent Packages: 0
Dependent Repositories: 4

Rankings

Stargazers count: 4.6%

Forks count: 4.9%

Dependent repos count: 16.1%

Average: 19.3%

Dependent packages count: 51.6%

Last synced: 4 months ago

Dependencies

.github/workflows/benchmarks.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite

.github/workflows/build_docs.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite
actions/upload-artifact v3 composite

.github/workflows/build_sdist.yml actions

actions/checkout v3 composite
actions/download-artifact v3 composite
actions/setup-python v3 composite
actions/upload-artifact v3 composite

.github/workflows/lint.yml actions

actions/checkout v3 composite
actions/setup-python v3 composite

setup.py pypi

line.strip *

doc/requirements.txt pypi

pandas *
sphinx *
sphinx_rtd_theme *
sphinxcontrib-bibtex *
sphinxcontrib-spelling *

pyproject.toml pypi

joblib >=1.2.0
numpy >=1.19.5
scipy >=1.6.0

Surprise

Science Score: 95.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

Overview

Getting started, example

Load the movielens-100k dataset (download it if needed).

Use the famous SVD algorithm.

Run 5-fold cross-validation and print results.

Benchmarks

Installation

License and reference

Contributors

Development Status

Owner

JOSS Publication

Surprise: A Python library for recommender systems

Authors

Editor

Tags

GitHub Events

Total

Last Year

Committers

All Time

Past Year

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: scikit-surprise

Rankings

Maintainers (1)

proxy.golang.org: github.com/NicolasHug/Surprise

Rankings

proxy.golang.org: github.com/nicolashug/surprise

Rankings

conda-forge.org: scikit-surprise

Rankings

Dependencies