cornac 2.6.0

A Comparative Framework for Multimodal Recommender Systems

Cornac

Cornac is a comparative framework for multimodal recommender systems. It focuses on making it convenient to work with models leveraging auxiliary data (e.g., item descriptive text and image, social network, etc). Cornac enables fast experiments and straightforward implementations of new models. It is highly compatible with existing machine learning libraries (e.g., TensorFlow, PyTorch).

Cornac is one of the frameworks recommended by ACM RecSys 2023 for the evaluation and reproducibility of recommendation algorithms. In addition, the implementation of BPR model in Cornac has been recommended as trustworthy baseline for RecSys comparison by independent research.

Quick Links

Website | Documentation | Tutorials | Examples | Models | Datasets | Paper | Preferred.AI

Installation

Currently, we are supporting Python 3. There are several ways to install Cornac:

• From PyPI (recommended):

  pip3 install cornac
  

• From Anaconda:

  conda install cornac -c conda-forge
  

• From the GitHub source (for latest updates):

  pip3 install git+https://github.com/PreferredAI/cornac.git
  

Note:

Additional dependencies required by models are listed here.

Some algorithm implementations use OpenMP to support multi-threading. For Mac OS users, in order to run those algorithms efficiently, you might need to install gcc from Homebrew to have an OpenMP compiler:

brew install gcc && brew link gcc

Getting started: your first Cornac experiment

Flow of an Experiment in Cornac

import cornac
from cornac.eval_methods import RatioSplit
from cornac.models import MF, PMF, BPR
from cornac.metrics import MAE, RMSE, Precision, Recall, NDCG, AUC, MAP

# load the built-in MovieLens 100K and split the data based on ratio
ml_100k = cornac.datasets.movielens.load_feedback()
rs = RatioSplit(data=ml_100k, test_size=0.2, rating_threshold=4.0, seed=123)

# initialize models, here we are comparing: Biased MF, PMF, and BPR
mf = MF(k=10, max_iter=25, learning_rate=0.01, lambda_reg=0.02, use_bias=True, seed=123)
pmf = PMF(k=10, max_iter=100, learning_rate=0.001, lambda_reg=0.001, seed=123)
bpr = BPR(k=10, max_iter=200, learning_rate=0.001, lambda_reg=0.01, seed=123)
models = [mf, pmf, bpr]

# define metrics to evaluate the models
metrics = [MAE(), RMSE(), Precision(k=10), Recall(k=10), NDCG(k=10), AUC(), MAP()]

# put it together in an experiment, voilà!
cornac.Experiment(eval_method=rs, models=models, metrics=metrics, user_based=True).run()

Output:

	MAE	RMSE	AUC	MAP	NDCG@10	Precision@10	Recall@10	Train (s)	Test (s)
MF	0.7430	0.8998	0.7445	0.0548	0.0761	0.0675	0.0463	0.13	1.57
PMF	0.7534	0.9138	0.7744	0.0671	0.0969	0.0813	0.0639	2.18	1.64
BPR	N/A	N/A	0.8695	0.1042	0.1500	0.1110	0.1195	3.74	1.49

Model serving

Here, we provide a simple way to serve a Cornac model by launching a standalone web service with Flask. It is very handy for testing or creating a demo application. First, we install the dependency:

$ pip3 install Flask

Supposed that we want to serve the trained BPR model from previous example, we need to save it:

bpr.save("save_dir", save_trainset=True)

After that, the model can be deployed easily by running Cornac serving app as follows:

$ MODEL_PATH='save_dir/BPR' \
  MODEL_CLASS='cornac.models.BPR' \
  flask --app cornac.serving.app run --host localhost --port 8080  # requires Flask>=2.2 (older Flask: FLASK_APP='cornac.serving.app' flask run ...)

# Running on http://localhost:8080

Here we go, our model service is now ready. Let's get top-5 item recommendations for the user "63":

$ curl -X GET "http://localhost:8080/recommend?uid=63&k=5&remove_seen=false"

