Python-based framework for building and evaluating session-based recommender systems.
Python
session-rec
Introduction
session-rec is a Python-based framework for building and evaluating recommender systems (Python 3.5.x). It
implements a suite of state-of-the-art
algorithms and baselines for session-based recommendation.
Parts of the framework and its algorithms are based on code developed and shared by:
Rendle et al., BPR: Bayesian Personalized Ranking from Implicit Feedback, UAI 2009. (Original Code).
Mi et al., Context Tree for Adaptive Session-based Recommendation, 2018. (Code shared by the authors).
Hidasi et al., Recurrent Neural Networks with Top-k Gains for Session-based Recommendations, CoRR
abs/1706.03847, 2017. (Original Code).
Liu et al., STAMP: Short-Term Attention/Memory Priority Model for Session-based Recommendation, KDD
2018. (Original Code).
Li et al., Neural Attentive Session-based Recommendation, CIKM 2017. (Original Code).
Yuan et al., A Simple but Hard-to-Beat Baseline for Session-based Recommendations, CoRR
abs/1808.05163, 2018. (Code shared by the authors).
Rendle et al., Factorizing Personalized Markov Chains for Next-basket Recommendation. WWW 2010. (Original
Code).
Kabbur et al., FISM: Factored Item Similarity Models for top-N Recommender Systems, KDD 2013. (Original
Code).
He and McAuley. Fusing Similarity Models with Markov Chains for Sparse Sequential Recommendation.
CoRR abs/1609.09152, 2016. (Original
Code).
Requirements
To run session-rec, the following libraries are required:
The data folder contains a small sample dataset. It's possible to have an overview of how the framework works by using as a configuration file:
example_next.yml to predict the next item in the session.
example_multiple.yml to predict the remaining items of the session.
At the end of the experiments, you can find the evalutaion results in the "results" folder. You can also find the list of recommended items under the "results" folder with the suffix "Saver@".
How to Run It
Dataset preprocessing
Unzip any dataset file to the data folder, i.e., rsc15-clicks.dat will then be in the folder
data/rsc15/raw
Open and edit any configuration file in the folder conf/preprocess/.. to configure the preprocessing method and parameters.
See, e.g., conf/preprocess/window/rsc15.yml for an example with comments.
Run a configuration with the following command:
./dpython run_preprocesing.py conf/preprocess/window/rsc15.yml
Run experiments using the configuration file
Create folders conf/in and conf/out. Configure a configuration file *.yml and put it into the folder named conf/in. Examples of configuration
files are listed in the conf folder. It is possible to configure multiple files and put them all in
the conf/in folder. When a configuration file in conf/in has been executed, it will be moved to the folder conf/out.
Using Anaconda:
Run the following command from the main folder:
python run_config.py conf/in conf/out
If you want to run a specific configuration file, run the following command:
python run_config.py conf/example_next.yml
Using Docker:
Run the following command from the main folder:
./dpython run_config.py conf/in conf/out
If you want to run a specific configuration file, run the following command:
./dpython run_config.py conf/example_next.yml
Results and run times will be displayed and saved to the results folder as config.
How to Configure It
Start from one of the examples in the conf folder.
Essential Options
Entry
Example
Description
type
single
Values: single (one single training-test split), window (sliding-window protocol), opt (parameters
optimization).
evaluation
evaluation_multiple
Values: evaluation (evaluation in term of the next item), evaluation_last (evaluation in term of the
last item of the session), evaluation_multiple (evaluation in terms of the remaining items of the
sessions).
slices
5
Number of slices for the window protocol.
opts
opts: {sessions_test: 10}
Number of sessions used as a test during the optimization phase.
metrics
-class: accuracy.HitRate
length: [5,10,15,20]
List of accuracy measures (HitRate, MRR, Precision, Recall, MAP, Coverage, Popularity,
Time_usage_training, Time_usage_testing, Memory_usage).
If you want to save the files with the recommedation lists use the option: - class: saver.Saver
length: [50]
It's possible to use the saved recommendations using the ResultFile class.
opts
opts: {sessions_test: 10}
Number of session used as a test during the optimization phase.
See the example.yml, example_opt.yml and example_hybrid_opt.yml for a complete list of the
algorithms and their parameters.
How to extend it
Make your new algorithm class.
Write the following functions:
__init__()
fit()
predict_next()
clear()
Tip: look at the implementation of a baseline (e.g.: ar.py).
Algorithms
Baselines
Algorithm
File
Description
Association Rules
ar.py
Simplified version of the association rule mining technique with a maximum rule size of two.
Markov Chains
markov.py
Variant of association rules with a focus on sequences in the data. The rules are extracted from a
first-order Markov Chain.
Sequential Rules
sr.py
Variation of mc or ar respectively. It also takes the order of actions into account, but in a less
restrictive manner.
BPR-MF
bpr.py
Rendle et al., BPR: Bayesian Personalized Ranking from Implicit Feedback, UAI 2009.
Context Tree
ct.py
Mi et al., Context Tree for Adaptive Session-based Recommendation, 2018.
Nearest Neighbors
Algorithm
File
Description
Item-based kNN
iknn.py
Considers the last element in a given session and then returns those items as recommendations that
are most similar to it in terms of their co-occurrence in other sessions.
Session-based kNN
sknn.py
Recommend items from the most similar sessions, where session distance is determined with the cosine similarity function or the jaccard index.
Vector Multiplication Session-Based kNN
vsknn.py
More emphasis on the more recent events of a session when computing the similarities. The weights of
the other elements are determined using a linear decay function that
depends on the position of the element within the session, where elements appearing earlier in the
session obtain a lower weight.
Neural Networks
Algorithm
File
Description
Gru4Rec
gru4rec.py
Hidasi et al., Recurrent Neural Networks with Top-k Gains for Session-based Recommendations, CoRR
abs/1706.03847, 2017.
STAMP
STAMP.py
Liu et al., STAMP: Short-Term Attention/Memory Priority Model for Session-based Recommendation, KDD
2018.
NARM
narm.py
Li et al., Neural Attentive Session-based Recommendation, CIKM 2017.
NextItNet
nextitrec.py
Yuan et al., A Simple but Hard-to-Beat Baseline for Session-based Recommendations, CoRR
abs/1808.05163, 2018.
Factorization-based Methods
Algorithm
File
Description
Factorized Personalized Markov Chains
fpmc.py
Rendle et al., Factorizing Personalized Markov Chains for Next-basket Recommendation. WWW 2010.
Factored Item Similarity Models
fism.py
Kabbur et al., FISM: Factored Item Similarity Models for top-N Recommender Systems, KDD 2013.
Factorized Sequential Prediction with Item Similarity Models
fossil.py
He and McAuley. Fusing Similarity Models with Markov Chains for Sparse Sequential Recommendation.
CoRR abs/1609.09152, 2016.
Session-based Matrix Factorization
smf.py
It combines factorized Markov chains with classic matrix factorization. In
addition, the method considers the
cold-start situation of session-based recommendation scenarios.