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.

• 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).
• Phuong et al., Neural session-aware recommendation, IEEE Access 2019. (Original Code).
• 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).
• Wu et al., Session-based recommendation with graph neural networks, AAAI, 2019. (Original Code).
• Wang et al., A collaborative session-based recommendation approach with parallel memory modules, SIGIR, 2019. (Original Code).
• 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).

• Anaconda 4.X (Python 3.5)
• Pympler
• NumPy
• SciPy
• BLAS
• Sklearn
• Dill
• Pandas
• Theano
• Pyyaml
• CUDA
• Tensorflow
• Theano
• Psutil
• Scikit-learn
• Tensorflow-gpu
• NetworkX
• Certifi
• NumExpr
• Pytables
• Python-dateutil
• Pytz
• Six
• Keras
• Scikit-optimize
• Python-telegram-bot

1. Download and Install Docker (https://www.docker.com/)
2. Run the following commands:
   1. If you are using Windows or you are using Linux but you don't have a GPU: docker pull maltel/session-rec-cpu:v1
   2. If you are using LINUX and you have a GPU: docker pull maltel/session-rec-gpu:v1
3. Download the repository: https://github.com/rn5l/session-rec.git

1. Download and Install Anaconda (https://www.anaconda.com/distribution/)
2. Run the following command:
   From the main folder run:
   
   1. If you have a GPU: conda install --yes --file environment_gpu.yml
   2. If you don't have a GPU or you are using Windows: conda install --yes --file environment_cpu.yml
3. Activate the conda environment: conda activate srec37
4. Download the repository: https://github.com/rn5l/session-rec.git

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.

Run experiments using the configuration file

1. 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.
2. Using Docker:
   Run the following command from the main folder:
   
   1. If you are using Linux and you have a GPU: ./dpython_gpu run_config.py conf/in conf/out
   2. If you are using Linux and you don't have a GPU: ./dpython run_config.py conf/in conf/out
   3. If you are using Windows: ./dpython.bat run_config.py conf/in conf/out
3. Using Anaconda:
   Run the following command from the main folder:
   
   1. 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
   2. 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
4. Results and run times will be displayed and saved to the results folder as config.
5. 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

1. Unzip any dataset file to the data folder, i.e., rsc15-clicks.dat will then be in the folder data/rsc15/raw
2. 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.
3. 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.
optimize	class: accuracy.MRR length: [20] iterations: 100 #optional	Measure to which optimize the parameters.
algorithms	-	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.

Related Datasets

Datasets can be downloaded from: https://drive.google.com/drive/folders/1ritDnO_Zc6DFEU6UND9C8VCisT0ETVp5?usp=sharing



RSC15	The e-commerce dataset used in the 2015 ACM RecSys Challenge.
RETAILROCKET	An e-commerce dataset from the company Retail Rocket.
DIGINETICA	An e-commerce dataset shared by the company Diginetica.
ZALANDO	A private dataset consisting of interaction logs from a European fashion retailer.
NOWPLAYING	Music listening logs obtained from Twitter.
30MUSIC	Music listening logs obtained from Last.fm.
AOTM	A public music dataset containing hand-crafted music playlists.
8TRACKS	A private music dataset with hand-crafted playlists.
XING	Interactions of job postings on a career-oriented social networking site, XING, from about three month.
COSMETICS	An e-commerce dataset containing the event history of a cosmetics shop for five months.
LASTFM	A music dataset that contains the entire listening history of almost 1,000 users during five year.