Skip to content

Commit

Permalink
Changed name RecSys to surprise.
Browse files Browse the repository at this point in the history
  • Loading branch information
NicolasHug committed Nov 22, 2016
1 parent 55b39a6 commit fa8adbd
Show file tree
Hide file tree
Showing 60 changed files with 307 additions and 301 deletions.
6 changes: 3 additions & 3 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ doc/build
.ipynb_checkpoints/
.cache/

recsys.egg-info/
surprise.egg-info/
build
dist/
recsys/similarities.c
recsys/prediction_algorithms/matrix_factorization.c
surprise/similarities.c
surprise/prediction_algorithms/matrix_factorization.c
*.so
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
CURRENT
=======

* Changed name from recsys to surprise
* Improved printing of accuracy measures.
* Added version number.
* Rewrote the the __main__.py
Expand Down
2 changes: 1 addition & 1 deletion MANIFEST.in
Original file line number Diff line number Diff line change
Expand Up @@ -3,4 +3,4 @@ include LICENSE.md
include requirements.txt
recursive-include doc *
recursive-include examples *
recursive-include recsys *.c *.pyx
recursive-include surprise *.c *.pyx
61 changes: 32 additions & 29 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,73 +1,76 @@
[![GitHub
version](https://badge.fury.io/gh/nicolashug%2Frecsys.svg)](https://nicolashug.github.io/RecSys/)
[![Documentation Status](https://readthedocs.org/projects/recsys/badge/?version=latest)](http://recsys.readthedocs.io/en/latest/?badge=latest)
version](https://badge.fury.io/gh/nicolashug%2Fsurprise.svg)](https://nicolashug.github.io/Surprise/)
[![Documentation Status](https://readthedocs.org/projects/surprise/badge/?version=latest)](http://surprise.readthedocs.io/en/latest/?badge=latest)
[![Build
Status](https://travis-ci.org/NicolasHug/RecSys.svg?branch=master)](https://travis-ci.org/NicolasHug/RecSys)
Status](https://travis-ci.org/NicolasHug/Surprise.svg?branch=master)](https://travis-ci.org/NicolasHug/Surprise)
[![python_versions](https://img.shields.io/badge/python-2.7%2C%203.5-blue.svg)]
(https://nicolashug.github.io/RecSys/)
[![license](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://github.com/NicolasHug/RecSys/blob/master/LICENSE.md)
(https://nicolashug.github.io/Surprise/)
[![license](https://img.shields.io/badge/license-GPLv3-blue.svg)](https://github.com/NicolasHug/Surprise/blob/master/LICENSE.md)


RecSys
======
Surprise
========

Overview
--------

[RecSys](https://NicolasHug.github.io/RecSys/) is an open source Python library
[Surprise](https://NicolasHug.github.io/Surprise/) is an open source Python library
that provides with tools to build and evaluate the performance of many
recommender system prediction algorithms. Its goal is to make life easy(-ier)
for reseachers, teachers and students who want to play around with new
recommender algorithms ideas and teach/learn more about recommender systems.

[RecSys](https://NicolasHug.github.io/RecSys/) **was designed with the following
[Surprise](https://NicolasHug.github.io/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](http://recsys.readthedocs.io/en/latest/index.html), which we
[documentation](http://surprise.readthedocs.io/en/latest/index.html), 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](http://recsys.readthedocs.io/en/latest/getting_started.html#load-a-custom-dataset).
handling](http://surprise.readthedocs.io/en/latest/getting_started.html#load-a-custom-dataset).
Users can use both *built-in* datasets
([Movielens](http://grouplens.org/datasets/movielens/),
[Jester](http://eigentaste.berkeley.edu/dataset/)), and their own *custom* datasets.
- Provide with various ready-to-use [prediction
algorithms](http://recsys.readthedocs.io/en/latest/prediction_algorithms_package.html) (Neighborhood approaches, SVD, SVD++...)
algorithms](http://surprise.readthedocs.io/en/latest/prediction_algorithms_package.html) (Neighborhood approaches, SVD, SVD++...)
- Make it easy to implement [new algorithm
ideas](http://recsys.readthedocs.io/en/latest/building_custom_algo.html).
- Provide with tools to [evaluate](http://recsys.readthedocs.io/en/latest/evaluate.html),
[analyse](http://nbviewer.jupyter.org/github/NicolasHug/RecSys/tree/master/examples/notebooks/KNNBasic_analysis.ipynb/)
ideas](http://surprise.readthedocs.io/en/latest/building_custom_algo.html).
- Provide with tools to [evaluate](http://surprise.readthedocs.io/en/latest/evaluate.html),
[analyse](http://nbviewer.jupyter.org/github/NicolasHug/Surprise/tree/master/examples/notebooks/KNNBasic_analysis.ipynb/)
and
[compare](http://nbviewer.jupyter.org/github/NicolasHug/RecSys/tree/master/examples/notebooks/Compare.ipynb/)
[compare](http://nbviewer.jupyter.org/github/NicolasHug/Surprise/tree/master/examples/notebooks/Compare.ipynb/)
the algorithms performance. Cross-validation procedures can be run very easily.

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

Installation / Usage
--------------------

The easiest way is to use pip (you'll need [numpy](http://www.numpy.org/)):

$ pip install recsys
$ pip install surprise

Or you can clone the repo and build the source (you'll need
[Cython](http://cython.org/) and [numpy](http://www.numpy.org/)):

$ git clone https://github.com/NicolasHug/recsys.git
$ git clone https://github.com/NicolasHug/surprise.git
$ python setup.py install

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](http://recsys.readthedocs.io/en/latest/matrix_factorization.html#recsys.prediction_algorithms.matrix_factorization.SVD)
[SVD](http://surprise.readthedocs.io/en/latest/matrix_factorization.html#surprise.prediction_algorithms.matrix_factorization.SVD)
algorithm.

```python
from recsys import SVD
from recsys import Dataset
from recsys import evaluate
from surprise import SVD
from surprise import Dataset
from surprise import evaluate


# Load the movielens-100k dataset (download it if needed),
Expand Down Expand Up @@ -102,18 +105,18 @@ All experiments are run on a laptop with Intel Core i3 1.7 GHz, 4Go Ram.

| | RMSE | MAE | Time (s) |
|-----------------|:------:|:------:|:--------:|
| [NormalPredictor](http://recsys.readthedocs.io/en/latest/basic_algorithms.html#recsys.prediction_algorithms.random_pred.NormalPredictor) | 1.5228 | 1.2242 | 4 |
| [BaselineOnly](http://recsys.readthedocs.io/en/latest/basic_algorithms.html#recsys.prediction_algorithms.baseline_only.BaselineOnly) | .9445 | .7488 | 16 |
| [KNNBasic](http://recsys.readthedocs.io/en/latest/knn_inspired.html#recsys.prediction_algorithms.knns.KNNBasic) | .9789 | .7732 | 27 |
| [KNNWithMeans](http://recsys.readthedocs.io/en/latest/knn_inspired.html#recsys.prediction_algorithms.knns.KNNWithMeans) | .9514 | .7500 | 30 |
| [KNNBaseline](http://recsys.readthedocs.io/en/latest/knn_inspired.html#recsys.prediction_algorithms.knns.KNNBaseline) | .9306 | .7334 | 44 |
| [SVD](http://recsys.readthedocs.io/en/latest/matrix_factorization.html#recsys.prediction_algorithms.matrix_factorization.SVD) | .9392 | .7409 | 46 |
| [NormalPredictor](http://surprise.readthedocs.io/en/latest/basic_algorithms.html#surprise.prediction_algorithms.random_pred.NormalPredictor) | 1.5228 | 1.2242 | 4 |
| [BaselineOnly](http://surprise.readthedocs.io/en/latest/basic_algorithms.html#surprise.prediction_algorithms.baseline_only.BaselineOnly) | .9445 | .7488 | 16 |
| [KNNBasic](http://surprise.readthedocs.io/en/latest/knn_inspired.html#surprise.prediction_algorithms.knns.KNNBasic) | .9789 | .7732 | 27 |
| [KNNWithMeans](http://surprise.readthedocs.io/en/latest/knn_inspired.html#surprise.prediction_algorithms.knns.KNNWithMeans) | .9514 | .7500 | 30 |
| [KNNBaseline](http://surprise.readthedocs.io/en/latest/knn_inspired.html#surprise.prediction_algorithms.knns.KNNBaseline) | .9306 | .7334 | 44 |
| [SVD](http://surprise.readthedocs.io/en/latest/matrix_factorization.html#surprise.prediction_algorithms.matrix_factorization.SVD) | .9392 | .7409 | 46 |

Documentation, Getting Started
------------------------------

The documentation with many other usage examples is [available
online](http://recsys.readthedocs.io/en/latest/index.html) on ReadTheDocs.
online](http://surprise.readthedocs.io/en/latest/index.html) on ReadTheDocs.

License
-------
Expand Down
2 changes: 1 addition & 1 deletion doc/source/accuracy.rst
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ accuracy module
===================


.. automodule:: recsys.accuracy
.. automodule:: surprise.accuracy
:members:
:undoc-members:
:show-inheritance:
2 changes: 1 addition & 1 deletion doc/source/algobase.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
The algorithm base class
------------------------

.. automodule:: recsys.prediction_algorithms.algo_base
.. automodule:: surprise.prediction_algorithms.algo_base
:members:
4 changes: 2 additions & 2 deletions doc/source/basic_algorithms.rst
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@ Basic algorithms
These are basic algorithm that do not do much work but that are still useful
for comparing accuracies.

.. autoclass:: recsys.prediction_algorithms.random_pred.NormalPredictor
.. autoclass:: surprise.prediction_algorithms.random_pred.NormalPredictor
:show-inheritance:

.. autoclass:: recsys.prediction_algorithms.baseline_only.BaselineOnly
.. autoclass:: surprise.prediction_algorithms.baseline_only.BaselineOnly
:show-inheritance:

39 changes: 20 additions & 19 deletions doc/source/building_custom_algo.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
How to build you own prediction algorithm
=========================================

This page describes how to build a custom prediction algorithm using RecSys.
This page describes how to build a custom prediction algorithm using Surprise.

The basics
~~~~~~~~~~
Expand All @@ -12,10 +12,10 @@ Want to get your hands dirty? Cool.

Creating your own prediction algorithm is pretty simple: an algorithm is
nothing but a class derived from :class:`AlgoBase
<recsys.prediction_algorithms.algo_base.AlgoBase>` that has an ``estimate``
<surprise.prediction_algorithms.algo_base.AlgoBase>` that has an ``estimate``
method. This is the method that is called by the :meth:`predict()
<recsys.prediction_algorithms.algo_base.AlgoBase.predict>` method. It takes in
an **inner** user id, an **inner** item id (see :ref:`this note
<surprise.prediction_algorithms.algo_base.AlgoBase.predict>` method. It takes
in an **inner** user id, an **inner** item id (see :ref:`this note
<raw_inner_note>`), and returns the estimated rating :math:`\hat{r}_{ui}`:

.. literalinclude:: ../../examples/building_custom_algorithms/most_basic_algorithm.py
Expand All @@ -36,8 +36,8 @@ return a dictionary with given details: ::
return 3, details

This dictionary will be stored in the :class:`prediction
<recsys.prediction_algorithms.predictions.Prediction>` as the ``details`` field and
can be used for later analysis.
<surprise.prediction_algorithms.predictions.Prediction>` as the ``details``
field and can be used for later analysis.



Expand All @@ -56,19 +56,19 @@ be done by defining the ``train`` method:


The ``train`` method is called by the :func:`evaluate
<recsys.evaluate.evaluate>` function at each fold of a cross-validation
<surprise.evaluate.evaluate>` function at each fold of a cross-validation
process, (but you can also :ref:`call it yourself <iterate_over_folds>`).
Before doing anything, you should call the base class :meth:`train()
<recsys.prediction_algorithms.algo_base.AlgoBase.train>` method.
<surprise.prediction_algorithms.algo_base.AlgoBase.train>` method.

The ``trainset`` attribute
~~~~~~~~~~~~~~~~~~~~~~~~~~

Once the base class :meth:`train()
<recsys.prediction_algorithms.algo_base.AlgoBase.train>` method has returned, all
the info you need about the current training set (rating values, etc...) is
<surprise.prediction_algorithms.algo_base.AlgoBase.train>` method has returned,
all the info you need about the current training set (rating values, etc...) is
stored in the ``self.trainset`` attribute. This is a :class:`Trainset
<recsys.dataset.Trainset>` object that has many attributes and methods of
<surprise.dataset.Trainset>` object that has many attributes and methods of
interest for prediction.

To illustrate its usage, let's make an algorithm that predicts an average
Expand All @@ -90,15 +90,16 @@ When the prediction is impossible
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

It's up to your algorithm to decide if it can or cannot yield a prediction. If
the prediction is impossible, then you can raise the :class:`PredictionImpossible
<recsys.prediction_algorithms.predictions.PredictionImpossible>` exception.
the prediction is impossible, then you can raise the
:class:`PredictionImpossible
<surprise.prediction_algorithms.predictions.PredictionImpossible>` exception.
You'll need to import it first): ::

from recsys import PredictionImpossible
from surprise import PredictionImpossible


This exception will be caught by the :meth:`predict()
<recsys.prediction_algorithms.algo_base.AlgoBase.predict>` method, and the
<surprise.prediction_algorithms.algo_base.AlgoBase.predict>` method, and the
estimation :math:`\hat{r}_{ui}` will be set to the global mean of all ratings
:math:`\mu`.

Expand All @@ -111,10 +112,10 @@ need to accept ``bsl_options`` and ``sim_options`` as parmeters to the
these parameters in the :ref:`prediction_algorithms` section.

Methods :meth:`compute_baselines()
<recsys.prediction_algorithms.algo_base.AlgoBase.compute_baselines>` and
<surprise.prediction_algorithms.algo_base.AlgoBase.compute_baselines>` and
:meth:`compute_similarities()
<recsys.prediction_algorithms.algo_base.AlgoBase.compute_similarities>` can be
called in the ``train`` method (or anywhere else).
<surprise.prediction_algorithms.algo_base.AlgoBase.compute_similarities>` can
be called in the ``train`` method (or anywhere else).

.. literalinclude:: ../../examples/building_custom_algorithms/with_baselines_or_sim.py
:caption: From file ``examples/building_custom_algorithms/.with_baselines_or_sim.py``
Expand All @@ -123,5 +124,5 @@ called in the ``train`` method (or anywhere else).


Feel free to explore the prediction_algorithms package `source
<https://github.com/NicolasHug/RecSys/tree/master/recsys/prediction_algorithms>`_
<https://github.com/NicolasHug/Surprise/tree/master/surprise/prediction_algorithms>`_
to get an idea of what can be done.
14 changes: 7 additions & 7 deletions doc/source/conf.py
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# RecSys documentation build configuration file, created by
# Surprise documentation build configuration file, created by
# sphinx-quickstart on Tue Dec 29 20:08:18 2015.
#
# This file is execfile()d with the current directory set to its
Expand Down Expand Up @@ -56,7 +56,7 @@
master_doc = 'index'

# General information about the project.
project = 'RecSys'
project = 'Surprise'
copyright = '2015, Nicolas Hug'
author = 'Nicolas Hug'

Expand Down Expand Up @@ -215,7 +215,7 @@
#html_search_scorer = 'scorer.js'

# Output file base name for HTML help builder.
htmlhelp_basename = 'RecSysdoc'
htmlhelp_basename = 'Surprisedoc'

# -- Options for LaTeX output ---------------------------------------------

Expand All @@ -237,7 +237,7 @@
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'RecSys.tex', 'RecSys Documentation',
(master_doc, 'Surprise.tex', 'Surprise Documentation',
'Nicolas Hug', 'manual'),
]

Expand Down Expand Up @@ -267,7 +267,7 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'recsys', 'RecSys Documentation',
(master_doc, 'surprise', 'Surprise Documentation',
[author], 1)
]

Expand All @@ -281,8 +281,8 @@
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'RecSys', 'RecSys Documentation',
author, 'RecSys', 'One line description of project.',
(master_doc, 'Surprise', 'Surprise Documentation',
author, 'Surprise', 'One line description of project.',
'Miscellaneous'),
]

Expand Down
2 changes: 1 addition & 1 deletion doc/source/dataset.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
dataset module
===================

.. automodule:: recsys.dataset
.. automodule:: surprise.dataset
:members:
:exclude-members: BuiltinDataset, read_ratings, DatasetUserFolds,
parse_line
2 changes: 1 addition & 1 deletion doc/source/dump.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,5 +3,5 @@
dump module
===============

.. automodule:: recsys.dump
.. automodule:: surprise.dump
:members:
2 changes: 1 addition & 1 deletion doc/source/evaluate.rst
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@
evaluate module
===============

.. automodule:: recsys.evaluate
.. automodule:: surprise.evaluate
:members:
:exclude-members: CaseInsensitiveDefaultDict
Loading

0 comments on commit fa8adbd

Please sign in to comment.