# Response: {"recommendations": ["50", "181", "100", "258", "286"], "query": {"uid": "63", "k": 5, "remove_seen": false}}

If we want to remove seen items during training, we need to provide TRAIN_SET which has been saved with the model earlier, when starting the serving app. We can also leverage WSGI server for model deployment in production. Please refer to this guide for more details.

Model A/B testing

Cornac-AB is an extension of Cornac using the Cornac Serving API. Easily create and manage A/B testing experiments to further understand your model performance with online users.

User Interaction Solution	Recommendations Dashboard	Feedback Dashboard

Efficient retrieval with ANN search

One important aspect of deploying recommender model is efficient retrieval via Approximate Nearest Neighbor (ANN) search in vector space. Cornac integrates several vector similarity search frameworks for the ease of deployment. This example demonstrates how ANN search will work seamlessly with any recommender models supporting it (e.g., matrix factorization).

Supported Framework	Cornac Wrapper	Example
spotify/annoy	AnnoyANN	quick-start, deep-dive
meta/faiss	FaissANN	quick-start, deep-dive
nmslib/hnswlib	HNSWLibANN	quick-start, hnsw-lib, deep-dive
google/scann	ScaNNANN	quick-start, deep-dive

Models

The table below lists the recommendation models/algorithms featured in Cornac. Examples are provided as quick-start showcasing an easy to run script, or as deep-dive explaining the math and intuition behind each model. Why don't you join us to lengthen the list?

Year	Model and Paper	Type	Environment	Example
2024	Comparative Aspects and Opinions Ranking for Recommendation Explanations (Companion), docs, paper	Hybrid / Sentiment / Explainable	CPU	quick-start
	Hypergraphs with Attention on Reviews (HypAR), docs, paper	Hybrid / Sentiment / Explainable	requirements, CPU / GPU	quick-start
2023	Scalable Approximate NonSymmetric Autoencoder (SANSA), docs, paper	Collaborative Filtering	requirements, CPU	quick-start, 150k-items
2022	Disentangled Multimodal Representation Learning for Recommendation (DMRL), docs, paper	Content-Based / Text & Image	requirements, CPU / GPU	quick-start
2021	Bilateral Variational Autoencoder for Collaborative Filtering (BiVAECF), docs, paper	Collaborative Filtering / Content-Based	requirements, CPU / GPU	quick-start, deep-dive
	Transformers4Rec-style Unified Transformer Recommender (TransformerRec), docs, paper	Next-Item	requirements, CPU / GPU	quick-start
	Causal Inference for Visual Debiasing in Visually-Aware Recommendation (CausalRec), docs, paper	Content-Based / Image	requirements, CPU / GPU	quick-start
	Explainable Recommendation with Comparative Constraints on Product Aspects (ComparER), docs, paper	Explainable	CPU	quick-start
2020	Adversarial Multimedia Recommendation (AMR), docs, paper	Content-Based / Image	requirements, CPU / GPU	quick-start
	Hybrid Deep Representation Learning of Ratings and Reviews (HRDR), docs, paper	Content-Based / Text	requirements, CPU / GPU	quick-start
	LightGCN: Simplifying and Powering Graph Convolution Network, docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start
	Predicting Temporal Sets with Deep Neural Networks (DNNTSP), docs, paper	Next-Basket	requirements, CPU / GPU	quick-start
	Recency Aware Collaborative Filtering (UPCF), docs, paper	Next-Basket	requirements, CPU	quick-start
	Temporal-Item-Frequency-based User-KNN (TIFUKNN), docs, paper	Next-Basket	CPU	quick-start
	Variational Autoencoder for Top-N Recommendations (RecVAE), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start
