Add Comparative Aspects and Opinions Ranking for Recommendation Explanations...

Add Comparative Aspects and Opinions Ranking for Recommendation Explanations (Companion) model (#635)

* Add Companion model

* Add example

* Update docs

* Update Companion model with additional arguments, removing sentiment loss

* Add paper link

* refactor code

README.md

@@ -52,7 +52,7 @@ Currently, we are supporting Python 3. There are several ways to install Cornac:
   pip3 install git+https://github.com/PreferredAI/cornac.git
   ```
 
-**Note:** 
+**Note:**
 
 Additional dependencies required by models are listed [here](README.md#Models).
 
@@ -151,7 +151,8 @@ The table below lists the recommendation models/algorithms featured in Cornac. E
 
 | Year | Model and Paper | Type | Environment | Example |
 | :--: | --------------- | :--: | :---------: | :-----: |
-| 2024 | [Hypergraphs with Attention on Reviews (HypAR)](cornac/models/hypar), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.hypar.recom_hypar), [paper](https://doi.org/10.1007/978-3-031-56027-9_14)| Hybrid / Sentiment / Explainable | [requirements](cornac/models/hypar/requirements_cu116.txt), CPU / GPU | [quick-start](https://github.com/PreferredAI/HypAR)
+| 2024 | [Comparative Aspects and Opinions Ranking for Recommendation Explanations (Companion)](cornac/models/companion), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.companion.recom_companion), [paper](https://lthoang.com/assets/publications/mlj24.pdf) | Hybrid / Sentiment / Explainable | CPU | [quick-start](examples/companion_example.py)
+|      | [Hypergraphs with Attention on Reviews (HypAR)](cornac/models/hypar), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.hypar.recom_hypar), [paper](https://doi.org/10.1007/978-3-031-56027-9_14)| Hybrid / Sentiment / Explainable | [requirements](cornac/models/hypar/requirements_cu116.txt), CPU / GPU | [quick-start](https://github.com/PreferredAI/HypAR)
 | 2022 | [Disentangled Multimodal Representation Learning for Recommendation (DMRL)](cornac/models/dmrl), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.dmrl.recom_dmrl), [paper](https://arxiv.org/pdf/2203.05406.pdf) | Content-Based / Text & Image | [requirements](cornac/models/dmrl/requirements.txt), CPU / GPU | [quick-start](examples/dmrl_example.py)
 | 2021 | [Bilateral Variational Autoencoder for Collaborative Filtering (BiVAECF)](cornac/models/bivaecf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.bivaecf.recom_bivaecf), [paper](https://dl.acm.org/doi/pdf/10.1145/3437963.3441759) | Collaborative Filtering / Content-Based | [requirements](cornac/models/bivaecf/requirements.txt), CPU / GPU | [quick-start](https://github.com/PreferredAI/bi-vae), [deep-dive](https://github.com/recommenders-team/recommenders/blob/main/examples/02_model_collaborative_filtering/cornac_bivae_deep_dive.ipynb)
 |      | [Causal Inference for Visual Debiasing in Visually-Aware Recommendation (CausalRec)](cornac/models/causalrec), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.causalrec.recom_causalrec), [paper](https://arxiv.org/abs/2107.02390) | Content-Based / Image | [requirements](cornac/models/causalrec/requirements.txt), CPU / GPU | [quick-start](examples/causalrec_clothing.py)

cornac/models/__init__.py

@@ -32,6 +32,7 @@ from .c2pf import C2PF
 from .cdl import CDL
 from .cdr import CDR
 from .coe import COE
+from .companion import Companion
 from .comparer import ComparERObj
 from .comparer import ComparERSub
 from .conv_mf import ConvMF

cornac/models/companion/__init__.py

+# Copyright 2018 The Cornac Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+
+from .recom_companion import Companion

docs/source/api_ref/models.rst

@@ -11,6 +11,11 @@ Recommender (Generic Class)
 .. automodule:: cornac.models.recommender
    :members:
 
+Comparative Aspects and Opinions Ranking for Recommendation Explanations (Companion)
+-------------------------------------------------------------------------
+.. automodule:: cornac.models.companion.recom_companion
+   :members:
+
 Disentangled Multimodal Representation Learning for Recommendation (DMRL)
 -------------------------------------------------------------------------
 .. automodule:: cornac.models.dmrl.recom_dmrl
@@ -307,7 +312,7 @@ Social Recommendation using PMF (SoRec)
 User K-Nearest-Neighbors (UserKNN)
 ----------------------------------
 .. autoclass:: cornac.models.knn.recom_knn.UserKNN
-   :members:   
+   :members:
 
 Weighted Matrix Factorization (WMF)
 -----------------------------------

examples/README.md

@@ -48,6 +48,8 @@
 
 [cdr_example.py](cdr_example.py) - Collaborative Deep Ranking (CDR) with CiteULike dataset.
 
+[companion_example.py](companion_example.py) - Comparative Aspects and Opinions Ranking for Recommendation Explanations (Companion) with Amazon Toy and Games dataset.
+
 [conv_mf_example.py](conv_mf_example.py) - Convolutional Matrix Factorization (ConvMF) with MovieLens dataset.
 
 [ctr_example_citeulike.py](ctr_example_citeulike.py) - Collaborative Topic Regression (CTR) with CiteULike dataset.

examples/companion_example.py

+# Copyright 2024 The Cornac Authors. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ============================================================================
+"""Example for Comparative Aspects and Opinions Ranking for Recommendation Explanations"""
+
+import cornac
+from cornac.datasets import amazon_toy
+from cornac.data import SentimentModality
+from cornac.eval_methods import StratifiedSplit
+from cornac.metrics import NDCG, RMSE, AUC
+from cornac import Experiment
+
+
+rating = amazon_toy.load_feedback(fmt="UIRT")
+sentiment = amazon_toy.load_sentiment()
+
+
+# Instantiate a SentimentModality, it makes it convenient to work with sentiment information
+md = SentimentModality(data=sentiment)
+
+# Define an evaluation method to split feedback into train and test sets
+eval_method = StratifiedSplit(
+    rating,
+    group_by="user",
+    chrono=True,
+    sentiment=md,
+    test_size=1,
+    val_size=1,
+    exclude_unknowns=True,
+    verbose=True,
+    seed=123,
+)
+
+companion = cornac.models.Companion(
+    n_top_aspects=0,
+    max_iter=10000,
+    verbose=True,
+    seed=123,
+)
+
+# Instantiate and run an experiment
+exp = Experiment(
+    eval_method=eval_method,
+    models=[companion],
+    metrics=[RMSE(), NDCG(k=20), AUC()],
+)
+exp.run()

setup.py

@@ -228,6 +228,14 @@ extensions = [
         extra_compile_args=compile_args,
         extra_link_args=link_args,
     ),
+    Extension(
+        name="cornac.models.companion.recom_companion",
+        sources=["cornac/models/companion/recom_companion.pyx"],
+        include_dirs=[np.get_include(), "cornac/utils/external"],
+        language="c++",
+        extra_compile_args=compile_args,
+        extra_link_args=link_args,
+    ),
     Extension(
         name="cornac.models.comparer.recom_comparer_sub",
         sources=["cornac/models/comparer/recom_comparer_sub.pyx"],