ReChorus2.0 is a modular and task-flexible PyTorch library for recommendation, especially for research purpose. It aims to provide researchers a flexible framework to implement various recommendation tasks, compare different algorithms, and adapt to diverse and highly-customized data inputs. We hope ReChorus2.0 can serve as a more convinient and user-friendly tool for researchers, so as to form a "Chorus" of recommendation tasks and algorithms.

The previous version of ReChorus can be found at ReChorus1.0

What's New in ReChorus2.0:

• New Tasks: Newly supporting the context-aware top-k recommendation and CTR prediction task. Newly supporting the Impression-based re-ranking task.
• New Models: Adding Context-aware Recommenders and Impression-based Re-ranking Models. Listed below.
• New dataset format: Supporting various contextual feature input. Customizing candidate item lists in training and evaluation. Supporting variable length positive and negative samples.
• Task Flexible: Each model can serve for different tasks, and task switching is conveniently achieved by altering model mode.

This framework is especially suitable for researchers to choose or implement desired experimental settings, and compare algorithms under the same setting. The characteristics of our framework can be summarized as follows:

• Modular: primary functions modularized into distinct components: runner, model, and reader, facilitating code comprehension and integration of new features.

• Swift: concentrate on your model design in a single file and implement new models quickly.

• Efficient: multi-thread batch preparation, special implementations for the evaluation, and around 90% GPU utilization during training for deep models.

• Flexible: implement new readers or runners for different datasets and experimental settings, and each model can be assigned with specific helpers.

Structure

Generally, ReChorus decomposes the whole process into three modules:

• Reader: read dataset into DataFrame and append necessary information to each instance
• Runner: control the training process and model evaluation, including evaluation metrics.
• Model: define how to generate output (predicted labels or ranking scores) and prepare batches.

Getting Started

1. Install Anaconda with Python >= 3.5
2. Clone the repository

git clone https://github.com/THUwangcy/ReChorus.git

3. Install requirements and step into the src folder

cd ReChorus
pip install -r requirements.txt
cd src

4. Run model with the build-in dataset

python main.py --model_name BPRMF --emb_size 64 --lr 1e-3 --l2 1e-6 --dataset Grocery_and_Gourmet_Food

5. (optional) Run jupyter notebook in dataset folder to download and build new datasets, or prepare your own datasets according to Guideline in data

6. (optional) Implement your own models according to Guideline in src

Tasks & Settings

The tasks & settings are listed below

Tasks	Runner	Metrics	Loss Functions	Reader	BaseModel	Models	Model Modes
Top-k Recommendation	BaseRunner	HitRate NDCG	BPR	BaseReader	BaseModel.GeneralModel	general	''
				SeqReader	BaseModel.SequentialModel	sequential	''
				ContextReader	BaseContextModel.ContextModel	context	'TopK'
CTR Prediction	CTRRunner	BPR, BCE	AUC Logloss	ContextReader	BaseContextModel.ContextCTRModel	context	'CTR'
Impression-based Ranking	ImpressionRunner	HitRate NDCG MAP	List-level BPR, Listnet loss, Softmax cross entropy loss, Attention rank	ImpressionReader	BaseImpressionModel.ImpressionModel	general	'Impression'
				ImpressionSeqReader	BaseImpressionModel.ImpressionSeqModel	sequential	'Impression'
				ImpressionReader	BaseRerankerModel.RerankModel	reranker	'General'
				ImpressionSeqReader	BaseRerankerModel.RerankSeqModel	reranker	'Sequential'

Arguments

The main arguments are listed below.

Args	Default	Description
model_name	'BPRMF'	The name of the model class.
model_mode	''	The task mode for the model to implement.
lr	1e-3	Learning rate.
l2	0	Weight decay in optimizer.
test_all	0	Wheter to rank all the items during evaluation.
metrics	'NDCG,HR'	The list of evaluation metrics (seperated by comma).
topk	'5,10,20'	The list of K in evaluation metrics (seperated by comma).
num_workers	5	Number of processes when preparing batches.
batch_size	256	Batch size during training.
eval_batch_size	256	Batch size during inference.
load	0	Whether to load model checkpoint and continue to train.
train	1	Wheter to perform model training.
regenerate	0	Wheter to regenerate intermediate files.
random_seed	0	Random seed of everything.
gpu	'0'	The visible GPU device (pass an empty string '' to only use CPU).
buffer	1	Whether to buffer batches for dev/test.
history_max	20	The maximum length of history for sequential models.
num_neg	1	The number of negative items for each training instance.
test_epoch	-1	Print test set metrics every test_epoch during training (-1: no print).

Models

We have implemented the following methods (still updating):

General Recommenders

• Bayesian personalized ranking from implicit feedback (BPRMF [UAI'09])
• Neural Collaborative Filtering (NeuMF [WWW'17])
• Learning over Knowledge-Base Embeddings for Recommendation (CFKG [SIGIR'18])
• LightGCN: Simplifying and Powering Graph Convolution Network for Recommendation (LightGCN [SIGIR'20])
• Bootstrapping User and Item Representations for One-Class Collaborative Filtering (BUIR [SIGIR'21])
• Towards Representation Alignment and Uniformity in Collaborative Filtering (DirectAU [KDD'22])

Sequential Recommenders

• Factorizing Personalized Markov Chains for Next-Basket Recommendation (FPMC [WWW'10])
• Session-based Recommendations with Recurrent Neural Networks (GRU4Rec [ICLR'16])
• Neural Attentive Session-based Recommendation (NARM [CIKM'17])
• Personalized Top-N Sequential Recommendation via Convolutional Sequence Embedding (Caser [WSDM'18])
• Self-attentive Sequential Recommendation (SASRec [IEEE'18])
• Modeling Item-specific Temporal Dynamics of Repeat Consumption for Recommender Systems (SLRC [WWW'19])
• Time Interval Aware Self-Attention for Sequential Recommendation (TiSASRec [WSDM'20])
• Make It a Chorus: Knowledge- and Time-aware Item Modeling for Sequential Recommendation (Chorus [SIGIR'20])
• Controllable Multi-Interest Framework for Recommendation (ComiRec [KDD'20])
• Towards Dynamic User Intention: Temporal Evolutionary Effects of Item Relations in Sequential Recommendation (KDA [TOIS'21])
• Sequential Recommendation with Multiple Contrast Signals (ContraRec [TOIS'22])
• Target Interest Distillation for Multi-Interest Recommendation (TiMiRec [CIKM'22])

Context-aware Recommenders

General Context-aware Recommenders

• Factorization Machines (FM [ICDM'10])
• Wide {&} Deep Learning for Recommender Systems (WideDeep [DLRS@Recsys'16])
• Attentional Factorization Machines: Learning the Weight of Feature Interactions via Attention Networks (AFM [IJCAI'17])
• DeepFM: A Factorization-Machine based Neural Network for CTR Prediction (DeepFM [IJCAI'17])
• Deep & Cross Network for Ad Click Predictions (DCN [KDD'17])
• AutoInt: Automatic Feature Interaction Learning via Self-Attentive Neural Networks (AutoInt [CIKM'18])
• xdeepfm: Combining explicit and implicit feature interactions for recommender systems (xDeepFM [KDD'18])
• Deep interest evolution network for click-through rate prediction (DIEN [AAAI'19])
• DCN v2: Improved deep & cross network and practical lessons for web-scale learning to rank systems (DCNv2 [WWW'21])
• Looking at CTR Prediction Again: Is Attention All You Need? (SAM [SIGIR'21])
• CAN: feature co-action network for click-through rate prediction (CAN [WSDM'22])
• FinalMLP: an enhanced two-stream MLP model for CTR prediction (FinalMLP [AAAI'23])

Sequential Context-aware Recommenders

• Deep interest network for click-through rate prediction (DIN [KDD'18])
• End-to-end user behavior retrieval in click-through rateprediction model (ETA [CoRR'18])
• Sampling is all you need on modeling long-term user behaviors for CTR prediction (SDIM[CIKM'22])

Impression-based Re-ranking Models

• Personalized Re-ranking for Recommendatio (PRM [RecSys'19])
• SetRank: Learning a Permutation-Invariant Ranking Model for Information Retrieval (SIGIR [SIGIR'20])
• Multi-Level Interaction Reranking with User Behavior History (MIR[SIGIR'22])

Experimental results and corresponding configurations are shown in XXX.

Citation

If you find ReChorus is helpful to your research, please cite either of the following papers. Thanks!

@inproceedings{to be released,
  title={ReChorus2.0: A Modular and Task-Flexible Recommendation Library},
}

@inproceedings{wang2020make,
  title={Make it a chorus: knowledge-and time-aware item modeling for sequential recommendation},
  author={Wang, Chenyang and Zhang, Min and Ma, Weizhi and Liu, Yiqun and Ma, Shaoping},
  booktitle={Proceedings of the 43rd International ACM SIGIR Conference on Research and Development in Information Retrieval},
  pages={109--118},
  year={2020}
}
@article{王晨阳2021rechorus,
  title={ReChorus: 一个综合, 高效, 易扩展的轻量级推荐算法框架},
  author={王晨阳 and 任一 and 马为之 and 张敏 and 刘奕群 and 马少平},
  journal={软件学报},
  volume={33},
  number={4},
  pages={0--0},
  year={2021}
}

This is also our public implementation for the following papers (codes and datasets to reproduce the results can be found at corresponding branch):

• Chenyang Wang, Min Zhang, Weizhi Ma, Yiqun Liu, and Shaoping Ma. Make It a Chorus: Knowledge- and Time-aware Item Modeling for Sequential Recommendation. In SIGIR'20.

git clone -b SIGIR20 https://github.com/THUwangcy/ReChorus.git

• Chenyang Wang, Weizhi Ma, Min Zhang, Chong Chen, Yiqun Liu, and Shaoping Ma. Towards Dynamic User Intention: Temporal Evolutionary Effects of Item Relations in Sequential Recommendation. In TOIS'21.

git clone -b TOIS21 https://github.com/THUwangcy/ReChorus.git

• Chenyang Wang, Weizhi Ma, Chong, Chen, Min Zhang, Yiqun Liu, and Shaoping Ma. Sequential Recommendation with Multiple Contrast Signals. In TOIS'22.

git clone -b TOIS22 https://github.com/THUwangcy/ReChorus.git

• Chenyang Wang, Zhefan Wang, Yankai Liu, Yang Ge, Weizhi Ma, Min Zhang, Yiqun Liu, Junlan Feng, Chao Deng, and Shaoping Ma. Target Interest Distillation for Multi-Interest Recommendation. In CIKM'22.

git clone -b CIKM22 https://github.com/THUwangcy/ReChorus.git

Contact

ReChorus 1.0: Chenyang Wang (THUwangcy@gmail.com)

ReChorus 2.0: Jiayu Li (lijiayu997@gmail.com), Hanyu Li (l-hy12@outlook.com)