2019	Correlation-Sensitive Next-Basket Recommendation (Beacon), docs, paper	Next-Basket	requirements, CPU / GPU	quick-start
	BERT4Rec: Sequential Recommendation with Bidirectional Encoder Representations from Transformer (BERT4Rec), docs, paper	Next-Item	requirements, CPU / GPU	quick-start
	Embarrassingly Shallow Autoencoders for Sparse Data (EASEᴿ), docs, paper	Collaborative Filtering	CPU	quick-start
	Neural Graph Collaborative Filtering (NGCF), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start
	Sampler Design for Bayesian Personalized Ranking by Leveraging View Data (VEBPR), paper	Collaborative Filtering	CPU	quick-start
2018	Collaborative Context Poisson Factorization (C2PF), docs, paper	Content-Based / Graph	CPU	quick-start
	Self-Attentive Sequential Recommendation (SASRec), docs, paper	Next-Item	requirements, CPU / GPU	quick-start
	Graph Convolutional Matrix Completion (GCMC), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start
	Multi-Task Explainable Recommendation (MTER), docs, paper	Explainable	CPU	quick-start, deep-dive
	Neural Attention Rating Regression with Review-level Explanations (NARRE), docs, paper	Explainable / Content-Based	requirements, CPU / GPU	quick-start
	Probabilistic Collaborative Representation Learning (PCRL), docs, paper	Content-Based / Graph	requirements, CPU / GPU	quick-start
	Variational Autoencoder for Collaborative Filtering (VAECF), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start, param-search, deep-dive
2017	Collaborative Variational Autoencoder (CVAE), docs, paper	Content-Based / Text	requirements, CPU / GPU	quick-start
	Conditional Variational Autoencoder for Collaborative Filtering (CVAECF), docs, paper	Content-Based / Text	requirements, CPU / GPU	quick-start
	Generalized Matrix Factorization (GMF), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start, deep-dive
	Indexable Bayesian Personalized Ranking (IBPR), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start, deep-dive
	Matrix Co-Factorization (MCF), docs, paper	Content-Based / Graph	CPU	quick-start, cross-modality
	Multi-Layer Perceptron (MLP), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start, deep-dive
	Neural Matrix Factorization (NeuMF) / Neural Collaborative Filtering (NCF), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start, deep-dive
	Online Indexable Bayesian Personalized Ranking (Online IBPR), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start, deep-dive
	Visual Matrix Factorization (VMF), docs, paper	Content-Based / Image	requirements, CPU / GPU	quick-start
2016	Collaborative Deep Ranking (CDR), docs, paper	Content-Based / Text	requirements, CPU / GPU	quick-start
	Collaborative Ordinal Embedding (COE), docs, paper	Collaborative Filtering	requirements, CPU / GPU
	Convolutional Matrix Factorization (ConvMF), docs, paper	Content-Based / Text	requirements, CPU / GPU	quick-start, deep-dive
	Learning to Rank Features for Recommendation over Multiple Categories (LRPPM), docs, paper	Explainable	CPU	quick-start
	Session-based Recommendations With Recurrent Neural Networks (GRU4Rec), docs, paper	Next-Item	requirements, CPU / GPU	quick-start
	Spherical K-means (SKM), docs, paper	Collaborative Filtering	CPU	quick-start
	Visual Bayesian Personalized Ranking (VBPR), docs, paper	Content-Based / Image	requirements, CPU / GPU	quick-start, cross-modality, deep-dive
2015	Collaborative Deep Learning (CDL), docs, paper	Content-Based / Text	requirements, CPU / GPU	quick-start, deep-dive
	Hierarchical Poisson Factorization (HPF), docs, paper	Collaborative Filtering	CPU	quick-start
	TriRank: Review-aware Explainable Recommendation by Modeling Aspects, docs, paper	Explainable	CPU	quick-start
2014	Explicit Factor Model (EFM), docs, paper	Explainable	CPU	quick-start, deep-dive
	Social Bayesian Personalized Ranking (SBPR), docs, paper	Content-Based / Social	CPU	quick-start
