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 and session-aware recommendation.
The authors developed this framework to carry out the experiments described in:
S. Latifi, N. Mauro and D. Jannach. 2021. Session-aware recommendation: a surprising quest for the state-of-the-art. Information Sciences.
M. Ludewig, N. Mauro, S. Latifi and D. Jannach. 2020. Empirical analysis of session-based recommendation algorithms. User Modeling and User-Adapted Interaction 31 (1), 149-181.
M. Ludewig, N. Mauro, S. Latifi and D. Jannach. Performance comparison of neural and non-neural approaches to session-based recommendation. 2019. Proceedings of the 13th ACM conference on recommender systems, 462-466.
M. Ludewig and D. Jannach. Evaluation of session-based recommendation algorithms. 2018. User Modeling and User-Adapted Interaction 28 (4-5), 331-390.
Parts of the framework and its algorithms are based on code developed and shared by:
Quadrana et al., Personalizing Session-based Recommendations with Hierarchical Recurrent Neural Networks, RecSys 2017. (Original Code).
Ruocco et al., Inter-session modeling for session-based recommendation, DLRS 2017. (Original Code).
Ying et al., Sequential recommender system based on hierarchical attention network, IJCAI 2018. (Original Code).
Liang et al., Neural cross-session filtering: Next-item prediction under intra- and inter-session context, IEEE Intelligent Systems 2019. (Original Code).
Run the following command:
From the main folder run:
If you have a GPU: conda install --yes --file environment_gpu.yml
If you don't have a GPU or you are using Windows: conda install --yes --file environment_cpu.yml
Activate the conda environment: conda activate srec37
Download the repository: https://github.com/rn5l/session-rec.git
Example of Experiments
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:
For session-based models:
example_next.yml to predict the next item in the session.
example_multiple.yml to predict the remaining items of the session.
For session-aware models:
example_session_aware_opt.yml to optimize the models.
example_session_aware_exp.yml to evaluate the models.
At the end of the experiments, you can find the evalutaion results in the "results" folder.
How to Run It
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 Docker:
Run the following command from the main folder:
If you are using Linux and you have a GPU:
./dpython_gpu run_config.py conf/in conf/out
If you are using Linux and you don't have a GPU:
./dpython run_config.py conf/in conf/out
If you are using Windows:
./dpython.bat run_config.py conf/in conf/out
Using Anaconda:
Run the following command from the main folder:
If you are using Linux and you have a GPU:
THEANO_FLAGS="device=cuda0,floatX=float32" CUDA_DEVICE_ORDER=PCI_BUS_ID python run_config.py conf/in conf/out
If you are using Windows or you are using Linux but you don't have a GPU:
python run_config.py conf/in conf/out
Results and run times will be displayed and saved to the results folder as config.
If you want to run a specific configuration file, you have to use:
conf/example_next.yml
instead of:
conf/in conf/out
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 file with the following command using the commands described above based on your OS. For example for Linux users that have a GPU and are using docker:
./dpython_gpu run_preprocessing.py conf/preprocess/window/rsc15.yml
Otherwise, replace ./dpython_gpu with the correct command based on your installation and your OS.
How to Configure It
Start from one of the examples in the conf folder.
Essential Options
Entry
Example
Description
type
window
Values: single (one single training-test split), window (sliding-window protocol), opt (parameters
optimization).
evaluation
evaluation_user_based
Values: for session-aware evaluation: evaluation_user_based (evaluation in term of the next item and in terms of the remaining items of the sessions), for session-based evaluation: 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 configuration files in the conf folder for a list of the
algorithms and their parameters.
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.
Sequence and Time Aware Neighborhood
stan.py
Garg et al., Sequence and time aware neighborhood for session-based recommendations: Stan, SIGIR 2019.
Sequence and Time Aware Neighborhood
vstan.py
It combines ideas from stan and v-sknn in a single approach. Furthermore, it has a sequence-aware item scoring procedure
as well as the IDF weighting scheme from v-sknn.
Session-based Neural Models
Algorithm
File
Description
CSRM
csrm.py
Wang et al., A collaborative session-based recommendation approach with parallel memory modules, SIGIR 2019.
Gru4Rec
gru4rec.py
Hidasi et al., Recurrent Neural Networks with Top-k Gains for Session-based Recommendations, CIKM 2018.
NextItNet
nextitrec.py
Yuan et al., A simple convolutional generative network for next item recommendation, WSDM 2019.
NARM
narm.py
Li et al., Neural Attentive Session-based Recommendation, CIKM 2017.
SR-GNN
gnn.py
Wu et al., Session-based recommendation with graph neural networks, AAAI 2019.
STAMP
STAMP.py
Liu et al., STAMP: Short-Term Attention/Memory Priority Model for Session-based Recommendation, KDD
2018.
Session-aware Neural Models
Algorithm
File
Description
HGru4Rec
hgru4rec.py
Quadrana et al., Method based on the gru4rec algorithm. To model the interactions of a user within a session, it utilizes RNNs based on a single GRU layer, RecSys 2017.
IIRNN
ii_rnn.py
Ruocco et al., Method extending a session-based recommender built on RNN, called intra-session RNN, by using a second RNN that is called inter-session RNN, DLRS 2017.
NCSF
ncfs.py
Hu et al., Method using three encoders to model inter-session context, intra-session context, and to integrate the information of the intra-session context and the inter-session context for item prediction, IEEE Intelligent Systems, 2018.
NSAR
nsar.py
Phuong et al., Method using RNNs to encode session patterns (short-term user preferences) and user embeddings to represent long-term user preferences across session, IEEE Access 2019.
SHAN
shan.py
Ying et al., Model using a two-layer hierarchical attention network to learn a hybrid representation for each user that combines the long-term and short-term preferences, IJCAI 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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent