<div align="center">
<h1>Corec</h1>
</div>
<p align="center">
<!-- Python -->
<a href="https://www.python.org"><img src="https://img.shields.io/badge/3.8-3776AB?style=flat&logo=python&logoColor=white"></a>
<!-- Version -->
<a href="https://pypi.org/project/corec/"><img src="https://img.shields.io/pypi/v/corec?color=orange"></a>
<!-- Elliot -->
<a href="https://elliot.readthedocs.io/en/latest/index.html"><img src="https://img.shields.io/badge/integrated-Elliot-blue.svg"></a>
<!-- Ranx -->
<a href="https://amenra.github.io/ranx/"><img src="https://badgen.net/badge/icon/Ranx?icon=bitcoin-lightning&label&color=ef5553"></a>
<br>
<!-- Pydantic -->
<a href="https://docs.pydantic.dev/latest/contributing/#badges"><img src="https://camo.githubusercontent.com/1ec3b5f774c66556456b4b855a73c1706f5454fa0ac3d2e4bcdabda9153b6b45/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f75726c3d68747470733a2f2f7261772e67697468756275736572636f6e74656e742e636f6d2f707964616e7469632f707964616e7469632f6d61696e2f646f63732f62616467652f76322e6a736f6e" alt="Pydantic v2" data-canonical-src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json" style="max-width: 100%;"></a>
<!-- Ruff -->
<a href="https://docs.astral.sh/ruff/"><img alt="Ruff" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json"></a>
<!-- License -->
<a href="https://lbesson.mit-license.org/"><img src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
</p>
**Corec** is a flexible and configurable framework designed for context-aware recommenders. It includes several object-oriented modules aimed at simplifying recommendation generation and metric evaluation.
The **recommendation module** supports **[Elliot](https://elliot.readthedocs.io/en/latest/index.html)-based models** for non-contextual recommendations and several library-specific **contextual heuristic models** for context-aware predictions. The **evaluation module** allows you to compute various metrics from prediction files, which can either be generated by the recommendation module or externally. It includes support for metrics from the **[Ranx](https://amenra.github.io/ranx/)** library, along with some custom Corec metrics.
It is important to note that **Corec** is part of a final degree project, and its goal is to provide a solid framework structure that allows users to easily extend the library with their own recommenders and metrics, making it a flexible foundation for further development.
## Corec Modules List
Below is a complete list of the available modules in Corec. Please check the associated documentation to learn more about them.
|**‣ Recommenders** |**‣ Evaluation** |**‣ Postfiltering** |
|:--------------------------|:----------------------------|:----------------------------|
| ElliotRec | QrelsGenerator | Postfilter |
| ContextPopRec | RunGenerator | |
| ContextRandomRec | MetricGenerator | |
| ContextSatisfactionRec | Evaluator | |
## Installation
To install Corec, simply use `pip`:
```bash
pip install corec
```
If you want to use the evaluation module:
```bash
pip install corec[evaluator]
```
## Usage
### Recommendation Module Examples
Here’s an example of how to use the **Elliot Recommendation Module** to generate predictions based on the library Elliot:
```python
from corec.recommenders import ElliotRec
# Instantiate the Elliot recommender
elliot_rec = ElliotRec(
preds_path_template="preds/{model}/{model}.tsv.gzip",
train_path="dataset/train.inter",
test_path="dataset/test.inter",
preds_score_col_name="score",
elliot_work_dir="elliot_work_dir",
)
# Setup the model parameters according to the official docs from Elliot
models_config = {
"ItemKNN": {
"implementation": "classic",
"neighbors": 40,
"similarity": "cosine",
},
"FM": {
"epochs": 10,
"batch_size": 512,
"factors": 10,
"lr": 0.001,
"reg": 0.1,
}
}
# You are ready to run the experiment
elliot_rec.run_elliot_experiment(
models_config,
K=50,
clean_elliot_work_dir=True,
clean_temp_dataset_files=True,
)
```
And here is shown an example of usage of **Heuristic Recommendation Module**:
```python
from corec.recommenders import ContextRandomRec
# Instantiate the context-aware recommender
cp_rec = ContextPopRec(
train_path="dataset/train.inter",
test_path="dataset/test.inter",
valid_path="dataset/valid.inter"
logs_path="ContextPop.log",
chunk_size=100,
)
cp_rec.compute_predictions(
output_path="preds/ContextPop.tsv.gzip",
K=5,
)
```
### Evaluation Module Example
After generating predictions, you can evaluate them with the **Evaluation Module**. Here's an example of how to use the module to compute metrics:
```python
```
### Dataset Structure
Corec assumes the following structure for the input datasets:
- **Training Set**: A file containing training data for recommender model training.
- **Test Set**: A file containing test data for generating recommendations.
- **Optional Validation Set**: An optional file for validation during model training or evaluation.
Each dataset should have the following columns:
- **User ID**: A column representing the unique identifier for each user (either `str` or `int`).
- **Item ID**: A column representing the unique identifier for each item (either `str` or `int`).
- **Rating ID**: A column representing the rating given by the user (usually a `float`).
- **Context Columns**: Additional columns representing the context for each recommendation (all `int`).
Example:
| User ID | Item ID | Rating ID | Context 1 | Context 2 | ... |
|---------|---------|-----------|-----------|-----------|-----|
| 1 | 101 | 4.5 | 1 | 0 | ... |
| 2 | 102 | 3.8 | 0 | 1 | ... |
Raw data
{
"_id": null,
"home_page": null,
"name": "corec",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.9,>=3.8",
"maintainer_email": null,
"keywords": "recommender, context-aware, evaluation, framework",
"author": null,
"author_email": "Jaime Gimillo <jaimegimillo@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0a/9c/d59bd038f2050f2fae66bd29405517e454cc404d6a1aa66687c4bd10cac0/corec-1.0.6.tar.gz",
"platform": null,
"description": "<div align=\"center\">\n <h1>Corec</h1>\n</div>\n\n<p align=\"center\">\n <!-- Python -->\n <a href=\"https://www.python.org\"><img src=\"https://img.shields.io/badge/3.8-3776AB?style=flat&logo=python&logoColor=white\"></a>\n <!-- Version -->\n <a href=\"https://pypi.org/project/corec/\"><img src=\"https://img.shields.io/pypi/v/corec?color=orange\"></a>\n <!-- Elliot -->\n <a href=\"https://elliot.readthedocs.io/en/latest/index.html\"><img src=\"https://img.shields.io/badge/integrated-Elliot-blue.svg\"></a>\n <!-- Ranx -->\n <a href=\"https://amenra.github.io/ranx/\"><img src=\"https://badgen.net/badge/icon/Ranx?icon=bitcoin-lightning&label&color=ef5553\"></a>\n <br>\n <!-- Pydantic -->\n <a href=\"https://docs.pydantic.dev/latest/contributing/#badges\"><img src=\"https://camo.githubusercontent.com/1ec3b5f774c66556456b4b855a73c1706f5454fa0ac3d2e4bcdabda9153b6b45/68747470733a2f2f696d672e736869656c64732e696f2f656e64706f696e743f75726c3d68747470733a2f2f7261772e67697468756275736572636f6e74656e742e636f6d2f707964616e7469632f707964616e7469632f6d61696e2f646f63732f62616467652f76322e6a736f6e\" alt=\"Pydantic v2\" data-canonical-src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/pydantic/pydantic/main/docs/badge/v2.json\" style=\"max-width: 100%;\"></a>\n <!-- Ruff -->\n <a href=\"https://docs.astral.sh/ruff/\"><img alt=\"Ruff\" src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\"></a>\n <!-- License -->\n <a href=\"https://lbesson.mit-license.org/\"><img src=\"https://img.shields.io/badge/license-MIT-blue.svg\"></a>\n</p>\n\n**Corec** is a flexible and configurable framework designed for context-aware recommenders. It includes several object-oriented modules aimed at simplifying recommendation generation and metric evaluation.\n\nThe **recommendation module** supports **[Elliot](https://elliot.readthedocs.io/en/latest/index.html)-based models** for non-contextual recommendations and several library-specific **contextual heuristic models** for context-aware predictions. The **evaluation module** allows you to compute various metrics from prediction files, which can either be generated by the recommendation module or externally. It includes support for metrics from the **[Ranx](https://amenra.github.io/ranx/)** library, along with some custom Corec metrics.\n\nIt is important to note that **Corec** is part of a final degree project, and its goal is to provide a solid framework structure that allows users to easily extend the library with their own recommenders and metrics, making it a flexible foundation for further development.\n\n## Corec Modules List\n\nBelow is a complete list of the available modules in Corec. Please check the associated documentation to learn more about them.\n\n|**\u2023 Recommenders** |**\u2023 Evaluation** |**\u2023 Postfiltering** |\n|:--------------------------|:----------------------------|:----------------------------|\n| ElliotRec | QrelsGenerator | Postfilter |\n| ContextPopRec | RunGenerator | |\n| ContextRandomRec | MetricGenerator | |\n| ContextSatisfactionRec | Evaluator | |\n\n## Installation\n\nTo install Corec, simply use `pip`:\n\n```bash\npip install corec\n```\n\nIf you want to use the evaluation module:\n\n```bash\npip install corec[evaluator]\n```\n\n## Usage\n\n### Recommendation Module Examples\n\nHere\u2019s an example of how to use the **Elliot Recommendation Module** to generate predictions based on the library Elliot:\n\n```python\nfrom corec.recommenders import ElliotRec\n\n# Instantiate the Elliot recommender\nelliot_rec = ElliotRec(\n preds_path_template=\"preds/{model}/{model}.tsv.gzip\",\n train_path=\"dataset/train.inter\",\n test_path=\"dataset/test.inter\",\n preds_score_col_name=\"score\",\n elliot_work_dir=\"elliot_work_dir\",\n)\n\n# Setup the model parameters according to the official docs from Elliot\nmodels_config = {\n \"ItemKNN\": {\n \"implementation\": \"classic\",\n \"neighbors\": 40,\n \"similarity\": \"cosine\",\n },\n \"FM\": {\n \"epochs\": 10,\n \"batch_size\": 512,\n \"factors\": 10,\n \"lr\": 0.001,\n \"reg\": 0.1,\n }\n}\n\n# You are ready to run the experiment\nelliot_rec.run_elliot_experiment(\n models_config,\n K=50,\n clean_elliot_work_dir=True,\n clean_temp_dataset_files=True,\n)\n```\n\nAnd here is shown an example of usage of **Heuristic Recommendation Module**:\n\n```python\nfrom corec.recommenders import ContextRandomRec\n\n# Instantiate the context-aware recommender\ncp_rec = ContextPopRec(\n train_path=\"dataset/train.inter\",\n test_path=\"dataset/test.inter\",\n valid_path=\"dataset/valid.inter\"\n logs_path=\"ContextPop.log\",\n chunk_size=100,\n)\n\ncp_rec.compute_predictions(\n output_path=\"preds/ContextPop.tsv.gzip\",\n K=5,\n)\n```\n\n### Evaluation Module Example\n\nAfter generating predictions, you can evaluate them with the **Evaluation Module**. Here's an example of how to use the module to compute metrics:\n\n```python\n\n```\n\n### Dataset Structure\n\nCorec assumes the following structure for the input datasets:\n\n- **Training Set**: A file containing training data for recommender model training.\n- **Test Set**: A file containing test data for generating recommendations.\n- **Optional Validation Set**: An optional file for validation during model training or evaluation.\n\nEach dataset should have the following columns:\n- **User ID**: A column representing the unique identifier for each user (either `str` or `int`).\n- **Item ID**: A column representing the unique identifier for each item (either `str` or `int`).\n- **Rating ID**: A column representing the rating given by the user (usually a `float`).\n- **Context Columns**: Additional columns representing the context for each recommendation (all `int`).\n\nExample:\n\n| User ID | Item ID | Rating ID | Context 1 | Context 2 | ... |\n|---------|---------|-----------|-----------|-----------|-----|\n| 1 | 101 | 4.5 | 1 | 0 | ... |\n| 2 | 102 | 3.8 | 0 | 1 | ... |\n",
"bugtrack_url": null,
"license": "LICENSE",
"summary": "A Context-Aware Recommendation Framework for Python",
"version": "1.0.6",
"project_urls": null,
"split_keywords": [
"recommender",
" context-aware",
" evaluation",
" framework"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b722f466d86c8540a332d4564e554f0ae1550aea43fe87d75269c682afdc5596",
"md5": "3c5930e40558f7c30e748cc4e7c8ca7e",
"sha256": "ab11f762f7344b536e721173e44f27adb245ddad3127f66c0cd98d537ab37718"
},
"downloads": -1,
"filename": "corec-1.0.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "3c5930e40558f7c30e748cc4e7c8ca7e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.9,>=3.8",
"size": 30637,
"upload_time": "2025-02-01T20:17:54",
"upload_time_iso_8601": "2025-02-01T20:17:54.717901Z",
"url": "https://files.pythonhosted.org/packages/b7/22/f466d86c8540a332d4564e554f0ae1550aea43fe87d75269c682afdc5596/corec-1.0.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0a9cd59bd038f2050f2fae66bd29405517e454cc404d6a1aa66687c4bd10cac0",
"md5": "2702c8e3b978fd81d4e8f7b4bb02eb42",
"sha256": "777cd462e80cdad625f280a2ec158ec90dabeccd8d2eb6cc4c12496ed7de3c76"
},
"downloads": -1,
"filename": "corec-1.0.6.tar.gz",
"has_sig": false,
"md5_digest": "2702c8e3b978fd81d4e8f7b4bb02eb42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.9,>=3.8",
"size": 23804,
"upload_time": "2025-02-01T20:17:56",
"upload_time_iso_8601": "2025-02-01T20:17:56.589697Z",
"url": "https://files.pythonhosted.org/packages/0a/9c/d59bd038f2050f2fae66bd29405517e454cc404d6a1aa66687c4bd10cac0/corec-1.0.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-01 20:17:56",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "corec"
}
JSON