2013	Hidden Factors and Hidden Topics (HFT), docs, paper	Content-Based / Text	CPU	quick-start
2012	Weighted Bayesian Personalized Ranking (WBPR), docs, paper	Collaborative Filtering	CPU	quick-start
2011	Collaborative Topic Regression (CTR), docs, paper	Content-Based / Text	CPU	quick-start, deep-dive
2010	Factorizing Personalized Markov Chains (FPMC), docs, paper	Next-Item	requirements, CPU / GPU	quick-start
Earlier	Baseline Only, docs, paper	Baseline	CPU	quick-start
	Bayesian Personalized Ranking (BPR), docs paper	Collaborative Filtering	CPU	quick-start, deep-dive
	Factorization Machines (FM), docs, paper	Collaborative Filtering / Content-Based	Linux, CPU	quick-start, deep-dive
	Global Average (GlobalAvg), docs, paper	Baseline	CPU	quick-start
	Global Personalized Top Frequent (GPTop), paper	Next-Basket	CPU	quick-start
	Item K-Nearest-Neighbors (ItemKNN), docs, paper	Neighborhood-Based	CPU	quick-start, deep-dive
	Matrix Factorization (MF), docs, paper	Collaborative Filtering	CPU / GPU	quick-start, pre-split-data, deep-dive
	Maximum Margin Matrix Factorization (MMMF), docs, paper	Collaborative Filtering	CPU	quick-start
	Most Popular (MostPop), docs, paper	Baseline	CPU	quick-start
	Non-negative Matrix Factorization (NMF), docs, paper	Collaborative Filtering	CPU	quick-start, deep-dive
	Probabilistic Matrix Factorization (PMF), docs, paper	Collaborative Filtering	CPU	quick-start
	Session Popular (SPop), docs, paper	Next-Item / Baseline	CPU	quick-start
	Singular Value Decomposition (SVD), docs, paper	Collaborative Filtering	CPU	quick-start, deep-dive
	Social Recommendation using PMF (SoRec), docs, paper	Content-Based / Social	CPU	quick-start, deep-dive
	User K-Nearest-Neighbors (UserKNN), docs, paper	Neighborhood-Based	CPU	quick-start, deep-dive
	Weighted Matrix Factorization (WMF), docs, paper	Collaborative Filtering	requirements, CPU / GPU	quick-start, deep-dive

Resources

• Cornac Examples
• Cornac Tutorials
• RecSys Tutorials by Preferred.AI
• Running Cornac Model with Microsoft Recommenders (BPR), (BiVAE)
• Multimodal RecSys Tutorial at TheWebConf/WWW 2023, earlier version at RecSys 2021

Contributing

This project welcomes contributions and suggestions. Before contributing, please see our contribution guidelines.

Citation

If you use Cornac in a scientific publication, we would appreciate citations to the following papers:

Cornac: A Comparative Framework for Multimodal Recommender Systems, Salah et al., Journal of Machine Learning Research, 21(95):1–5, 2020.

@article{salah2020cornac,
  title={Cornac: A Comparative Framework for Multimodal Recommender Systems},
  author={Salah, Aghiles and Truong, Quoc-Tuan and Lauw, Hady W},
  journal={Journal of Machine Learning Research},
  volume={21},
  number={95},
  pages={1--5},
  year={2020}
}

Exploring Cross-Modality Utilization in Recommender Systems, Truong et al., IEEE Internet Computing, 25(4):50–57, 2021.

@article{truong2021exploring,
  title={Exploring Cross-Modality Utilization in Recommender Systems},
  author={Truong, Quoc-Tuan and Salah, Aghiles and Tran, Thanh-Binh and Guo, Jingyao and Lauw, Hady W},
  journal={IEEE Internet Computing},
  year={2021},
  publisher={IEEE}
}

Multi-Modal Recommender Systems: Hands-On Exploration, Truong et al., ACM Conference on Recommender Systems, 2021.

@inproceedings{truong2021multi,
  title={Multi-modal recommender systems: Hands-on exploration},
  author={Truong, Quoc-Tuan and Salah, Aghiles and Lauw, Hady},
  booktitle={Fifteenth ACM Conference on Recommender Systems},
  pages={834--837},
  year={2021}
}

License

Apache License 2.0