From fce463bf971e2642bbffd5838328962d1aecdb33 Mon Sep 17 00:00:00 2001 From: hieuddo Date: Mon, 16 Nov 2026 14:50:46 +0800 Subject: [PATCH 1/6] Fix broken examples, links and setup steps in the docs --- README.md | 4 +-- cornac/datasets/README.md | 42 ++++++++++++------------ docs/source/developer/contributing.rst | 6 ++-- docs/source/developer/gettingstarted.rst | 7 ++-- docs/source/user/example-foodrecce.rst | 2 +- docs/source/user/install.rst | 8 ++--- docs/source/user/owndata.rst | 26 +++++++-------- docs/source/user/predict.rst | 8 ++--- tutorials/add_metric.md | 10 +++--- tutorials/add_model.md | 29 ++++++++-------- 10 files changed, 74 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index 407a52c6a..702cf3d16 100644 --- a/README.md +++ b/README.md @@ -189,7 +189,7 @@ The table below lists the recommendation models/algorithms featured in Cornac. E | | [Conditional Variational Autoencoder for Collaborative Filtering (CVAECF)](cornac/models/cvaecf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.cvaecf.recom_cvaecf), [paper](https://dl.acm.org/doi/10.1145/3132847.3132972) | Content-Based / Text | [requirements](cornac/models/cvaecf/requirements.txt), CPU / GPU | [quick-start](examples/cvaecf_filmtrust.py) | | [Generalized Matrix Factorization (GMF)](cornac/models/ncf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.ncf.recom_gmf), [paper](https://arxiv.org/pdf/1708.05031.pdf) | Collaborative Filtering | [requirements](cornac/models/ncf/requirements.txt), CPU / GPU | [quick-start](examples/ncf_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/09_deep_learning.ipynb) | | [Indexable Bayesian Personalized Ranking (IBPR)](cornac/models/ibpr), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.ibpr.recom_ibpr), [paper](http://www.hadylauw.com/publications/cikm17a.pdf) | Collaborative Filtering | [requirements](cornac/models/ibpr/requirements.txt), CPU / GPU | [quick-start](examples/ibpr_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/08_retrieval.ipynb) -| | [Matrix Co-Factorization (MCF)](cornac/models/mcf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.mcf.recom_mcf), [paper](https://dsail.kaist.ac.kr/files/WWW17.pdf) | Content-Based / Graph | CPU | [quick-start](examples/mcf_office.py), [cross-modality](https://github.com/lgabs/cornac/blob/luan/describe-gpu-supported-models-readme/tutorials/text_to_graph.ipynb) +| | [Matrix Co-Factorization (MCF)](cornac/models/mcf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.mcf.recom_mcf), [paper](https://dsail.kaist.ac.kr/files/WWW17.pdf) | Content-Based / Graph | CPU | [quick-start](examples/mcf_office.py), [cross-modality](tutorials/text_to_graph.ipynb) | | [Multi-Layer Perceptron (MLP)](cornac/models/ncf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.ncf.recom_mlp), [paper](https://arxiv.org/pdf/1708.05031.pdf) | Collaborative Filtering | [requirements](cornac/models/ncf/requirements.txt), CPU / GPU | [quick-start](examples/ncf_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/09_deep_learning.ipynb) | | [Neural Matrix Factorization (NeuMF) / Neural Collaborative Filtering (NCF)](cornac/models/ncf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.ncf.recom_neumf), [paper](https://arxiv.org/pdf/1708.05031.pdf) | Collaborative Filtering | [requirements](cornac/models/ncf/requirements.txt), CPU / GPU | [quick-start](examples/ncf_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/09_deep_learning.ipynb) | | [Online Indexable Bayesian Personalized Ranking (Online IBPR)](cornac/models/online_ibpr), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.online_ibpr.recom_online_ibpr), [paper](http://www.hadylauw.com/publications/cikm17a.pdf) | Collaborative Filtering | [requirements](cornac/models/online_ibpr/requirements.txt), CPU / GPU | [quick-start](examples/ibpr_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/08_retrieval.ipynb) @@ -201,7 +201,7 @@ The table below lists the recommendation models/algorithms featured in Cornac. E | | [Session-based Recommendations With Recurrent Neural Networks (GRU4Rec)](cornac/models/gru4rec), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.gru4rec.recom_gru4rec), [paper](https://arxiv.org/pdf/1511.06939.pdf) | Next-Item | [requirements](cornac/models/gru4rec/requirements.txt), CPU / GPU | [quick-start](examples/gru4rec_yoochoose.py) | | [Spherical K-means (SKM)](cornac/models/skm), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.skm.recom_skmeans), [paper](https://www.sciencedirect.com/science/article/pii/S092523121501509X) | Collaborative Filtering | CPU | [quick-start](examples/skm_movielens.py) | | [Visual Bayesian Personalized Ranking (VBPR)](cornac/models/vbpr), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.vbpr.recom_vbpr), [paper](https://arxiv.org/pdf/1510.01784.pdf) | Content-Based / Image | [requirements](cornac/models/vbpr/requirements.txt), CPU / GPU | [quick-start](examples/vbpr_tradesy.py), [cross-modality](tutorials/vbpr_text.ipynb), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/05_multimodality.ipynb) -| 2015 | [Collaborative Deep Learning (CDL)](cornac/models/cdl), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.cdl.recom_cdl), [paper](https://arxiv.org/pdf/1409.2944.pdf) | Content-Based / Text | [requirements](cornac/models/cdl/requirements.txt), CPU / GPU | [quick-start](examples/cdl_example.py), [deep-dive](https://github.com/lgabs/cornac/blob/luan/describe-gpu-supported-models-readme/tutorials/working_with_auxiliary_data.md) +| 2015 | [Collaborative Deep Learning (CDL)](cornac/models/cdl), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.cdl.recom_cdl), [paper](https://arxiv.org/pdf/1409.2944.pdf) | Content-Based / Text | [requirements](cornac/models/cdl/requirements.txt), CPU / GPU | [quick-start](examples/cdl_example.py), [deep-dive](tutorials/working_with_auxiliary_data.md) | | [Hierarchical Poisson Factorization (HPF)](cornac/models/hpf), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.hpf.recom_hpf), [paper](http://jakehofman.com/inprint/poisson_recs.pdf) | Collaborative Filtering | CPU | [quick-start](examples/hpf_movielens.py) | | [TriRank: Review-aware Explainable Recommendation by Modeling Aspects](cornac/models/trirank), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.trirank.recom_trirank), [paper](https://wing.comp.nus.edu.sg/wp-content/uploads/Publications/PDF/TriRank-%20Review-aware%20Explainable%20Recommendation%20by%20Modeling%20Aspects.pdf) | Explainable | CPU | [quick-start](examples/trirank_example.py) | 2014 | [Explicit Factor Model (EFM)](cornac/models/efm), [docs](https://cornac.readthedocs.io/en/stable/api_ref/models.html#module-cornac.models.efm.recom_efm), [paper](https://www.yongfeng.me/attach/efm-zhang.pdf) | Explainable | CPU | [quick-start](examples/efm_example.py), [deep-dive](https://github.com/PreferredAI/tutorials/blob/master/recommender-systems/07_explanations.ipynb) diff --git a/cornac/datasets/README.md b/cornac/datasets/README.md index 22eb32944..551d89723 100644 --- a/cornac/datasets/README.md +++ b/cornac/datasets/README.md @@ -24,7 +24,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda Graph - Amazon Clothing
(source) + Amazon Clothing
(source) 5,377 3,393 13,689 @@ -35,7 +35,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - Amazon Digital Music
(source) + Amazon Digital Music
(source) 5,541 3,568 64,706 @@ -46,7 +46,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - Amazon Office
(source) + Amazon Office
(source) 3,703 6,523 53,282 @@ -57,7 +57,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - Amazon Toy
(source) + Amazon Toy
(source) 19,412 11,924 167,597 @@ -68,7 +68,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - Citeulike
(source) + Citeulike
(source) 5,551 16,980 210,537 @@ -79,7 +79,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - Epinions
(source) + Epinions
(source) 40,163 139,738 664,824 @@ -90,7 +90,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda ✔ - FilmTrust
(source) + FilmTrust
(source) 1,508 2,071 35,497 @@ -101,7 +101,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda ✔ - MovieLens 100k
(source) + MovieLens 100k
(source) 943 1,682 100,000 @@ -112,7 +112,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - MovieLens 1M
(source) + MovieLens 1M
(source) 6,040 3,706 1,000,209 @@ -123,7 +123,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - MovieLens 10M
(source) + MovieLens 10M
(source) 69,878 10,677 10,000,054 @@ -134,7 +134,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - MovieLens 20M
(source) + MovieLens 20M
(source) 138,493 26,744 20,000,263 @@ -145,7 +145,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - Netflix Small
(source) + Netflix Small
(source) 10,000 5,000 607,803 @@ -156,7 +156,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - Neflix Original
(source) + Netflix Original
(source) 480,189 17,770 100,480,507 @@ -167,7 +167,7 @@ For easy experimentation, Cornac offers access to a number of popular recommenda - Tradesy
(source) + Tradesy
(source) 19,243 165,906 394,421 @@ -189,12 +189,12 @@ ratings = filmtrust.load_feedback() trust = filmtrust.load_trust() ``` -The ranting values are in the range `[0.5,4]`, and the trust network is undirected. Here are samples from our dataset, +The rating values are in the range `[0.5,4]`, and the trust network is undirected. Here are samples from our dataset, ``` Samples from ratings: [('1', '1', 2.0), ('1', '2', 4.0), ('1', '3', 3.5)] Samples from trust: [('2', '966', 1.0), ('2', '104', 1.0), ('5', '1509', 1.0)] ``` -Our dataset is now ready to use for model training and evaluation. A concrete example is [sorec_filmtrust](../../examples/sorec_filmtrust.py), which illustrates how to perform an experiment with the [SoRec](../models/sorec/) model on FilmTrust. More details regarding the other datasets are available in the [documentation](https://cornac.readthedocs.io/en/latest/datasets.html). +Our dataset is now ready to use for model training and evaluation. A concrete example is [sorec_filmtrust](../../examples/sorec_filmtrust.py), which illustrates how to perform an experiment with the [SoRec](../models/sorec/) model on FilmTrust. More details regarding the other datasets are available in the [documentation](https://cornac.readthedocs.io/en/stable/api_ref/datasets.html). --- @@ -213,7 +213,7 @@ Our dataset is now ready to use for model training and evaluation. A concrete ex #Interactions - Ta Feng
(source) + Ta Feng
(source) 28,297 22,542 86,403 @@ -236,7 +236,7 @@ Our dataset is now ready to use for model training and evaluation. A concrete ex Extra Info. - Gowalla
(source) + Gowalla
(source) 107,092 1,280,969 2,710,119 @@ -244,7 +244,7 @@ Our dataset is now ready to use for model training and evaluation. A concrete ex Check-ins location (longitude, latitude) - YooChoose (buy)
(source) + YooChoose (buy)
(source) N/A 19,949 509,696 @@ -252,7 +252,7 @@ Our dataset is now ready to use for model training and evaluation. A concrete ex N/A - YooChoose (click) + YooChoose (click) N/A 52,739 9,249,729 @@ -260,7 +260,7 @@ Our dataset is now ready to use for model training and evaluation. A concrete ex N/A - YooChoose (test) + YooChoose (test) N/A 42,155 2,312,432 diff --git a/docs/source/developer/contributing.rst b/docs/source/developer/contributing.rst index 4f8c65ae4..a89580563 100644 --- a/docs/source/developer/contributing.rst +++ b/docs/source/developer/contributing.rst @@ -40,8 +40,8 @@ are working as expected. .. code-block:: bash - python3 setup.py clean - python3 setup.py install + python setup.py build_ext --inplace + pip install -e ".[tests]" .. note:: @@ -85,7 +85,7 @@ Once your feature is ready for reviewing, do a pull request for review and mergi 1. Visit your fork on GitHub. 2. Click the "New Pull Request" button. -3. Choose the base repository (PreferredAI/cornac) and branch (main) for your pull request. +3. Choose the base repository (PreferredAI/cornac) and branch (master) for your pull request. 4. Write a clear and detailed pull request description. 5. Click "Create Pull Request." diff --git a/docs/source/developer/gettingstarted.rst b/docs/source/developer/gettingstarted.rst index 5784f3bd3..66c95ffa3 100644 --- a/docs/source/developer/gettingstarted.rst +++ b/docs/source/developer/gettingstarted.rst @@ -5,7 +5,7 @@ Prerequisites ^^^^^^^^^^^^^ Before contributing to Cornac, make sure you have the following prerequisites: -- Python 3.x +- Python 3.10 or newer - Git - Virtual Environment (optional but recommended) @@ -23,7 +23,10 @@ Setting Up Your Development Environment cd cornac python -m venv venv source venv/bin/activate # On Windows, use 'venv\Scripts\activate' - pip install -r requirements.txt + pip install Cython numpy scipy + python setup.py build_ext --inplace + pip install -e ".[tests]" + pytest Now you are ready to contribute to Cornac! diff --git a/docs/source/user/example-foodrecce.rst b/docs/source/user/example-foodrecce.rst index 6686bb154..234816fec 100644 --- a/docs/source/user/example-foodrecce.rst +++ b/docs/source/user/example-foodrecce.rst @@ -133,7 +133,7 @@ Now, given that our backend receives a load request from a user with id def get_recommendations(user_id, top_k): # Get the top k recommendations for user with id user_id - top_k_recs = bpr.recommend(user_id=user_id, top_k=top_k) + top_k_recs = bpr.recommend(user_id=user_id, k=top_k) return top_k_recs diff --git a/docs/source/user/install.rst b/docs/source/user/install.rst index d0433779f..3572fac06 100644 --- a/docs/source/user/install.rst +++ b/docs/source/user/install.rst @@ -3,7 +3,7 @@ Installation Install Python -------------- -Cornac supports most versions of Python 3. If you have not done so, go to the official `Python download page `_. +Cornac supports Python 3.10 or newer. If you have not done so, go to the official `Python download page `_. Install Cornac -------------- @@ -47,7 +47,7 @@ Model dependencies ------------------ Certain models in Cornac may require additional dependencies. -The requirements.txt file shows what dependencies are required for each model.\ +The requirements.txt file shows what dependencies are required for each model. Take the model WMF for example. @@ -80,7 +80,7 @@ To install all dependencies in a provided requirements.txt file, follow these st .. code-block:: bash - brew install gcc | brew link gcc + brew install gcc && brew link gcc Verifying Installation ---------------------- @@ -94,7 +94,7 @@ by running the following command on your favourite terminal/command prompt: You should see the following output: .. parsed-literal:: - |version| + |release| Congratulations! Your machine has Cornac and you're now ready to create your first experiment! diff --git a/docs/source/user/owndata.rst b/docs/source/user/owndata.rst index 129fa9dbd..69406a99d 100644 --- a/docs/source/user/owndata.rst +++ b/docs/source/user/owndata.rst @@ -132,7 +132,7 @@ recommended item for the user, followed by the second item, and so on. # Use the fit() function to train the model model_pmf.fit(dataset) - # Get recommendations for user id 10 + # Get recommendations for user id 4 user_id = 4 recommended_items = model_pmf.recommend(user_id) @@ -189,7 +189,8 @@ provided by Cornac to read our CSV file. data = Reader().read('data.csv', sep=',') print(data) -1. Creating the Dataset Object +2. Creating the Dataset Object +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Next, we will create a dataset object from the data. The dataset object will be used to train the model. @@ -199,9 +200,10 @@ will be used to train the model. from cornac.data import Dataset # Load the data into a dataset object - dataset = Dataset.from_uir(data, sep=',', skip_lines=1) + dataset = Dataset.from_uir(data) 3. Create and train model +^^^^^^^^^^^^^^^^^^^^^^^^^^ We will then create a model object and train it using the dataset object. @@ -216,6 +218,7 @@ We will then create a model object and train it using the dataset object. model_pmf.fit(dataset) 4. Getting recommendations +^^^^^^^^^^^^^^^^^^^^^^^^^^ Finally, we will use the model to get item recommendations for the users. The ``recommend()`` function will recommend the top rated items from the model for the user provided. @@ -225,7 +228,7 @@ For example, we will get all recommendations for user 4. .. code-block:: python # Get recommendations for user id 4 - user_id = 4 + user_id = "4" recommended_items = model_pmf.recommend(user_id) # Print the recommended items @@ -234,7 +237,7 @@ For example, we will get all recommendations for user 4. .. code-block:: bash :caption: output - [1, 4, 3, 5, 2] + ['1', '4', '3', '5', '2'] The output is a list of item IDs. The first item in the list is the most recommended item for the user, followed by the second item, and so on. @@ -245,19 +248,16 @@ recommended item for the user, followed by the second item, and so on. :caption: data_csv.py :linenos: - import csv import cornac from cornac.models import PMF - from cornac.data import Dataset + from cornac.data import Dataset, Reader # Load the data from the CSV file - with open('data.csv', 'r') as f: - reader = csv.reader(f) - data = list(reader) - print(data) + data = Reader().read('data.csv', sep=',') + print(data) # Load the data into a dataset object - dataset = Dataset.from_uir(data, sep=',', skip_lines=1) + dataset = Dataset.from_uir(data) # Instantiate the PMF model model_pmf = PMF(k=10, max_iter=100, learning_rate=0.001, lambda_reg=0.001, seed=123) @@ -266,7 +266,7 @@ recommended item for the user, followed by the second item, and so on. model_pmf.fit(dataset) # Get recommendations for user id 4 - user_id = 4 + user_id = "4" recommended_items = model_pmf.recommend(user_id) # Print the recommended items diff --git a/docs/source/user/predict.rst b/docs/source/user/predict.rst index 307bc1ab4..8a77edc61 100644 --- a/docs/source/user/predict.rst +++ b/docs/source/user/predict.rst @@ -20,7 +20,7 @@ The Prediction -------------- We will predict the ratings of a particular user. Let's say we want to -predict the ratings of the first user in our list (``index 0``). +predict the ratings of the user with ID ``"10"``. Followed from our quickstart tutorial, we will use the PMF model to predict the ratings of a user. We will use the same hyperparameters as in the @@ -43,7 +43,7 @@ into it: ml_100k = cornac.datasets.movielens.load_feedback() Similar to the previous tutorial, we load the MovieLens 100K dataset. -The ``ml_100k`` variable is a ``cornac.data.Dataset`` object. +The ``ml_100k`` variable is a list of ``(user, item, rating)`` tuples. 2. Model Training @@ -63,7 +63,7 @@ We then instantiate the PMF model and train it using the ``fit()`` function. rs = RatioSplit(ml_100k, test_size=0.2, seed=123, verbose=True) # Use the fit() function to train the model - model_pmf.fit(ml_100k) + model_pmf.fit(rs.train_set) 3. Prediction @@ -78,7 +78,7 @@ user. The list is sorted in descending order of the predicted ratings. .. code-block:: python # Get recommendations for user id 10 - user_id = 10 + user_id = "10" recommended_items = model_pmf.recommend(user_id) # Print the recommended items diff --git a/tutorials/add_metric.md b/tutorials/add_metric.md index 893f71fab..fc4c91442 100644 --- a/tutorials/add_metric.md +++ b/tutorials/add_metric.md @@ -2,7 +2,7 @@ This tutorial shows how to add an evaluation measure to Cornac. As with any contribution, we assume that we have already forked the Cornac repository. -Some evaluation measures may have different appellations in the literature. So it is worth it to make sure that the metric of interest is not already available in Cornac, before considering any contribution. Cornac's list of measures is [here](https://cornac.readthedocs.io/en/latest/metrics.html). +Some evaluation measures may have different appellations in the literature. So it is worth it to make sure that the metric of interest is not already available in Cornac, before considering any contribution. Cornac's list of measures is [here](https://cornac.readthedocs.io/en/stable/api_ref/metrics.html). ## Adding a metric @@ -21,7 +21,7 @@ It is important to follow the above categorization to avoid confusions. For the ### 1. Extending the RatingMetric class -The starting point is to create a class called ``MAE``, which extends the generic class ``RatingMetric`` implemented inside `metric/rating.py`. The minimal structure of our new class is as follows: +The starting point is to create a class called ``MAE``, which extends the generic class ``RatingMetric`` implemented inside `cornac/metrics/rating.py`. The minimal structure of our new class is as follows: ```python class MAE(RatingMetric): """Mean Absolute Error. @@ -67,16 +67,16 @@ def compute(self, gt_ratings, pd_ratings, weights=None, **kwargs): mae = np.average(np.abs(gt_ratings - pd_ratings), axis=0, weights=weights) return mae ``` -As one may have guessed, the code of the ``MAE`` class should be inside ``metrics/rating.py``. +As one may have guessed, the code of the ``MAE`` class should be inside ``cornac/metrics/rating.py``. ### 2. Making our metric available to Cornac and its Docs -To make the MAE class accessible in Cornac, we update the ``metrics/__init__.py`` file by adding the following line: +To make the MAE class accessible in Cornac, we update the ``cornac/metrics/__init__.py`` file by adding the following line: ```python from .rating import MAE ``` -To further automatically generate the documentation for our measure, we update `cornac/docs/source/metrics.rst` by adding the following code under the _Rating_ section. +To further automatically generate the documentation for our measure, we update `docs/source/api_ref/metrics.rst` by adding the following code under the _Rating_ section. ``` Mean Absolute Error (MAE) -------------------------- diff --git a/tutorials/add_model.md b/tutorials/add_model.md index 96669156d..2b7e67a04 100644 --- a/tutorials/add_model.md +++ b/tutorials/add_model.md @@ -47,27 +47,28 @@ class PMF(Recommender): Parameters ---------- - train_set: :obj:`cornac.data.MultimodalTrainSet`, required + train_set: :obj:`cornac.data.Dataset`, required User-Item preference data as well as additional modalities. - val_set: :obj:`cornac.data.MultimodalTestSet`, optional, default: None + val_set: :obj:`cornac.data.Dataset`, optional, default: None User-Item preference data for model selection purposes (e.g., early stopping). Returns ------- self : object """ + Recommender.fit(self, train_set, val_set) - def score(self, user_id, item_id=None): + def score(self, user_idx, item_idx=None): """Predict the scores/ratings of a user for an item. Parameters ---------- - user_id: int, required + user_idx: int, required The index of the user for whom to perform score prediction. - item_id: int, optional, default: None - The index of the item for that to perform score prediction. + item_idx: int, optional, default: None + The index of the item for which to perform score prediction. If None, scores for all known items will be returned. Returns @@ -78,18 +79,20 @@ class PMF(Recommender): ``` Every model extends the generic class `Recommender`. All you need to do is to redefine the functions listed in the above `recom_pmf.py` file. -The `fit()` function should contain or make a call to the necessary codes to fit your model to the training data, while the `score()` function specifies how to perform predictions using your model. +The `fit()` function should contain or make a call to the necessary codes to fit your model to the training data, while the `score()` function specifies how to perform predictions using your model. Start `fit()` with `Recommender.fit(self, train_set, val_set)`, which sets up the information your model needs later, such as `num_users`, `num_items`, `uid_map` and `iid_map`. #### More on the score function When you perform rating prediction evaluation (e.g., in terms of RMSE) Cornac calls the `Recommender.rate()` function, which in turn calls the `score()` function and clips the predicted values to lie in the same range as the original ratings. Analogously, Cornac calls the `Recommender.rank()` function, which returns a ranking of items according to their scores as predicted by the function `score()`. We recommend you to take a look at the `rate()` and `rank()` functions inside the `Recommender` class, as you may wish to redefine them as well, if the default settings do not meet your needs. +If your model cannot score a user or an item, for example one that was not in the training data, raise `ScoreException` from `cornac.exception` in `score()`. `rate()` and `rank()` catch it and fall back to a default score. The `score()` function of [PMF](https://github.com/PreferredAI/cornac/blob/master/cornac/models/pmf/recom_pmf.py) shows how. + ### 2. Making your recommender available to Cornac As you may have already noticed, Cornac treats each recommender model as a separate module, so as to reduce coupling and ease the contribution of new models. This is the reason why you need to include a `pmf/__init__.py` file: ```python from .recom_pmf import PMF ``` -One last step is required to make you recommender model available to Cornac, which is to update `../models/__init__.py` by adding the following line: +One last step is required to make your recommender model available to Cornac, which is to update `cornac/models/__init__.py` by adding the following line: ```python from .pmf import PMF ``` @@ -104,9 +107,9 @@ tensorflow>=1.10.0 Cornac uses [Sphinx](http://www.sphinx-doc.org/en/master/) to generate documentation. All you need to do is to fulfill the Parameters section inside `recom_pmf.py`. If you are not familiar with Sphinx syntax conventions, you can just take a look at some of the existing Cornac models and follow them. -Once you have documented the parameters of your recommender, the next step, to integrate your model to the docs, is to update `cornac/docs/source/models.rst` by adding the following code: +Once you have documented the parameters of your recommender, the next step, to integrate your model to the docs, is to update `docs/source/api_ref/models.rst` by adding the following code: ``` -Probabilitic Matrix Factorization (PMF) +Probabilistic Matrix Factorization (PMF) ----------------------------------------- .. automodule:: cornac.models.pmf.recom_pmf :members: @@ -115,7 +118,7 @@ The last step is to add your algorithm into the Cornac's list of models table in At this point you are done, and ready to create a pull request, congratulations! ### Including an example (optional) -We highly encourage you to add an example on how to fit your model to some dataset and report the obtained results, see for instance `./cornac/examples/pcrl_example.py`. All examples, should be added to the `examples/` directory, listed in `examples/README.md` under section: Examples by Algorithm, and referenced in models table in `./README.md`. +We highly encourage you to add an example on how to fit your model to some dataset and report the obtained results, see for instance `examples/pcrl_example.py`. All examples, should be added to the `examples/` directory, listed in `examples/README.md` in the section that fits the model, and referenced in models table in `./README.md`. ## Summary @@ -125,13 +128,13 @@ In short, contributing a recommender model to Cornac involves, - Creating new files - [x] ./cornac/models/model_name/\_\_init__.py - [x] ./cornac/models/model_name/recom_model_name.py - - [x] ./cornac/models/model_name/requirement.txt (optional) + - [x] ./cornac/models/model_name/requirements.txt (optional) - Implementing two functions - [x] Recommender.fit() - [x] Recommender.score() - Updating existing files - [x] ./cornac/models/\_\_init__.py - - [x] ./docs/source/models.rst + - [x] ./docs/source/api_ref/models.rst - [x] ./README.md As a concrete example, you can take a look at one of the Cornac's model implementations inside `./cornac/models/`, as this may help you save time. From 9d22f653f401484508619bf324258774fa9da4e7 Mon Sep 17 00:00:00 2001 From: hieuddo Date: Mon, 16 Nov 2026 14:50:46 +0800 Subject: [PATCH 2/6] Complete the API reference and examples list --- docs/source/api_ref/datasets.rst | 35 +++++++++++++++ docs/source/api_ref/eval_methods.rst | 16 ++++--- docs/source/api_ref/experiment.rst | 5 +++ docs/source/api_ref/metrics.rst | 12 +++++ docs/source/api_ref/models.rst | 67 +++++++++++++++++++++++++--- examples/README.md | 12 ++++- 6 files changed, 133 insertions(+), 14 deletions(-) diff --git a/docs/source/api_ref/datasets.rst b/docs/source/api_ref/datasets.rst index 95468ebb9..153bfe2a1 100644 --- a/docs/source/api_ref/datasets.rst +++ b/docs/source/api_ref/datasets.rst @@ -20,6 +20,11 @@ Amazon Office .. automodule:: cornac.datasets.amazon_office :members: +Amazon Product Review +--------------------- +.. automodule:: cornac.datasets.amazon_review + :members: + Amazon Toys and Games --------------------- .. automodule:: cornac.datasets.amazon_toy @@ -30,6 +35,16 @@ CiteULike .. automodule:: cornac.datasets.citeulike :members: +Cosmetics +--------- +.. automodule:: cornac.datasets.cosmetics + :members: + +Diginetica +---------- +.. automodule:: cornac.datasets.diginetica + :members: + Epinions -------- .. automodule:: cornac.datasets.epinions @@ -40,6 +55,11 @@ FilmTrust .. automodule:: cornac.datasets.filmtrust :members: +Gowalla +------- +.. automodule:: cornac.datasets.gowalla + :members: + MovieLens --------- .. automodule:: cornac.datasets.movielens @@ -50,11 +70,26 @@ Netflix .. automodule:: cornac.datasets.netflix :members: +RetailRocket +------------ +.. automodule:: cornac.datasets.retailrocket + :members: + +Ta Feng +------- +.. automodule:: cornac.datasets.tafeng + :members: + Tradesy ------- .. automodule:: cornac.datasets.tradesy :members: +YooChoose +--------- +.. automodule:: cornac.datasets.yoochoose + :members: + Catalog Bundle Datasets ----------------------- diff --git a/docs/source/api_ref/eval_methods.rst b/docs/source/api_ref/eval_methods.rst index fb97565ac..fa52d6a6b 100644 --- a/docs/source/api_ref/eval_methods.rst +++ b/docs/source/api_ref/eval_methods.rst @@ -33,16 +33,21 @@ Timestamp Split .. automodule:: cornac.eval_methods.timestamp_split :members: +Next Basket Evaluation +---------------------- +.. automodule:: cornac.eval_methods.next_basket_evaluation + :members: + Next Item Evaluation -------------------- .. automodule:: cornac.eval_methods.next_item_evaluation :members: Recommendation Evaluation with Semantic IDs ------------------------------------------- +------------------------------------------- Use ``NextItemEvaluation`` for both ordinary next-item models (such as SASRec) -and Semantic ID models (TIGER, LETTER, RPG and DiffGRM), including a mixed +and Semantic ID models (TIGER, LETTER, RPG, DiffGRM and DIGER), including a mixed ``Experiment``. Its optional ``semantic_id_metrics`` switch defaults to False. Set it to True in Semantic ID experiment setup to enable the extra views. Ordinary item metric names and model-specific item resolution are preserved. @@ -90,7 +95,8 @@ view in the same way. For example:: evaluation = NextItemEvaluation.from_splits( - train, test, fmt="USIT", item_feature=features, + train, test, fmt="USIT", + item_feature=FeatureModality(features=features, ids=item_ids), semantic_id_metrics=True) Experiment(evaluation, [TIGER(device="cpu"), SASRec()], [Recall(10), NDCG(10)]).run() @@ -129,6 +135,6 @@ The given items of each held-out bundle become training rows of its queries and the remaining items are targets, so ordinary ranking metrics exclude exactly the given items, and item recommenders such as MostPop and ItemKNN are valid completion baselines. With ``set_metrics=True`` it also reports ``Set-F1`` and -``Set-Jaccard`` between the targets T and |T| constructed items, taken from +``Set-Jaccard`` between the targets T and ``|T|`` constructed items, taken from ``construct`` for a :class:`cornac.models.BundleConstructionRecommender` and -from the top |T| ranked items otherwise. +from the top ``|T|`` ranked items otherwise. diff --git a/docs/source/api_ref/experiment.rst b/docs/source/api_ref/experiment.rst index 31ffee2a4..6d5fa8cc2 100644 --- a/docs/source/api_ref/experiment.rst +++ b/docs/source/api_ref/experiment.rst @@ -18,6 +18,11 @@ CVResult .. automodule:: cornac.experiment.result :members: CVResult +PSTResult +--------- +.. autoclass:: cornac.experiment.result.PSTResult + :members: + ExperimentResult ---------------- .. automodule:: cornac.experiment.result diff --git a/docs/source/api_ref/metrics.rst b/docs/source/api_ref/metrics.rst index 4ee93fdfc..dd27bb2a2 100644 --- a/docs/source/api_ref/metrics.rst +++ b/docs/source/api_ref/metrics.rst @@ -3,6 +3,18 @@ Metrics .. automodule:: cornac.metrics +++++++++++++ +Base Classes +++++++++++++ + +Rating Metric +------------- +.. autoclass:: RatingMetric + +Ranking Metric +-------------- +.. autoclass:: RankingMetric + ++++++ Rating ++++++ diff --git a/docs/source/api_ref/models.rst b/docs/source/api_ref/models.rst index 88ae93527..e5045bc4c 100644 --- a/docs/source/api_ref/models.rst +++ b/docs/source/api_ref/models.rst @@ -17,7 +17,7 @@ Diffusion-based Generative Recommendation Model (DiffGRM) :members: Comparative Aspects and Opinions Ranking for Recommendation Explanations (Companion) -------------------------------------------------------------------------- +------------------------------------------------------------------------------------ .. automodule:: cornac.models.companion.recom_companion :members: @@ -95,7 +95,7 @@ Temporal-Item-Frequency-based User-KNN (TIFUKNN) :members: Correlation-Sensitive Next-Basket Recommendation (Beacon) ---------------------------------------------------- +--------------------------------------------------------- .. automodule:: cornac.models.beacon.recom_beacon :members: @@ -249,9 +249,23 @@ Collaborative Topic Regression (CTR) .. automodule:: cornac.models.ctr.recom_ctr :members: +Approximate Nearest Neighbor Search +----------------------------------- +.. automodule:: cornac.models.ann.recom_ann_annoy + :members: + +.. automodule:: cornac.models.ann.recom_ann_faiss + :members: + +.. automodule:: cornac.models.ann.recom_ann_hnswlib + :members: + +.. automodule:: cornac.models.ann.recom_ann_scann + :members: + Baseline Only ------------- -.. autoclass:: cornac.models.baseline_only.recom_bo +.. automodule:: cornac.models.baseline_only.recom_bo :members: Bayesian Personalized Ranking (BPR) @@ -259,6 +273,11 @@ Bayesian Personalized Ranking (BPR) .. autoclass:: cornac.models.bpr.recom_bpr.BPR :members: +BERT4Rec: Sequential Recommendation with Bidirectional Encoder Representations from Transformer (BERT4Rec) +---------------------------------------------------------------------------------------------------------- +.. automodule:: cornac.models.bert4rec.recom_bert4rec + :members: + Bundle Popularity (BundlePop) ----------------------------- .. automodule:: cornac.models.bundle_pop.recom_bundle_pop @@ -267,13 +286,23 @@ Bundle Popularity (BundlePop) Factorization Machines (FM) --------------------------- .. autoclass:: cornac.models.fm.recom_fm.FM - :members + :members: + +Factorizing Personalized Markov Chains (FPMC) +--------------------------------------------- +.. automodule:: cornac.models.fpmc.recom_fpmc + :members: Global Average (GlobalAvg) -------------------------- .. automodule:: cornac.models.global_avg.recom_global_avg :members: +Global Personalized Top Frequent (GPTop) +---------------------------------------- +.. automodule:: cornac.models.gp_top.recom_gp_top + :members: + Item K-Nearest-Neighbors (ItemKNN) ---------------------------------- .. autoclass:: cornac.models.knn.recom_knn.ItemKNN @@ -309,6 +338,21 @@ Probabilitic Matrix Factorization (PMF) .. automodule:: cornac.models.pmf.recom_pmf :members: +Recommender Systems with Generative Retrieval (TIGER) +----------------------------------------------------- +.. automodule:: cornac.models.tiger.recom_tiger + :members: + +Scalable Approximate NonSymmetric Autoencoder (SANSA) +----------------------------------------------------- +.. automodule:: cornac.models.sansa.recom_sansa + :members: + +Self-Attentive Sequential Recommendation (SASRec) +------------------------------------------------- +.. automodule:: cornac.models.sasrec.recom_sasrec + :members: + Session Popular (SPop) ---------------------- .. automodule:: cornac.models.spop.recom_spop @@ -329,20 +373,29 @@ Social Recommendation using PMF (SoRec) .. automodule:: cornac.models.sorec.recom_sorec :members: +Transformers4Rec-style Unified Transformer Recommender (TransformerRec) +----------------------------------------------------------------------- +.. automodule:: cornac.models.transformer_rec.recom_transformer_rec + :members: + User K-Nearest-Neighbors (UserKNN) ---------------------------------- .. autoclass:: cornac.models.knn.recom_knn.UserKNN :members: +View-Enhanced Bayesian Personalized Ranking (VEBPR) +--------------------------------------------------- +.. autoclass:: cornac.models.bpr.recom_vebpr.VEBPR + :members: + Weighted Matrix Factorization (WMF) ----------------------------------- .. automodule:: cornac.models.wmf.recom_wmf :members: Semantic ID Model Contracts --------------------------- -.. autoclass:: cornac.models.recommender.SemanticIDMixin - :members: +--------------------------- +See :class:`~cornac.models.recommender.SemanticIDMixin` under `Recommender (Generic Class)`_. DIGER ----- diff --git a/examples/README.md b/examples/README.md index 6c6f15afe..d66ff9e15 100644 --- a/examples/README.md +++ b/examples/README.md @@ -18,6 +18,8 @@ [param_search.py](param_search.py) - Hyper-parameter tuning with GridSearch and RandomSearch. +[ann_example.py](ann_example.py) - Example for comparing different ANN searchers (Annoy, Faiss, HNSWLib, ScaNN) with BPR model on Netflix dataset. + ---- ## Multimodal Algorithms (Using Auxiliary Data) @@ -62,14 +64,20 @@ [efm_example.py](efm_example.py) - Explicit Factor Model (EFM) with Amazon Toy and Games dataset. -[hft_example.py](hft_example.py) - Hidden Factor Topic (HFT) with MovieLen 1m dataset. +[hft_example.py](hft_example.py) - Hidden Factor Topic (HFT) with MovieLens 1M dataset. + +[hrdr_example.py](hrdr_example.py) - Hybrid neural recommendation with joint deep representation learning of ratings and reviews (HRDR) with Amazon Digital Music dataset. [lrppm_example.py](lrppm_example.py) - Learn to Rank user Preferences based on Phrase-level sentiment analysis across Multiple categories (LRPPM) with Amazon Toy and Games dataset. [mter_example.py](mter_example.py) - Multi-Task Explainable Recommendation (MTER) with Amazon Toy and Games dataset. +[narre_example.py](narre_example.py) - Neural Attention Rating Regression with Review-level Explanations (NARRE) with Amazon Digital Music dataset. + ### Image +[amr_clothing.py](amr_clothing.py) - Adversarial Training Towards Robust Multimedia Recommender System (AMR) with Amazon Clothing dataset. + [causalrec_clothing.py](causalrec_clothing.py) - CausalRec with Clothing dataset. [dmrl_clothes_example.py](dmrl_clothes_example.py) - Disentangled Multimodal Representation Learning (DMRL) with Amazon clothing dataset. @@ -106,7 +114,7 @@ [sansa_movielens.py](sansa_movielens.py) - Scalable Approximate NonSymmetric Autoencoder (SANSA) with MovieLens 1M dataset. -[sansa_tradesy.py](sansa_movielens.py) - Scalable Approximate NonSymmetric Autoencoder (SANSA) with Tradesy dataset. +[sansa_tradesy.py](sansa_tradesy.py) - Scalable Approximate NonSymmetric Autoencoder (SANSA) with Tradesy dataset. [skm_movielens.py](skm_movielens.py) - SKMeans vs BPR on MovieLens data. From c5e6489134a0264f1b581a1e17b04c4c191411a8 Mon Sep 17 00:00:00 2001 From: hieuddo Date: Mon, 16 Nov 2026 16:34:40 +0800 Subject: [PATCH 3/6] Consolidate the Contributors Guide --- docs/source/api_ref/models.rst | 4 +- docs/source/conf.py | 3 + docs/source/developer/add_metric.md | 2 + docs/source/developer/add_model.md | 2 + docs/source/developer/contributing.rst | 54 +- docs/source/developer/gettingstarted.rst | 57 -- docs/source/developer/guidelines.md | 5 + docs/source/developer/index.rst | 6 +- docs/source/index.rst | 2 +- docs/source/user/iamaresearcher.rst | 668 +---------------------- tutorials/README.md | 1 + tutorials/add_metric.md | 2 +- tutorials/add_model.md | 94 +++- 13 files changed, 141 insertions(+), 759 deletions(-) create mode 100644 docs/source/developer/add_metric.md create mode 100644 docs/source/developer/add_model.md delete mode 100644 docs/source/developer/gettingstarted.rst create mode 100644 docs/source/developer/guidelines.md diff --git a/docs/source/api_ref/models.rst b/docs/source/api_ref/models.rst index e5045bc4c..4a884aec7 100644 --- a/docs/source/api_ref/models.rst +++ b/docs/source/api_ref/models.rst @@ -333,8 +333,8 @@ Non-negative Matrix Factorization (NMF) .. automodule:: cornac.models.nmf.recom_nmf :members: -Probabilitic Matrix Factorization (PMF) ---------------------------------------- +Probabilistic Matrix Factorization (PMF) +---------------------------------------- .. automodule:: cornac.models.pmf.recom_pmf :members: diff --git a/docs/source/conf.py b/docs/source/conf.py index ff55ba3bf..877ca801b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -57,6 +57,9 @@ "sphinx_copybutton", ] +# Render "- [x]" lists in the Markdown pages included from the repository. +myst_enable_extensions = ["tasklist"] + # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] diff --git a/docs/source/developer/add_metric.md b/docs/source/developer/add_metric.md new file mode 100644 index 000000000..c0bccfd74 --- /dev/null +++ b/docs/source/developer/add_metric.md @@ -0,0 +1,2 @@ +```{include} ../../../tutorials/add_metric.md +``` diff --git a/docs/source/developer/add_model.md b/docs/source/developer/add_model.md new file mode 100644 index 000000000..965b4103e --- /dev/null +++ b/docs/source/developer/add_model.md @@ -0,0 +1,2 @@ +```{include} ../../../tutorials/add_model.md +``` diff --git a/docs/source/developer/contributing.rst b/docs/source/developer/contributing.rst index a89580563..a60aae014 100644 --- a/docs/source/developer/contributing.rst +++ b/docs/source/developer/contributing.rst @@ -1,6 +1,18 @@ Contributing to Cornac ====================== +This page walks you through setting up Cornac for development and opening a pull request. + +Prerequisites +^^^^^^^^^^^^^ + +Before contributing to Cornac, make sure you have the following prerequisites: + +- Python 3.10 or newer +- A C++ compiler, because parts of Cornac are written in Cython +- Git +- Virtual Environment (optional but recommended) + Fork the Repository ^^^^^^^^^^^^^^^^^^^ Click the "Fork" button on the Cornac GitHub repository @@ -13,6 +25,15 @@ Clone your forked repository to your local machine using the following command: .. code-block:: bash git clone https://github.com/your-github-id/cornac.git + cd cornac + +Setting Up Your Development Environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Create a virtual environment, build Cornac and run the tests with the commands +under "Development Setup" in :doc:`/developer/guidelines`. + +Now you are ready to contribute to Cornac! Create a New Branch ^^^^^^^^^^^^^^^^^^^ @@ -36,23 +57,11 @@ Testing your Changes Build Cornac on your environment, followed by testing it on an example to ensure your changes are working as expected. -1. To build Cornac on your environment: - -.. code-block:: bash +1. If you changed a Cython (``.pyx``) file, build Cornac on your environment again: - python setup.py build_ext --inplace - pip install -e ".[tests]" + .. code-block:: bash - -.. note:: - - The following packages are required for building Cornac on your environment: ``Cython``, ``numpy``, ``scipy``. - - If you do not have them, install by using the following commands: - - .. code-block:: bash - - pip3 install Cython numpy scipy + python setup.py build_ext --inplace 2. Run an example depending on what you are fixing/enhancing on. @@ -99,26 +108,28 @@ Please be patient during the review process, and be prepared to address any feed Development Guidelines -====================== +^^^^^^^^^^^^^^^^^^^^^^ + +:doc:`/developer/guidelines` sums up what we check when we review a pull request. Documentation -^^^^^^^^^^^^^ +~~~~~~~~~~~~~ Contributions should include relevant and concise documentation. This includes docstrings, comments, and updates to the official documentation when needed. Communication -============= +^^^^^^^^^^^^^ Issues -^^^^^^ +~~~~~~ If you encounter bugs or have ideas for improvements, create an issue on the GitHub issue tracker at https://github.com/PreferredAI/cornac/issues. Review Process -^^^^^^^^^^^^^^ +~~~~~~~~~~~~~~ Your pull request will be reviewed by Cornac maintainers. They will provide feedback and request changes if necessary. @@ -127,7 +138,7 @@ As this is an open source project, the repository is maintained on a voluntary basis. We thank you for your patience during the review process. License -^^^^^^^ +~~~~~~~ By contributing to Cornac, you agree that your code will be released under the Apache 2.0 License. Make sure to include the appropriate license headers in your files. @@ -135,4 +146,3 @@ Make sure to include the appropriate license headers in your files. **Thank you for contributing to Cornac! Your contributions are greatly appreciated and help make Cornac a better tool for everyone.** - diff --git a/docs/source/developer/gettingstarted.rst b/docs/source/developer/gettingstarted.rst deleted file mode 100644 index 66c95ffa3..000000000 --- a/docs/source/developer/gettingstarted.rst +++ /dev/null @@ -1,57 +0,0 @@ -Getting Started -=============== - -Prerequisites -^^^^^^^^^^^^^ - -Before contributing to Cornac, make sure you have the following prerequisites: -- Python 3.10 or newer -- Git -- Virtual Environment (optional but recommended) - - -Setting Up Your Development Environment -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -1. Fork the Cornac repository on GitHub. -2. Clone your fork to your local machine. -3. Create a virtual environment and install the necessary packages using pip. - -.. code-block:: bash - - git clone https://github.com/your-github-id/cornac.git - cd cornac - python -m venv venv - source venv/bin/activate # On Windows, use 'venv\Scripts\activate' - pip install Cython numpy scipy - python setup.py build_ext --inplace - pip install -e ".[tests]" - pytest - -Now you are ready to contribute to Cornac! - -Contributing -^^^^^^^^^^^^ - -Cornac is an open-source project and we welcome contributions of all kinds. -We welcome pull requests for new features such as models, datasets, metrics -and anything that could make Cornac a better tool for all. - - -How to Contribute -^^^^^^^^^^^^^^^^^ - -View :doc:`/developer/contributing` for more information on how to contribute. - - -Creating a new model -^^^^^^^^^^^^^^^^^^^^ - -View https://github.com/PreferredAI/cornac/blob/master/tutorials/add_model.md -for more information on how to create a new model. - -Adding a new metric -^^^^^^^^^^^^^^^^^^^ - -View https://github.com/PreferredAI/cornac/blob/master/tutorials/add_metric.md -for more information on how to add a new metric. diff --git a/docs/source/developer/guidelines.md b/docs/source/developer/guidelines.md new file mode 100644 index 000000000..7ac88bc00 --- /dev/null +++ b/docs/source/developer/guidelines.md @@ -0,0 +1,5 @@ +# Development Guidelines + +```{include} ../../../CONTRIBUTING.md +:start-line: 1 +``` diff --git a/docs/source/developer/index.rst b/docs/source/developer/index.rst index 8bba5e07c..2d14717b0 100644 --- a/docs/source/developer/index.rst +++ b/docs/source/developer/index.rst @@ -11,8 +11,10 @@ Whether you are new to open source or an experienced contributor, you can help u .. toctree:: :glob: - :maxdepth: 2 + :maxdepth: 1 :caption: Contributing - gettingstarted contributing + guidelines + add_model + add_metric diff --git a/docs/source/index.rst b/docs/source/index.rst index a49e4b52b..5475c92b1 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -87,7 +87,7 @@ Quick Links +++ - .. button-ref:: user/iamaresearcher + .. button-ref:: developer/guidelines :color: primary :expand: :click-parent: diff --git a/docs/source/user/iamaresearcher.rst b/docs/source/user/iamaresearcher.rst index 1ff0e7b13..671a9365e 100644 --- a/docs/source/user/iamaresearcher.rst +++ b/docs/source/user/iamaresearcher.rst @@ -235,574 +235,8 @@ with a Recall@100 score of 0.6988. Adding your own model --------------------- -Adding your own model on Cornac is easy. Cornac is designed to be flexible and -extensible, allowing researchers to easily add their own models into the -framework. - -Files to add -^^^^^^^^^^^^ - -Below is an example of the ``PMF`` model which was already added into Cornac. -We will use this as a reference to add our own model. - -.. code-block:: bash - - cornac - |-- cornac - | |-- models - | |-- pmf - | |-- __init__.py - | |-- recom_pmf.py - |-- examples - |-- pmf_ratio.py - -.. dropdown:: 1. Create the base folder for your model - - .. code-block:: bash - - cornac - |-- cornac - |-- models - |-- pmf - -.. dropdown:: 2. Create the ``__init__.py`` file in the ``pmf`` folder - - Add the following line to the ``__init__.py`` file in your model folder. - The ``.recom_pmf`` coincides with the name of the file that contains the - model, and ``PMF`` coincides with the name of the class in the - ``recon_pmf.py`` file. - - .. code-block:: python - :caption: cornac/cornac/models/pmf/__init__.py - - from .recom_pmf import PMF - - -.. dropdown:: 3. Create the ``recom_pmf.py`` file in the ``pmf`` folder - - The ``recom_pmf.py`` file contains the logic of the model. This includes - the training and testing portions of the model. - - Core to the ``recom_pmf.py`` file is the ``PMF`` class. This class inherits - from the :class:`~cornac.models.Recommender` class. The ``PMF`` class - implements the following methods: - - - :meth:`~cornac.models.Recommender.__init__`: The constructor of the class - - :meth:`~cornac.models.Recommender.fit`: The training procedure of the model - - :meth:`~cornac.models.Recommender.score`: The scoring function of the model - - .. code-block:: python - :caption: __init__ method: The constructor - - # Here we initialize parameters and variables - - def __init__( - self, - k=5, - max_iter=100, - learning_rate=0.001, - gamma=0.9, - lambda_reg=0.001, - name="PMF", - variant="non_linear", - trainable=True, - verbose=False, - init_params=None, - seed=None, - ): - Recommender.__init__(self, name=name, trainable=trainable, verbose=verbose) - self.k = k - self.max_iter = max_iter - self.learning_rate = learning_rate - self.gamma = gamma - self.lambda_reg = lambda_reg - self.variant = variant - self.seed = seed - - self.ll = np.full(max_iter, 0) - self.eps = 0.000000001 - - # Init params if provided - self.init_params = {} if init_params is None else init_params - self.U = self.init_params.get("U", None) # matrix of user factors - self.V = self.init_params.get("V", None) # matrix of item factors - - .. code-block:: python - :caption: fit method: The training procedure - - # Here we implement the training procedure of the model - - def fit(self, train_set, val_set=None): - """Fit the model to observations. - - Parameters - ---------- - train_set: :obj:`cornac.data.Dataset`, required - User-Item preference data as well as additional modalities. - - val_set: :obj:`cornac.data.Dataset`, optional, default: None - User-Item preference data for model selection purposes (e.g., early stopping). - - Returns - ------- - self : object - """ - Recommender.fit(self, train_set) - - from cornac.models.pmf import pmf - - if self.trainable: - # converting data to the triplet format (needed for cython function pmf) - (uid, iid, rat) = train_set.uir_tuple - rat = np.array(rat, dtype="float32") - if self.variant == "non_linear": # need to map the ratings to [0,1] - if [self.min_rating, self.max_rating] != [0, 1]: - rat = scale(rat, 0.0, 1.0, self.min_rating, self.max_rating) - uid = np.array(uid, dtype="int32") - iid = np.array(iid, dtype="int32") - - if self.verbose: - print("Learning...") - - # use pre-trained params if exists, otherwise from constructor - init_params = {"U": self.U, "V": self.V} - - if self.variant == "linear": - res = pmf.pmf_linear( - uid, - iid, - rat, - k=self.k, - n_users=self.num_users, - n_items=self.num_items, - n_ratings=len(rat), - n_epochs=self.max_iter, - lambda_reg=self.lambda_reg, - learning_rate=self.learning_rate, - gamma=self.gamma, - init_params=init_params, - verbose=self.verbose, - seed=self.seed, - ) - elif self.variant == "non_linear": - res = pmf.pmf_non_linear( - uid, - iid, - rat, - k=self.k, - n_users=self.num_users, - n_items=self.num_items, - n_ratings=len(rat), - n_epochs=self.max_iter, - lambda_reg=self.lambda_reg, - learning_rate=self.learning_rate, - gamma=self.gamma, - init_params=init_params, - verbose=self.verbose, - seed=self.seed, - ) - else: - raise ValueError('variant must be one of {"linear","non_linear"}') - - self.U = np.asarray(res["U"]) - self.V = np.asarray(res["V"]) - - if self.verbose: - print("Learning completed") - - elif self.verbose: - print("%s is trained already (trainable = False)" % (self.name)) - - return self - - .. code-block:: python - :caption: score method: The scoring function - - # Here we implement the scoring function of the model. - # If item-idx is not provided, return scores for all known items - # of the users. Otherwise, return the score of the user-item pair - - def score(self, user_idx, item_idx=None): - """Predict the scores/ratings of a user for an item. - - Parameters - ---------- - user_idx: int, required - The index of the user for whom to perform score prediction. - - item_idx: int, optional, default: None - The index of the item for which to perform score prediction. - If None, scores for all known items will be returned. - - Returns - ------- - res : A scalar or a Numpy array - Relative scores that the user gives to the item or to all known items - - """ - if item_idx is None: - if not self.knows_user(user_idx): - raise ScoreException( - "Can't make score prediction for (user_id=%d)" % user_idx - ) - - known_item_scores = self.V.dot(self.U[user_idx, :]) - return known_item_scores - else: - if not self.knows_user(user_idx) or not self.knows_item(item_idx): - raise ScoreException( - "Can't make score prediction for (user_id=%d, item_id=%d)" - % (user_idx, item_idx) - ) - - user_pred = self.V[item_idx, :].dot(self.U[user_idx, :]) - - if self.variant == "non_linear": - user_pred = sigmoid(user_pred) - user_pred = scale(user_pred, self.min_rating, self.max_rating, 0.0, 1.0) - - return user_pred - - Putting everything together, below we have the whole recom_pmf.py file: - - .. code-block:: python - :caption: cornac/cornac/models/pmf/recom_pmf.py - - import numpy as np - - from ..recommender import Recommender - from ...utils.common import sigmoid - from ...utils.common import scale - from ...exception import ScoreException - - - class PMF(Recommender): - """Probabilistic Matrix Factorization. - - Parameters - ---------- - k: int, optional, default: 5 - The dimension of the latent factors. - - max_iter: int, optional, default: 100 - Maximum number of iterations or the number of epochs for SGD. - - learning_rate: float, optional, default: 0.001 - The learning rate for SGD_RMSProp. - - gamma: float, optional, default: 0.9 - The weight for previous/current gradient in RMSProp. - - lambda_reg: float, optional, default: 0.001 - The regularization coefficient. - - name: string, optional, default: 'PMF' - The name of the recommender model. - - variant: {"linear","non_linear"}, optional, default: 'non_linear' - Pmf variant. If 'non_linear', the Gaussian mean is the output of a Sigmoid function.\ - If 'linear' the Gaussian mean is the output of the identity function. - - trainable: boolean, optional, default: True - When False, the model is not trained and Cornac assumes that the model already \ - pre-trained (U and V are not None). - - verbose: boolean, optional, default: False - When True, some running logs are displayed. - - init_params: dict, optional, default: None - List of initial parameters, e.g., init_params = {'U':U, 'V':V}. - - U: ndarray, shape (n_users, k) - User latent factors. - - V: ndarray, shape (n_items, k) - Item latent factors. - - seed: int, optional, default: None - Random seed for parameters initialization. - - References - ---------- - * Mnih, Andriy, and Ruslan R. Salakhutdinov. Probabilistic matrix factorization. \ - In NIPS, pp. 1257-1264. 2008. - """ - - def __init__( - self, - k=5, - max_iter=100, - learning_rate=0.001, - gamma=0.9, - lambda_reg=0.001, - name="PMF", - variant="non_linear", - trainable=True, - verbose=False, - init_params=None, - seed=None, - ): - Recommender.__init__(self, name=name, trainable=trainable, verbose=verbose) - self.k = k - self.max_iter = max_iter - self.learning_rate = learning_rate - self.gamma = gamma - self.lambda_reg = lambda_reg - self.variant = variant - self.seed = seed - - self.ll = np.full(max_iter, 0) - self.eps = 0.000000001 - - # Init params if provided - self.init_params = {} if init_params is None else init_params - self.U = self.init_params.get("U", None) # matrix of user factors - self.V = self.init_params.get("V", None) # matrix of item factors - - def fit(self, train_set, val_set=None): - """Fit the model to observations. - - Parameters - ---------- - train_set: :obj:`cornac.data.Dataset`, required - User-Item preference data as well as additional modalities. - - val_set: :obj:`cornac.data.Dataset`, optional, default: None - User-Item preference data for model selection purposes (e.g., early stopping). - - Returns - ------- - self : object - """ - Recommender.fit(self, train_set) - - from cornac.models.pmf import pmf - - if self.trainable: - # converting data to the triplet format (needed for cython function pmf) - (uid, iid, rat) = train_set.uir_tuple - rat = np.array(rat, dtype="float32") - if self.variant == "non_linear": # need to map the ratings to [0,1] - if [self.min_rating, self.max_rating] != [0, 1]: - rat = scale(rat, 0.0, 1.0, self.min_rating, self.max_rating) - uid = np.array(uid, dtype="int32") - iid = np.array(iid, dtype="int32") - - if self.verbose: - print("Learning...") - - # use pre-trained params if exists, otherwise from constructor - init_params = {"U": self.U, "V": self.V} - - if self.variant == "linear": - res = pmf.pmf_linear( - uid, - iid, - rat, - k=self.k, - n_users=self.num_users, - n_items=self.num_items, - n_ratings=len(rat), - n_epochs=self.max_iter, - lambda_reg=self.lambda_reg, - learning_rate=self.learning_rate, - gamma=self.gamma, - init_params=init_params, - verbose=self.verbose, - seed=self.seed, - ) - elif self.variant == "non_linear": - res = pmf.pmf_non_linear( - uid, - iid, - rat, - k=self.k, - n_users=self.num_users, - n_items=self.num_items, - n_ratings=len(rat), - n_epochs=self.max_iter, - lambda_reg=self.lambda_reg, - learning_rate=self.learning_rate, - gamma=self.gamma, - init_params=init_params, - verbose=self.verbose, - seed=self.seed, - ) - else: - raise ValueError('variant must be one of {"linear","non_linear"}') - - self.U = np.asarray(res["U"]) - self.V = np.asarray(res["V"]) - - if self.verbose: - print("Learning completed") - - elif self.verbose: - print("%s is trained already (trainable = False)" % (self.name)) - - return self - - def score(self, user_idx, item_idx=None): - """Predict the scores/ratings of a user for an item. - - Parameters - ---------- - user_idx: int, required - The index of the user for whom to perform score prediction. - - item_idx: int, optional, default: None - The index of the item for which to perform score prediction. - If None, scores for all known items will be returned. - - Returns - ------- - res : A scalar or a Numpy array - Relative scores that the user gives to the item or to all known items - - """ - if item_idx is None: - if not self.knows_user(user_idx): - raise ScoreException( - "Can't make score prediction for (user_id=%d)" % user_idx - ) - - known_item_scores = self.V.dot(self.U[user_idx, :]) - return known_item_scores - else: - if not self.knows_user(user_idx) or not self.knows_item(item_idx): - raise ScoreException( - "Can't make score prediction for (user_id=%d, item_id=%d)" - % (user_idx, item_idx) - ) - - user_pred = self.V[item_idx, :].dot(self.U[user_idx, :]) - - if self.variant == "non_linear": - user_pred = sigmoid(user_pred) - user_pred = scale(user_pred, self.min_rating, self.max_rating, 0.0, 1.0) - - return user_pred - - -.. dropdown:: 4. Create the example file in the ``examples`` folder - - .. code-block:: python - :caption: cornac/examples/pmf_ratio.py - - """Example to run Probabilistic Matrix Factorization (PMF) model with Ratio Split evaluation strategy""" - - import cornac - from cornac.datasets import movielens - from cornac.eval_methods import RatioSplit - from cornac.models import PMF - - - # Load the MovieLens 100K dataset - ml_100k = movielens.load_feedback() - - # Instantiate an evaluation method. - ratio_split = RatioSplit( - data=ml_100k, test_size=0.2, rating_threshold=4.0, exclude_unknowns=False - ) - - # Instantiate a PMF recommender model. - pmf = PMF(k=10, max_iter=100, learning_rate=0.001, lambda_reg=0.001) - - # Instantiate evaluation metrics. - mae = cornac.metrics.MAE() - rmse = cornac.metrics.RMSE() - rec_20 = cornac.metrics.Recall(k=20) - pre_20 = cornac.metrics.Precision(k=20) - - # Instantiate and then run an experiment. - cornac.Experiment( - eval_method=ratio_split, - models=[pmf], - metrics=[mae, rmse, rec_20, pre_20], - user_based=True, - ).run() - -Files to edit -^^^^^^^^^^^^^ - -To add your model to the overall Cornac package, you need to edit the following -file: - -.. code-block:: bash - - cornac - |-- cornac - |-- models - |-- __init__.py - -.. dropdown:: Edit the models/__init__.py - - .. code-block:: python - :caption: cornac/cornac/models/__init__.py - - from .amr import AMR - ... # models removed for brevity - from .pmf import PMF # Add this line - ... # models removed for brevity - - -Now you have implemented your model, it is time to test it. -In order to do so, you have to rebuild Cornac. We will discuss on how to do -this in the next section. - -.. topic:: View related tutorial on Github - - View the add model guide on Github: - https://github.com/PreferredAI/cornac/blob/master/tutorials/add_model.md - -Development workflow --------------------- - -Before we move on to the section of building a new model, let's take a look at -the development workflow of Cornac. - -First time setup -^^^^^^^^^^^^^^^^ - -As Cornac contains models which uses Cython, compilation is required before -testing could be done. In order to do so, you first need to install Cython and -run the following command: - -.. code-block:: bash - - python setup.py build_ext --inplace - -This will generate C++ files from Cython files, compile the C++ files, and place the compiled binary files in the necessary folders. - -The main workflow of developing a new model will be to: - -1. Implement model files -2. Create an example -3. Run the example - -Folder structure for testing -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. code-block:: bash - - cornac - |-- cornac - | |-- models - | |-- mymodel - | | |-- __init__.py - | | |-- recom_mymodel.py - | |-- requirements.txt - |-- mymodel_example.py <-- not in the examples folder - -To run the example, ensure that your current working directory is in the top -``cornac`` folder. Then, run the following command: - -.. code-block:: bash - - python mymodel_example.py - -Whenever a new change is done to your model files, just run the example for -testing and debugging. +The Contributors Guide shows how to add a model to Cornac, see +:doc:`/developer/add_model`. Analyze results --------------- @@ -824,106 +258,10 @@ To do so, simply add you model to the list of models in the experiment. # run the experiment and compare the results cornac.Experiment(eval_method=rs, models=models, metrics=metrics, user_based=True).run() -Using additional packages -------------------------- - -Cornac is built on top of the popular scientific computing libraries such as -NumPy and SciPy. It is also designed to be compatible with the popular deep learning -libraries such as PyTorch and TensorFlow. - -If you are using additional packages in your model, you can add them into the -``requirements.txt`` file. This will ensure that the packages are installed - -.. code-block:: bash - - cornac - |-- cornac - | |-- models - | |-- ngcf - | |-- __init__.py - | |-- recom_ngcf.py - | |-- requirements.txt <-- Add this file - |-- examples - |-- ngcf_example.py - -Your requirements.txt file should look like this: - -.. code-block:: bash - :caption: cornac/cornac/models/ngcf/requirements.txt - - torch>=2.0.0 - dgl>=1.1.0 - -This is generated by doing a ``pip freeze > requirements.txt`` command on your -environment. - -Model file structure -^^^^^^^^^^^^^^^^^^^^ - -Your model file should have special dependencies imported only in the -fit/score functions. This is to ensure that Cornac can be built without -installing the additional packages. - -For example, in the code snippet below from the ``NGCF`` model, the ``fit`` -function imports the ``torch`` package. This is to ensure that the ``torch`` -package is only imported when the ``fit`` function is called. - -.. code-block:: python - :caption: cornac/cornac/models/ngcf/recom_ngcf.py - - def fit(self, train_set, val_set=None): - """Fit the model to observations. - - Parameters - ---------- - train_set: :obj:`cornac.data.Dataset`, required - User-Item preference data as well as additional modalities. - - val_set: :obj:`cornac.data.Dataset`, optional, default: None - User-Item preference data for model selection purposes (e.g., early stopping). - - Returns - ------- - self : object - """ - Recommender.fit(self, train_set, val_set) - - if not self.trainable: - return self - - # model setup - import torch - from .ngcf import Model - from .ngcf import construct_graph - - self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu") - if self.seed is not None: - torch.manual_seed(self.seed) - if torch.cuda.is_available(): - torch.cuda.manual_seed_all(self.seed) - - graph = construct_graph(train_set, self.total_users, self.total_items).to(self.device) - model = Model( - graph, - self.emb_size, - self.layer_sizes, - self.dropout_rates, - self.lambda_reg, - ).to(self.device) - - # remaining codes removed for brevity - Adding a new metric ------------------- -Cornac provides a wide range of evaluation metrics for you to use. However, if -you would like to add your own metric, you can do so by extending the -:class:`~cornac.metrics.Metric` class. - -.. topic:: View related tutorial on Github - - View the add metric guide on Github: - https://github.com/PreferredAI/cornac/blob/master/tutorials/add_metric.md +The Contributors Guide shows how to add a metric, see :doc:`/developer/add_metric`. Let us know! ------------ diff --git a/tutorials/README.md b/tutorials/README.md index efbb62bef..1344e8edc 100644 --- a/tutorials/README.md +++ b/tutorials/README.md @@ -8,6 +8,7 @@ If you are new to Cornac, the [Getting Started](#getting-started) tutorials are - [Your first Cornac experiment](../README.md#getting-started-your-first-cornac-experiment) - [Hyperparameter search for VAECF](./param_search_vaecf.ipynb) - [Approximate nearest neighbor (ANN) search](./ann_hnswlib.ipynb) +- [Model ensembling: combine the predictions of BPR and WMF models](./model_ensembling.ipynb) - [Introduction to BPR, using Cornac with Microsoft Recommenders](https://github.com/microsoft/recommenders/blob/main/examples/02_model_collaborative_filtering/cornac_bpr_deep_dive.ipynb) - [Tutorials on recommender systems by Preferred.AI](https://github.com/PreferredAI/tutorials/tree/master/recommender-systems) - [BiVAE model with Microsoft Recommenders](https://github.com/microsoft/recommenders/blob/main/examples/02_model_collaborative_filtering/cornac_bivae_deep_dive.ipynb) diff --git a/tutorials/add_metric.md b/tutorials/add_metric.md index fc4c91442..a41828730 100644 --- a/tutorials/add_metric.md +++ b/tutorials/add_metric.md @@ -97,4 +97,4 @@ def test_mae(self): self.assertEqual(1, mae.compute(np.asarray([0, 1]), np.asarray([1, 0]))) self.assertEqual(2, mae.compute(np.asarray([0, 1]), np.asarray([2, 3]), np.asarray([1, 3]))) ``` -At this stage we are done and ready to create a pull request. \ No newline at end of file +At this stage we are done and ready to create a pull request. See [CONTRIBUTING.md](https://github.com/PreferredAI/cornac/blob/master/CONTRIBUTING.md) for how to run the tests and what we check when we review it. \ No newline at end of file diff --git a/tutorials/add_model.md b/tutorials/add_model.md index 2b7e67a04..defa184fe 100644 --- a/tutorials/add_model.md +++ b/tutorials/add_model.md @@ -4,7 +4,7 @@ This tutorial describes how to integrate a recommender model into Cornac. We ass ## Directory & file structure -For convenience assume that the model of interest is PMF. At this point it is useful to recall that Cornac follows the [PEP 8](https://www.python.org/dev/peps/pep-0008/) coding conventions. One good way to get started is to update the directory and file structure as follows. +For convenience assume that the model of interest is PMF. At this point it is useful to recall that Cornac follows the [PEP 8](https://www.python.org/dev/peps/pep-0008/) coding conventions. See [CONTRIBUTING.md](https://github.com/PreferredAI/cornac/blob/master/CONTRIBUTING.md) for how to check and format your code with Ruff. One good way to get started is to update the directory and file structure as follows. ``` cornac │ @@ -21,7 +21,7 @@ cornac ``` Note that you only need to add the `pmf` branch as the rest of the structure is already in place. -## Creating a model in 4 steps +## Creating a model in 5 steps ### 1. Extending the Recommender class @@ -86,11 +86,15 @@ When you perform rating prediction evaluation (e.g., in terms of RMSE) Cornac ca If your model cannot score a user or an item, for example one that was not in the training data, raise `ScoreException` from `cornac.exception` in `score()`. `rate()` and `rank()` catch it and fall back to a default score. The `score()` function of [PMF](https://github.com/PreferredAI/cornac/blob/master/cornac/models/pmf/recom_pmf.py) shows how. +#### Next-item and next-basket models +If your model recommends the next item of a session or the next basket of a user, extend `NextItemRecommender` or `NextBasketRecommender` instead. Both are in `cornac/models/recommender.py` and extend `Recommender`. Their `score()` function also receives the user's history, as `score(self, user_idx, history_items, **kwargs)` or `score(self, user_idx, history_baskets, **kwargs)`, and returns the scores of all known items. [GRU4Rec](https://github.com/PreferredAI/cornac/blob/master/cornac/models/gru4rec/recom_gru4rec.py) and [TIFUKNN](https://github.com/PreferredAI/cornac/blob/master/cornac/models/tifuknn/recom_tifuknn.py) are good examples to start from. + ### 2. Making your recommender available to Cornac As you may have already noticed, Cornac treats each recommender model as a separate module, so as to reduce coupling and ease the contribution of new models. This is the reason why you need to include a `pmf/__init__.py` file: ```python from .recom_pmf import PMF ``` +The `.recom_pmf` coincides with the name of the file that contains the model, and `PMF` coincides with the name of the class in the `recom_pmf.py` file. One last step is required to make your recommender model available to Cornac, which is to update `cornac/models/__init__.py` by adding the following line: ```python @@ -98,9 +102,79 @@ from .pmf import PMF ``` ### 3. Indicating dependencies -The file `requirements.txt` is optional as opposed to the others, and it is only needed if your implementation relies on some external libraries (e.g., TensorFlow, PyTorch) which are not Cornac dependencies. In this case you should include this file and indicate which versions of the libraries of interest are required. Here is a sample of a `requirements.txt` file: +The file `requirements.txt` is optional as opposed to the others, and it is only needed if your implementation relies on some external libraries (e.g., TensorFlow, PyTorch) which are not Cornac dependencies. In this case you should include this file and indicate which versions of the libraries of interest are required. Here is the `requirements.txt` file of the NGCF model: +``` +torch>=2.0.0 +dgl>=1.1.0 +``` + +List only the packages your model needs. The file sits next to your model files: + ``` -tensorflow>=1.10.0 +cornac +|-- cornac +| |-- models +| |-- ngcf +| |-- __init__.py +| |-- ngcf.py +| |-- recom_ngcf.py +| |-- requirements.txt <-- Add this file +|-- examples + |-- ngcf_example.py +``` + +#### Model file structure + +Your model file should have special dependencies imported only in the +fit/score functions. This is to ensure that Cornac can be imported without +installing the additional packages. + +For example, in the code snippet below from the [NGCF](https://github.com/PreferredAI/cornac/blob/master/cornac/models/ngcf/recom_ngcf.py) model, the `fit` +function imports the `torch` package. This is to ensure that the `torch` +package is only imported when the `fit` function is called. + +```python +def fit(self, train_set, val_set=None): + """Fit the model to observations. + + Parameters + ---------- + train_set: :obj:`cornac.data.Dataset`, required + User-Item preference data as well as additional modalities. + + val_set: :obj:`cornac.data.Dataset`, optional, default: None + User-Item preference data for model selection purposes (e.g., early stopping). + + Returns + ------- + self : object + """ + Recommender.fit(self, train_set, val_set) + + if not self.trainable: + return self + + # model setup + import torch + from .ngcf import Model + from .ngcf import construct_graph + + self.device = torch.device("cuda" if torch.cuda.is_available() else "cpu") + if self.seed is not None: + torch.manual_seed(self.seed) + if torch.cuda.is_available(): + torch.cuda.manual_seed_all(self.seed) + + graph = construct_graph(train_set, self.total_users, self.total_items).to(self.device) + model = Model( + graph, + self.emb_size, + self.layer_sizes, + self.dropout_rates, + self.lambda_reg, + ).to(self.device) + + # remaining codes removed for brevity ``` ### 4. Adding documentation @@ -114,11 +188,11 @@ Probabilistic Matrix Factorization (PMF) .. automodule:: cornac.models.pmf.recom_pmf :members: ``` -The last step is to add your algorithm into the Cornac's list of models table inside `./README.md`, for ease of reference purposes. -At this point you are done, and ready to create a pull request, congratulations! +The last step is to add your algorithm into the Cornac's list of models table inside `./README.md`; the Models Available page of the documentation is built from this table. +At this point your model is part of Cornac, congratulations! Before you create a pull request, add an example as described next. -### Including an example (optional) -We highly encourage you to add an example on how to fit your model to some dataset and report the obtained results, see for instance `examples/pcrl_example.py`. All examples, should be added to the `examples/` directory, listed in `examples/README.md` in the section that fits the model, and referenced in models table in `./README.md`. +### 5. Including an example +Please add an example on how to fit your model to some dataset and report the obtained results, see for instance `examples/pcrl_example.py`. All examples, should be added to the `examples/` directory, listed in `examples/README.md` in the section that fits the model, and referenced in models table in `./README.md`. ## Summary @@ -136,8 +210,10 @@ In short, contributing a recommender model to Cornac involves, - [x] ./cornac/models/\_\_init__.py - [x] ./docs/source/api_ref/models.rst - [x] ./README.md +- Adding an example + - [x] ./examples/model_name_example.py, listed in ./examples/README.md -As a concrete example, you can take a look at one of the Cornac's model implementations inside `./cornac/models/`, as this may help you save time. +As a concrete example, you can take a look at one of the Cornac's model implementations inside `./cornac/models/`, as this may help you save time. For instance, [recom_pmf.py](https://github.com/PreferredAI/cornac/blob/master/cornac/models/pmf/recom_pmf.py) is the complete PMF model, and [pmf_ratio.py](https://github.com/PreferredAI/cornac/blob/master/examples/pmf_ratio.py) runs it on MovieLens 100K. ## Using Cython and C/C++ (optional) From 0c9e29558596e8be9c25416996cb21945a252123 Mon Sep 17 00:00:00 2001 From: hieuddo Date: Mon, 16 Nov 2026 16:35:05 +0800 Subject: [PATCH 4/6] Merge the user guide into one guide --- README.md | 2 +- docs/source/user/evaluation.rst | 593 ++++++++++++++++++ docs/source/user/example-foodrecce.rst | 23 +- docs/source/user/iamadeveloper.rst | 725 ----------------------- docs/source/user/iamaresearcher.rst | 294 --------- docs/source/user/index.rst | 8 +- docs/source/user/owndata.rst | 275 ++++++++- docs/source/user/predict.rst | 145 ++++- docs/source/user/quickstart.rst | 22 +- docs/source/user/serving.rst | 508 ++++++++++++++++ docs/source/user/tasks.rst | 717 ++++++++++++++++++++++ tutorials/param_search_vaecf.ipynb | 2 +- tutorials/text_to_graph.ipynb | 2 +- tutorials/working_with_auxiliary_data.md | 2 +- 14 files changed, 2216 insertions(+), 1102 deletions(-) create mode 100644 docs/source/user/evaluation.rst delete mode 100644 docs/source/user/iamadeveloper.rst delete mode 100644 docs/source/user/iamaresearcher.rst create mode 100644 docs/source/user/serving.rst create mode 100644 docs/source/user/tasks.rst diff --git a/README.md b/README.md index 702cf3d16..c75a5fc94 100644 --- a/README.md +++ b/README.md @@ -122,7 +122,7 @@ $ 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](https://flask.palletsprojects.com/en/3.0.x/deploying/) server for model deployment in production. Please refer to [this](https://cornac.readthedocs.io/en/stable/user/iamadeveloper.html#running-an-api-service) guide for more details. +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](https://flask.palletsprojects.com/en/3.0.x/deploying/) server for model deployment in production. Please refer to [this](https://cornac.readthedocs.io/en/latest/user/serving.html#running-an-api-service) guide for more details. ## Model A/B testing diff --git a/docs/source/user/evaluation.rst b/docs/source/user/evaluation.rst new file mode 100644 index 000000000..432398161 --- /dev/null +++ b/docs/source/user/evaluation.rst @@ -0,0 +1,593 @@ +Evaluation and Tuning +===================== + +This page helps you measure how well recommendation models work, compare them +fairly, and tune their hyper-parameters. It covers how to split your data, +which metrics to choose, how to read the results Cornac gives you, and how to +search for good hyper-parameters. + +Conducting experiments +---------------------- + +Cornac provides a set of tools to help you conduct experiments. The main tool is +the :class:`~cornac.experiment.experiment.Experiment` class. As its name would suggest, this is +where you manage an experiment with a method to split dataset (e.g., by ratio, k-fold +cross-validation), a set of models to be compared with, and different evaluation metrics. + +Recap from the :doc:`/user/quickstart` example, the following code snippet shows +how to create an experiment with the MovieLens 100K dataset, split it into +training and testing sets, and run the experiment with the BPR recommender model +and the Precision, Recall evaluation metrics. + +.. code-block:: python + + import cornac + from cornac.eval_methods import RatioSplit + from cornac.models import BPR, PMF + from cornac.metrics import Precision, Recall + + # Load a sample dataset (e.g., MovieLens) + ml_100k = cornac.datasets.movielens.load_feedback() + + # Split the data into training and testing sets + rs = RatioSplit(data=ml_100k, test_size=0.2, rating_threshold=4.0, seed=123) + + # Instantiate a matrix factorization model (e.g., BPR) + models = [ + BPR(k=10, max_iter=200, learning_rate=0.001, lambda_reg=0.01, seed=123), + PMF(k=10, max_iter=100, learning_rate=0.001, lambda_reg=0.001, seed=123), + ] + + # Define metrics to evaluate the models + metrics = [Precision(k=10), Recall(k=10)] + + # put it together in an experiment, voilà! + cornac.Experiment(eval_method=rs, models=models, metrics=metrics, user_based=True).run() + +Analyze results +--------------- +Cornac makes it easy for you to run your model alongside other existing models. +To do so, simply add your model to the list of models in the experiment. Below, +``MF`` takes the place of your own model; :doc:`/developer/add_model` shows how +to write one. + +.. code-block:: python + + from cornac.metrics import RMSE + from cornac.models import MF + + # Add new model to list + models = [ + BPR(k=10, max_iter=200, learning_rate=0.001, lambda_reg=0.01, seed=123), + PMF(k=10, max_iter=100, learning_rate=0.001, lambda_reg=0.001, seed=123), + MF(k=10, max_iter=25, learning_rate=0.01, lambda_reg=0.02, seed=123), + ] + + # Define metrics to evaluate the models + metrics = [RMSE(), Precision(k=10), Recall(k=10)] + + # run the experiment and compare the results + cornac.Experiment(eval_method=rs, models=models, metrics=metrics, user_based=True).run() + +.. code-block:: bash + :caption: output + + TEST: + ... + | RMSE | Precision@10 | Recall@10 | Train (s) | Test (s) + --- + ------ + ------------ + --------- + --------- + -------- + BPR | 2.2267 | 0.1110 | 0.1195 | 1.4414 | 0.2735 + PMF | 0.9138 | 0.0813 | 0.0639 | 1.1986 | 0.2600 + MF | 0.8998 | 0.0675 | 0.0463 | 0.0249 | 0.2836 + +The rest of this page explains each part of an experiment. + +Choosing an evaluation method +----------------------------- + +The evaluation method decides which interactions a model learns from and which +are held out to test it. All methods take a few common arguments: +``rating_threshold`` (the lowest rating that counts as a positive for ranking +metrics), ``exclude_unknowns`` (skip test users and items that never appear in +training, ``True`` by default), and ``seed``. + +**Random split.** :class:`~cornac.eval_methods.ratio_split.RatioSplit` +shuffles all interactions and holds out a fraction for testing (``test_size``) +and, if you like, for validation (``val_size``). A value above 1 is read as a +number of interactions instead of a fraction. + +**Per-user split.** :class:`~cornac.eval_methods.stratified_split.StratifiedSplit` +splits each user's interactions separately, in the same proportions, so users +appear in both the training and the test set (``group_by="item"`` does the same +per item). With +``chrono=True`` and data that has timestamps, each user's earliest interactions +are used for training and the latest ones are held out. + +**Split by time.** :class:`~cornac.eval_methods.timestamp_split.TimestampSplit` +cuts all interactions at the same points in time: the latest ``test_size`` +fraction is the test set and the ``val_size`` fraction just before it is the +validation set. You can also give the cut-off times directly with +``val_timestamp`` and ``test_timestamp``. Models are then trained on the past +and tested on the future, as they would be in a live system. + +``TimestampSplit`` needs data with timestamps (``fmt="UIRT"``), and so does +``StratifiedSplit`` by default; pass it ``fmt="UIR"`` for data without them. + +.. code-block:: python + + from cornac.datasets import movielens + from cornac.eval_methods import StratifiedSplit, TimestampSplit + + data_t = movielens.load_feedback(fmt="UIRT", variant="100K") + + ss = StratifiedSplit( + data=data_t, + group_by="user", + chrono=True, + test_size=0.2, + rating_threshold=4.0, + seed=123, + ) + + ts = TimestampSplit(data=data_t, test_size=0.2, val_size=0.1, rating_threshold=4.0) + + print(ss.train_set.num_ratings, ss.test_set.num_ratings) + print(ts.train_set.num_ratings, ts.val_set.num_ratings, ts.test_set.num_ratings) + +.. code-block:: bash + :caption: output + + 79619 20295 + 69997 1697 2286 + +The time split keeps far fewer test ratings: many MovieLens users joined after +the cut-off, so the model has never seen them and ``exclude_unknowns=True`` +leaves them out. + +**Cross-validation.** :class:`~cornac.eval_methods.cross_validation.CrossValidation` +splits the data into ``n_folds`` parts and uses each one in turn as the test +set. The results show each fold, then the mean and standard deviation: + +.. code-block:: python + + from cornac.eval_methods import CrossValidation + + cv = CrossValidation(data=ml_100k, n_folds=5, rating_threshold=4.0, seed=123) + + cornac.Experiment( + eval_method=cv, + models=[MF(k=10, max_iter=25, learning_rate=0.01, lambda_reg=0.02, seed=123)], + metrics=[RMSE(), Recall(k=10)], + ).run() + +.. code-block:: bash + :caption: output + + TEST: + ... + [MF] + | RMSE | Recall@10 | Train (s) | Test (s) + ------ + ------ + --------- + --------- + -------- + Fold 0 | 0.9126 | 0.0524 | 0.0232 | 0.2862 + Fold 1 | 0.8996 | 0.0564 | 0.0236 | 0.2819 + Fold 2 | 0.9112 | 0.0558 | 0.0234 | 0.2828 + Fold 3 | 0.8923 | 0.0551 | 0.0232 | 0.2810 + Fold 4 | 0.9113 | 0.0532 | 0.0235 | 0.2825 + ------ + ------ + --------- + --------- + -------- + Mean | 0.9054 | 0.0546 | 0.0234 | 0.2829 + Std | 0.0081 | 0.0015 | 0.0002 | 0.0018 + +**Your own splits.** If your data already comes split, for example to compare +with published results, build the evaluation method with +:meth:`~cornac.eval_methods.base_method.BaseMethod.from_splits`. Here it uses +the first of the standard MovieLens 100K splits. Unlike the other methods, it +keeps unknown users and items by default (``exclude_unknowns=False``): + +.. code-block:: python + + from cornac.data import Reader + from cornac.eval_methods import BaseMethod + from cornac.metrics import MAE + from cornac.utils import cache + + reader = Reader() + train_data = reader.read( + cache(url="https://files.grouplens.org/datasets/movielens/ml-100k/u1.base") + ) + test_data = reader.read( + cache(url="https://files.grouplens.org/datasets/movielens/ml-100k/u1.test") + ) + + eval_method = BaseMethod.from_splits( + train_data=train_data, test_data=test_data, rating_threshold=4.0 + ) + + cornac.Experiment( + eval_method=eval_method, + models=[MF(k=10, max_iter=25, learning_rate=0.01, lambda_reg=0.02, seed=123)], + metrics=[MAE(), RMSE(), Recall(k=10)], + ).run() + +.. code-block:: bash + :caption: output + + TEST: + ... + | MAE | RMSE | Recall@10 | Train (s) | Test (s) + -- + ------ + ------ + --------- + --------- + -------- + MF | 0.7439 | 0.9159 | 0.0450 | 0.0294 | 0.2023 + +To read your own files, see :doc:`/user/owndata`. + +**Popularity-aware evaluation.** +:class:`~cornac.eval_methods.propensity_stratified_evaluation.PropensityStratifiedEvaluation` +estimates how likely each item was to be observed from its popularity, splits +the test set into ``n_strata`` groups by that estimate, and reports each group +next to the usual result and an unbiased estimate, so that popular items do not +dominate the result. It follows Jadidinejad et al., *The Simpson's Paradox in +the Offline Evaluation of Recommendation Systems*; see +`propensity_stratified_evaluation_example.py +`_. + +Next-item, next-basket and bundle data have their own evaluation methods, +covered in :doc:`/user/tasks`. + +Rating and ranking metrics +-------------------------- + +Cornac has two kinds of metrics, listed in :doc:`/api_ref/metrics`. + +**Rating metrics** (``MAE``, ``RMSE``, ``MSE``) compare the rating a model +predicts for each test pair with the actual rating. They only make sense for +models that predict ratings, such as MF. BPR learns to rank, not to predict +ratings, which is why its RMSE in `Analyze results`_ is so high even though it +ranks best. + +**Ranking metrics** (``Precision``, ``Recall``, ``NDCG``, ``HitRatio``, +``FMeasure``, ``NCRR``, ``MRR``, ``AUC``, ``MAP``) ask the model to rank +the items for each test user. Test items rated ``rating_threshold`` or higher +are the relevant ones, and items the user already liked in training are left +out. ``k`` sets how many top items count: ``Recall(k=10)`` looks at the top 10, +and without ``k`` the whole ranking is used. + +The ``user_based`` argument of ``Experiment`` changes how rating metrics are +averaged. With ``True`` (the default), Cornac averages the error of each user +first, then averages over users, so every user counts the same. With +``False``, it averages over all test ratings, so active users count more. +Ranking metrics are always averaged over users. + +.. code-block:: python + + cornac.Experiment( + eval_method=rs, + models=[MF(k=10, max_iter=25, learning_rate=0.01, lambda_reg=0.02, seed=123)], + metrics=[MAE(), RMSE()], + user_based=False, + ).run() + +.. code-block:: bash + :caption: output + + TEST: + ... + | MAE | RMSE | Train (s) | Test (s) + -- + ------ + ------ + --------- + -------- + MF | 0.7149 | 0.9087 | 0.0252 | 0.1001 + +Validation sets +--------------- + +When the evaluation method has a validation set (``val_size`` in +``RatioSplit``, or ``val_data`` in ``from_splits``), ``Experiment`` also +scores every model on it and prints a ``VALIDATION`` table before the ``TEST`` +one, as in `Tuning hyper-parameters`_ below. Pass ``show_validation=False`` to +``Experiment`` to skip it. + +Models receive the validation set during training too. Some use it, for +example to stop early (the ``early_stopping`` option of NCF models and +LightGCN) or to keep their best epoch (``model_selection="best"`` in GRU4Rec, +SASRec and TIGER). Choose hyper-parameters on the validation set rather than the +test set; `Tuning hyper-parameters`_ shows how. + +Reading the results +------------------- + +Each table has one row per model and one column per metric, followed by the +training and test times in seconds. Besides printing them, ``run()`` saves the +tables to a ``CornacExp-_