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.

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

For more details, please take a look at our examples as well as tutorials. For learning purposes, this list of tutorials on recommender systems will be more organized and comprehensive.

Simple model serving

Here, we provide a simple way to serve a Cornac model by launching a standalone web service. While this will not be an optimized service for model deployment in production, it is quite handy for testing or creating a demo application. Supposed that we use the trained BPR from previous example, we first need to save the model:

bpr.save("save_dir")

The model can be deployed easily by triggering Cornac serving module:

$ python -m cornac.serving --model_dir save_dir/BPR --model_class cornac.models.BPR

# Serving BPR at port 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://127.0.0.1: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 when starting the serving service.

$ python -m cornac.serving --help

usage: serving.py [-h] --model_dir MODEL_DIR [--model_class MODEL_CLASS] [--train_set TRAIN_SET] [--port PORT]

Cornac model serving

options:
  -h, --help                    show this help message and exit
  --model_dir MODEL_DIR         path to directory where the model was saved
  --model_class MODEL_CLASS     class of the model being deployed
  --train_set TRAIN_SET         path to pickled file of the train_set (to remove seen items)
  --port PORT                   service port

Efficient retrieval with ANN search

One important aspect of deploying recommender model is efficient retrieval via Approximate Nearest Neighor (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., MF).

Supported framework	Cornac wrapper	Examples
nmslib/hnswlib	HNSWLibANN	ann_hnswlib.ipynb

Models

The recommender models supported by Cornac are listed below. Why don't you join us to lengthen the list?

Year	Model and paper	Additional dependencies	Examples
2021	Bilateral Variational Autoencoder for Collaborative Filtering (BiVAECF), paper	requirements.txt	PreferredAI/bi-vae
	Causal Inference for Visual Debiasing in Visually-Aware Recommendation (CausalRec), paper	requirements.txt	causalrec_clothing.py
	Explainable Recommendation with Comparative Constraints on Product Aspects (ComparER), paper	N/A	PreferredAI/ComparER
2020	Adversarial Training Towards Robust Multimedia Recommender System (AMR), paper	requirements.txt	amr_clothing.py
	Hybrid neural recommendation with joint deep representation learning of ratings and reviews (HRDR), paper	requirements.txt	hrdr_example.py
	LightGCN: Simplifying and Powering Graph Convolution Network for Recommendation, paper	requirements.txt	lightgcn_example.py
2019	Embarrassingly Shallow Autoencoders for Sparse Data (EASEᴿ), paper	N/A	ease_movielens.py
	Neural Graph Collaborative Filtering (NGCF), paper	requirements.txt	ngcf_example.py
2018	Collaborative Context Poisson Factorization (C2PF), paper	N/A	c2pf_exp.py
	Graph Convolutional Matrix Completion (GCMC), paper	requirements.txt	gcmc_example.py
	Multi-Task Explainable Recommendation (MTER), paper	N/A	mter_exp.py
	Neural Attention Rating Regression with Review-level Explanations (NARRE), paper	requirements.txt	narre_example.py
	Probabilistic Collaborative Representation Learning (PCRL), paper	requirements.txt	pcrl_exp.py
	Variational Autoencoder for Collaborative Filtering (VAECF), paper	requirements.txt	vaecf_citeulike.py
2017	Collaborative Variational Autoencoder (CVAE), paper	requirements.txt	cvae_exp.py
	Conditional Variational Autoencoder for Collaborative Filtering (CVAECF), paper	requirements.txt	cvaecf_filmtrust.py
	Generalized Matrix Factorization (GMF), paper	requirements.txt	ncf_exp.py
	Indexable Bayesian Personalized Ranking (IBPR), paper	requirements.txt	ibpr_exp.py
	Matrix Co-Factorization (MCF), paper	N/A	mcf_office.py
	Multi-Layer Perceptron (MLP), paper	requirements.txt	ncf_exp.py
	Neural Matrix Factorization (NeuMF) / Neural Collaborative Filtering (NCF), paper	requirements.txt	ncf_exp.py
	Online Indexable Bayesian Personalized Ranking (Online IBPR), paper	requirements.txt
	Visual Matrix Factorization (VMF), paper	requirements.txt	vmf_clothing.py
2016	Collaborative Deep Ranking (CDR), paper	requirements.txt	cdr_exp.py
	Collaborative Ordinal Embedding (COE), paper	requirements.txt
	Convolutional Matrix Factorization (ConvMF), paper	requirements.txt	convmf_exp.py
	Learn to Rank user Preferences based on Phrase-level sentiment analysis across Multiple categories (LRPPM), paper	N/A	lrppm_example.py
	Spherical K-means (SKM), paper	N/A	skm_movielens.py
	Visual Bayesian Personalized Ranking (VBPR), paper	requirements.txt	vbpr_tradesy.py
2015	Collaborative Deep Learning (CDL), paper	requirements.txt	cdl_exp.py
	Hierarchical Poisson Factorization (HPF), paper	N/A	hpf_movielens.py
	TriRank: Review-aware Explainable Recommendation by Modeling Aspects, paper	N/A	trirank_example.py
2014	Explicit Factor Model (EFM), paper	N/A	efm_example.py
	Social Bayesian Personalized Ranking (SBPR), paper	N/A	sbpr_epinions.py
2013	Hidden Factors and Hidden Topics (HFT), paper	N/A	hft_exp.py
2012	Weighted Bayesian Personalized Ranking (WBPR), paper	N/A	bpr_netflix.py
2011	Collaborative Topic Regression (CTR), paper	N/A	ctr_citeulike.py
Earlier	Baseline Only, paper	N/A	svd_exp.py
	Bayesian Personalized Ranking (BPR), paper	N/A	bpr_netflix.py
	Factorization Machines (FM), paper	Linux only	fm_example.py
	Global Average (GlobalAvg), paper	N/A	biased_mf.py
	Item K-Nearest-Neighbors (ItemKNN), paper	N/A	knn_movielens.py
	Matrix Factorization (MF), paper	N/A	biased_mf.py, given_data.py
	Maximum Margin Matrix Factorization (MMMF), paper	N/A	mmmf_exp.py
	Most Popular (MostPop), paper	N/A	bpr_netflix.py
	Non-negative Matrix Factorization (NMF), paper	N/A	nmf_exp.py
	Probabilistic Matrix Factorization (PMF), paper	N/A	pmf_ratio.py
	Singular Value Decomposition (SVD), paper	N/A	svd_exp.py
	Social Recommendation using PMF (SoRec), paper	N/A	sorec_filmtrust.py
	User K-Nearest-Neighbors (UserKNN), paper	N/A	knn_movielens.py
	Weighted Matrix Factorization (WMF), paper	requirements.txt	wmf_exp.py

Support

Your contributions at any level of the library are welcome. If you intend to contribute, please:

• Fork the Cornac repository to your own account.
• Make changes and create pull requests.

You can also post bug reports and feature requests in GitHub issues.

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