Awesome

Collaborative filtering based on sequences

This python library includes multiple collaboraborative filtering algorithm that make use of the sequence of actions of the user: they not only use the fact that a user rated a certain item, but also that he rated before this other item or after that other one. Some standard algorithms that do not use sequence information are also present for easier comparison.

All those algorithms aims to solve the "item recommendation" or "top-N recommendation" problem, which mean that they are not designed to predict ratings values, but only to predict which items are of interest for a given user.

Our code was used to produce the experiments in "Collaborative Filtering with Recurrent Neural Networks" and "Long and Short-Term Recommendations with Recurrent Neural Networks". If you use this code in your research, please cite us:

@inproceedings{Rec_with_RNN,
 author = {Devooght, Robin and Bersini, Hugues},
 title = {Long and Short-Term Recommendations with Recurrent Neural Networks},
 booktitle = {Proceedings of the 25th Conference on User Modeling, Adaptation and Personalization},
 series = {UMAP '17},
 year = {2017},
 isbn = {978-1-4503-4635-1},
 location = {Bratislava, Slovakia},
 pages = {13--21},
 numpages = {9},
 url = {http://doi.acm.org/10.1145/3079628.3079670},
 doi = {10.1145/3079628.3079670},
 acmid = {3079670},
 publisher = {ACM},
} 

Installation

The library has many dependencies: numpy/scipy, theano and lasagne for the neural networks, Gensim for word2vec and pandas for the data manipulation.

Numpy, scipy and Theano can be sometimes difficult to install, and we recommend looking at Theano's installation tutorial: http://deeplearning.net/software/theano/install.html Gensim and pandas are easily installed with pip. Lasagne is also installed with pip but you have to specify the version >=0.2.dev1.

On Ubuntu, the following commands should install everything that you need:

sudo apt-get install python-numpy python-scipy python-dev python-pip python-nose g++ libopenblas-dev git
sudo pip install Theano pandas gensim https://github.com/Lasagne/Lasagne/archive/master.zip

Usage

The library is designed to be used in command line through three scripts:

• preprocess.py for the preparation of the dataset
• train.py for training models
• test.py for testing models

calling these scripts with the --help option will display the available options (e.g. python preprocess.py --help).

preprocess.py

This script takes a file containing a dataset of user/item interactions and split it into training/validation/test sets and save them in the format used by train.py and test.py. The original dataset must be in a format where each line correspond to a single user/item interaction.

The only required argument is -f path/to/dataset, which is used to specify the original dataset. The script will create subfolders named "data", "models" and "results" in the folder containing the original dataset. "data" is used by preprocess.py to store all the files it produces, "models" is used by train.py to store the trained models and "results" is used by test.py to store the results of the tests.

The optional arguments are the following:

Example 1

In the movielens 1M dataset each line has the following format:

UserID::MovieID::Rating::Timestamp

To process it you have to specify the order of the columns, in this case uirt (for user, item, rating, timestamp), and the separator ("::"). If you want to use a hundred users for the validation set and a hundred others for the test set, you'll have to use the following command:

python preprocess.py -f path/to/ratings.dat --columns uirt --sep :: --val_size 100 --test_size 100

Example 2

Consider a dataset where each line has the following format:

timestamp, user_id, some_useless_data, item_id, more_useless_data

You can specify the order of columns with "tuxiy" where x and y are placeholder names for the columns that will be discarted by the script. Using "tuxi" will also work, as all the columns not mentioned are discarded. As no rating column is present, each interaction will recieve the rating "1". If you also want for example to remove users with less than 10 interactions, use the following command:

python preprocess.py -f path/to/file --columns tuxi --min_user_activity 10

train.py

This script is used to train models and offers many options regarding when to save new models and when to stop training. The basic usage is the following:

python train.py -d path/to/dataset/ -m Method_name

The argument -d is used to specify the path to the folder that contains the "data", "models" and "results" subfolders created by preprocess.py. If you have multiple datasets with a partly common path (e.g. path/to/dataset1/, path/to/dataset2/, etc.) you can specify this common path in the variable DEFAULT_DIR of helpers/data_handling.py. For example, setting DEFAULT_DIR = "path/to/" and using the argument -d dataset1 will look for the dataset in "path/to/dataset1/".

The optional arguments are the following:

The options specific to each method are explained in the Methods section.

test.py

This script test the models built with train.py on the test set. The basic usage is:

python test.py -d path/to/dataset/ -m Method_name

The argument -d works in the same way as with train.py, and the precise model to test is specified by the --dir option and the methods-specific options. If multiple models fit the options (They are in the same subfolder and were trained with the same method and same options), they are all evaluated one after the other, except if the argument -i epoch_number is also specified, which will then select the model based on the number of epochs.

--metrics allows to specify the list of metrics to compute, separated by commas. By default the metrics are: sps, recall, item_coverage, user_coverage, blockbuster_share. The "blockbuster share" is the percentage of correct recommendations among the 1% most popular items. The other available metrics are the sps, the ndcg and the assr (when clustering is used).

All the metrics are computed "@k", with k=10 by default. k can be changed using the -k option.

When the --save option is used, the results are saved in a file in "path/to/dataset/results/". the results of each model form a line of the file, and each line contains the number of epochs followed by the metrics specified by --metrics.

When testing a method based on clustering, the option --ignore_clusters can be used to test how the method performs without clusters.

Methods

The available methods are:

• Recurrent Neural Networks
• Stacked Denoising Autoencoder
• Latent Tarjectory Modeling/word2vec
• BPR-MF
• FPMC
• FISM
• Fossil
• Markov Chains
• User KNN
• Popularity baseline

Neural Networks

Recurrent Neural Networks

Use it with -m RNN. The RNN have many options allowing to change the type/size/number of layers, the training procedure and the objective function, and some options are specific to a particular objective function.

Layers

Update mechanism

Noise

Other options

Objective functions

Clustering

It is possible to combine RNNs with an item-clustering method. This leads to faster prediction on large dataset and creates meaningful item clusters. In order to use it, use the option --clusters nb_of_clusters.
For example, python train.py -d path/to/dataset/ -m RNN --loss BPR --clusters 10 will train an RNN with the BPR loss and 10 clusters of items. Note that the clustering is only compatible with sampling-based loss (BPR, Blackout and TOP1). It also works with --loss CCE, but a sampling version of CCE is then used instead of the normal categorical cross-entropy.

Stacked Denoising Autoencoders

Use it with -m SDAE. SDAE the RNN options described in "Update mechanism" and "Other options".

Latent Trajectory Modeling

Use it with -m LTM. LTM is a method based on word2vec, described in "Latent Trajectory Modeling: A Light and Efficient Way to Introduce Time in Recommender Systems". LTM works in two steps: it first produces an embedding of the items with the word2vec algorithm using the sequence of items in the training set, then it estimates for each user a translation vector that would best explain the trajectory of that user in the embedded space. Predictions are made by finding the closest items to the last user item translated by the user's translation vector. Our implementation is mainly a wrapper around Gensim's word2vec implementation.

Factorization-based

FPMC

FPMC is a method combining factorized markov chains with the factorization of the user-item matrix (see "Factorizing personalized Markov chains for next-basket recommendation" by Rendle et al. in Proceedings of WWW'10). Use it with -m FPMC

BPR-MF

BPR-MF is a matrix factorization method based on the BPR loss (see "BPR: Bayesian personalized ranking from implicit feedback" by Rendle et al. in Proceedings of the twenty-fifth conference on uncertainty in artificial intelligence) Use it with -m BPRMF

FISM

FISM is a method based of item-item factorization (see "Fism: factored item similarity models for top-n recommender systems" by Kabbur et al. in Proceedings of SIGKDD'13). It has the advantage over BPR-MF that it does not build a representation for each user. This leads to smaller models, and the ability to make recommendation to new users. Use it with -m FISM --loss [BPR, RMSE]

FISM can be combined with item-clustering the same way that RNN can. To do so, add the option --clusters nb_of_clusters. When using clustering, a completely different implementation is used, which is based on Theano instead of Numpy. This has some implications on the available options:

• The loss must be choosen among CCE, BPR, Blackout and TOP1 instead of BPR and RMSE.
• The number of samples for each training step can be specified using --sampling nb_of_samples.
• The update mechanism is controled by the options defined in Update mechanism instead of -l and --cooling.

Fossil

Fossil combines FISM with factorized markov chains (see "Fusing Similarity Models with Markov Chains for Sparse Sequential Recommendation" by He and McAuley in Proceedings of ICDM'16). Unlike FPMC, Fossil can use higher-order markov chains. Use it with -m Fossil

Lazy

Lazy methods do not build models, they make recommendation directly based on the dataset. They should therefor not be used with train.py, but only with test.py.

POP

Use it with -m POP. Always predict the most popular items.

Markov Chain

Use it with -m MM. Recommends the items that follow most often the last item the user's sequence.

User KNN

Use it with -m UKNN. User-based nearest neighbors approach. The similarity measure between users is the cosine similarity: #number-of-common-items / sqrt(#number-of-items-of-user-a * #number-of-items-of-user-b).