[](https://github.com/fidelity/mab2rec/actions/workflows/ci.yml) [](https://pypi.python.org/pypi/mab2rec/) [](https://pypi.python.org/pypi/mab2rec/) [](http://makeapullrequest.com) [](https://pepy.tech/project/mab2rec)
# Mab2Rec: Multi-Armed Bandits Recommender
Mab2Rec ([AAAI'24](https://ojs.aaai.org/index.php/AAAI/article/view/30341)) is a Python library for building bandit-based recommendation algorithms. It supports **context-free**, **parametric** and **non-parametric** **contextual** bandit models powered by [MABWiser](https://github.com/fidelity/mabwiser) and fairness and recommenders evaluations powered by [Jurity](https://github.com/fidelity/jurity).
The library is designed with rapid experimentation in mind, follows the [PEP-8 standards](https://www.python.org/dev/peps/pep-0008/), and is tested heavily.
Mab2Rec is built on top of several other open-source software developed at the AI Center at Fidelity:
* [MABWiser](https://github.com/fidelity/mabwiser) to create multi-armed bandit recommendation algorithms ([Bridge@AAAI'24](http://osullivan.ucc.ie/CPML2024/papers/06.pdf), [TMLR'22](https://openreview.net/pdf?id=sX9d3gfwtE), [IJAIT'21](https://www.worldscientific.com/doi/abs/10.1142/S0218213021500214), [ICTAI'19](https://ieeexplore.ieee.org/document/8995418)).
* [TextWiser](https://github.com/fidelity/textwiser) to create item representations via text featurization ([AAAI'21](https://ojs.aaai.org/index.php/AAAI/article/view/17814)).
* [Selective](https://github.com/fidelity/selective) to create user representations via feature selection ([CPAIOR'21](https://link.springer.com/chapter/10.1007/978-3-030-78230-6_27), [DSO@IJCAI'21](https://arxiv.org/abs/2112.03105)).
* [Seq2Pat](https://github.com/fidelity/seq2pat) to create user representations via sequential pattern mining ([AI Magazine'23](https://onlinelibrary.wiley.com/doi/epdf/10.1002/aaai.12081), [AAAI'22](https://ojs.aaai.org/index.php/AAAI/article/view/21542), [Bridge@AAAI'23](http://osullivan.ucc.ie/CPML2023/submissions/09.pdf), [Frontiers'22](https://www.frontiersin.org/articles/10.3389/frai.2022.868085/full), [KDF@AAAI'22](https://arxiv.org/abs/2201.09178), [CMU Blog Post](https://www.cmu.edu/tepper/news/stories/2023/may/fidelity-ai.html))
* [Jurity](https://github.com/fidelity/jurity) to evaluate recommendations including fairness metrics ([LION'23](https://link.springer.com/chapter/10.1007/978-3-031-44505-7_29), [CIKM'22](https://ceur-ws.org/Vol-3318/short6.pdf), [ICMLA'21](https://ieeexplore.ieee.org/abstract/document/9680169)).
An introduction to **content- and context-aware** recommender systems and an overview of the building blocks of the library is presented at [AAAI 2024](https://underline.io/lecture/91479-building-higher-order-abstractions-from-the-components-of-recommender-systems) and [All Things Open 2021](https://www.youtube.com/watch?v=54d_YUalvOA). There is a corresponding [blogpost](https://2022.allthingsopen.org/introducing-mab2rec-a-multi-armed-bandit-recommender-library/) to serve as a starting point for practioners to build and deploy bandit-based recommenders using Mab2Rec.
Documentation is available at [fidelity.github.io/mab2rec](https://fidelity.github.io/mab2rec).
## Usage Patterns
Mab2Rec supports prototyping with a **single** bandit algorithm or benchmarking with **multiple** bandit algorithms.
If you are new user, the best place to start is to experiment with multiple bandits using the [tutorial notebooks](notebooks).
## Quick Start
### Single Recommender
```python
# Example of how to train an singler recommender to generate top-4 recommendations
# Import
from mab2rec import BanditRecommender, LearningPolicy
from mab2rec.pipeline import train, score
# LinGreedy recommender to select top-4 items with 10% random exploration
rec = BanditRecommender(LearningPolicy.LinGreedy(epsilon=0.1), top_k=4)
# Train on (user, item, response) interactions in train data using user features
train(rec, data='data/data_train.csv',
user_features='data/features_user.csv')
# Score recommendations for users in test data. The output df holds
# user_id, item_id, score columns for every test user for top-k items
df = score(rec, data='data/data_test.csv',
user_features='data/features_user.csv')
```
### Multiple Recommenders
```python
# Example of how to benchmark multiple recommenders to generate top-4 recommendations
from mab2rec import BanditRecommender, LearningPolicy
from mab2rec.pipeline import benchmark
from jurity.recommenders import BinaryRecoMetrics, RankingRecoMetrics
# Recommenders (many more available)
recommenders = {"Random": BanditRecommender(LearningPolicy.Random()),
"Popularity": BanditRecommender(LearningPolicy.Popularity()),
"LinGreedy": BanditRecommender(LearningPolicy.LinGreedy(epsilon=0.1))}
# Column names for the response, user, and item id columns
metric_params = {'click_column': 'score', 'user_id_column': 'user_id', 'item_id_column':'item_id'}
# Performance metrics for benchmarking (many more available)
metrics = []
for top_k in [3, 5, 10]:
metrics.append(BinaryRecoMetrics.CTR(**metric_params, k=top_k))
metrics.append(RankingRecoMetrics.NDCG(**metric_params, k=top_k))
# Benchmarking with a collection of recommenders and metrics
# This returns two dictionaries;
# reco_to_results: recommendations for each algorithm on cross-validation data
# reco_to_metrics: evaluation metrics for each algorithm
reco_to_results, reco_to_metrics = benchmark(recommenders,
metrics=metrics,
train_data="data/data_train.csv",
cv=5,
user_features="data/features_user.csv")
```
## Usage Examples
We provide extensive tutorials in the [notebooks](notebooks) folder with guidelines on building recommenders, performing model selection, and evaluating performance.
1. [Data Overview:](https://github.com/fidelity/mab2rec/tree/master/notebooks/1_data_overview.ipynb) Overview of data required to train recommender.
2. [Feature Engineering:](https://github.com/fidelity/mab2rec/tree/master/notebooks/2_feature_engineering.ipynb) Creating user and item features from structured, unstructured, and sequential data.
3. [Model Selection:](https://github.com/fidelity/mab2rec/tree/master/notebooks/3_model_selection.ipynb) Model selection by benchmarking recommenders using cross-validation.
4. [Evaluation:](https://github.com/fidelity/mab2rec/tree/master/notebooks/4_evaluation.ipynb) Benchmarking of selected recommenders and baselines on test data with detailed evaluation.
5. [Advanced:](https://github.com/fidelity/mab2rec/tree/master/notebooks/5_advanced.ipynb) Demonstration of advanced functionality such as persistency, eligibility, item availability, and memory efficiency.
## Installation
Mab2Rec requires **Python 3.8+** and can be installed from PyPI using ``pip install mab2rec`` or by building from source as shown in [installation instructions](https://fidelity.github.io/mab2rec/installation.html).
## Support
Please submit bug reports and feature requests as [Issues](https://github.com/fidelity/mab2rec/issues).
## License
Mab2Rec is licensed under the [Apache License 2.0](LICENSE).
<br>
Raw data
{
"_id": null,
"home_page": null,
"name": "mab2rec",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": "FMR LLC",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/80/14/a84d631d73e40e40eb17023cba1589144f3210b67a7c4023f40ccab33676/mab2rec-1.3.1.tar.gz",
"platform": null,
"description": "[](https://github.com/fidelity/mab2rec/actions/workflows/ci.yml) [](https://pypi.python.org/pypi/mab2rec/) [](https://pypi.python.org/pypi/mab2rec/) [](http://makeapullrequest.com) [](https://pepy.tech/project/mab2rec)\n\n# Mab2Rec: Multi-Armed Bandits Recommender \n\nMab2Rec ([AAAI'24](https://ojs.aaai.org/index.php/AAAI/article/view/30341)) is a Python library for building bandit-based recommendation algorithms. It supports **context-free**, **parametric** and **non-parametric** **contextual** bandit models powered by [MABWiser](https://github.com/fidelity/mabwiser) and fairness and recommenders evaluations powered by [Jurity](https://github.com/fidelity/jurity).\nThe library is designed with rapid experimentation in mind, follows the [PEP-8 standards](https://www.python.org/dev/peps/pep-0008/), and is tested heavily.\n\nMab2Rec is built on top of several other open-source software developed at the AI Center at Fidelity:\n\n* [MABWiser](https://github.com/fidelity/mabwiser) to create multi-armed bandit recommendation algorithms ([Bridge@AAAI'24](http://osullivan.ucc.ie/CPML2024/papers/06.pdf), [TMLR'22](https://openreview.net/pdf?id=sX9d3gfwtE), [IJAIT'21](https://www.worldscientific.com/doi/abs/10.1142/S0218213021500214), [ICTAI'19](https://ieeexplore.ieee.org/document/8995418)).\n* [TextWiser](https://github.com/fidelity/textwiser) to create item representations via text featurization ([AAAI'21](https://ojs.aaai.org/index.php/AAAI/article/view/17814)).\n* [Selective](https://github.com/fidelity/selective) to create user representations via feature selection ([CPAIOR'21](https://link.springer.com/chapter/10.1007/978-3-030-78230-6_27), [DSO@IJCAI'21](https://arxiv.org/abs/2112.03105)).\n* [Seq2Pat](https://github.com/fidelity/seq2pat) to create user representations via sequential pattern mining ([AI Magazine'23](https://onlinelibrary.wiley.com/doi/epdf/10.1002/aaai.12081), [AAAI'22](https://ojs.aaai.org/index.php/AAAI/article/view/21542), [Bridge@AAAI'23](http://osullivan.ucc.ie/CPML2023/submissions/09.pdf), [Frontiers'22](https://www.frontiersin.org/articles/10.3389/frai.2022.868085/full), [KDF@AAAI'22](https://arxiv.org/abs/2201.09178), [CMU Blog Post](https://www.cmu.edu/tepper/news/stories/2023/may/fidelity-ai.html))\n* [Jurity](https://github.com/fidelity/jurity) to evaluate recommendations including fairness metrics ([LION'23](https://link.springer.com/chapter/10.1007/978-3-031-44505-7_29), [CIKM'22](https://ceur-ws.org/Vol-3318/short6.pdf), [ICMLA'21](https://ieeexplore.ieee.org/abstract/document/9680169)).\n\nAn introduction to **content- and context-aware** recommender systems and an overview of the building blocks of the library is presented at [AAAI 2024](https://underline.io/lecture/91479-building-higher-order-abstractions-from-the-components-of-recommender-systems) and [All Things Open 2021](https://www.youtube.com/watch?v=54d_YUalvOA). There is a corresponding [blogpost](https://2022.allthingsopen.org/introducing-mab2rec-a-multi-armed-bandit-recommender-library/) to serve as a starting point for practioners to build and deploy bandit-based recommenders using Mab2Rec.\n\nDocumentation is available at [fidelity.github.io/mab2rec](https://fidelity.github.io/mab2rec).\n\n## Usage Patterns\n\nMab2Rec supports prototyping with a **single** bandit algorithm or benchmarking with **multiple** bandit algorithms. \nIf you are new user, the best place to start is to experiment with multiple bandits using the [tutorial notebooks](notebooks).\n\n## Quick Start\n\n### Single Recommender\n\n```python\n# Example of how to train an singler recommender to generate top-4 recommendations\n\n# Import \nfrom mab2rec import BanditRecommender, LearningPolicy\nfrom mab2rec.pipeline import train, score\n\n# LinGreedy recommender to select top-4 items with 10% random exploration \nrec = BanditRecommender(LearningPolicy.LinGreedy(epsilon=0.1), top_k=4)\n\n# Train on (user, item, response) interactions in train data using user features \ntrain(rec, data='data/data_train.csv', \n user_features='data/features_user.csv')\n\n# Score recommendations for users in test data. The output df holds \n# user_id, item_id, score columns for every test user for top-k items \ndf = score(rec, data='data/data_test.csv', \n user_features='data/features_user.csv')\n```\n\n### Multiple Recommenders\n\n```python\n# Example of how to benchmark multiple recommenders to generate top-4 recommendations\n\nfrom mab2rec import BanditRecommender, LearningPolicy\nfrom mab2rec.pipeline import benchmark\nfrom jurity.recommenders import BinaryRecoMetrics, RankingRecoMetrics\n\n# Recommenders (many more available)\nrecommenders = {\"Random\": BanditRecommender(LearningPolicy.Random()),\n \"Popularity\": BanditRecommender(LearningPolicy.Popularity()),\n \"LinGreedy\": BanditRecommender(LearningPolicy.LinGreedy(epsilon=0.1))}\n\n# Column names for the response, user, and item id columns\nmetric_params = {'click_column': 'score', 'user_id_column': 'user_id', 'item_id_column':'item_id'}\n\n# Performance metrics for benchmarking (many more available)\nmetrics = []\nfor top_k in [3, 5, 10]:\n metrics.append(BinaryRecoMetrics.CTR(**metric_params, k=top_k))\n metrics.append(RankingRecoMetrics.NDCG(**metric_params, k=top_k))\n\n# Benchmarking with a collection of recommenders and metrics \n# This returns two dictionaries; \n# reco_to_results: recommendations for each algorithm on cross-validation data\n# reco_to_metrics: evaluation metrics for each algorithm\nreco_to_results, reco_to_metrics = benchmark(recommenders,\n metrics=metrics,\n train_data=\"data/data_train.csv\",\n cv=5,\n user_features=\"data/features_user.csv\")\n```\n\n## Usage Examples\n\nWe provide extensive tutorials in the [notebooks](notebooks) folder with guidelines on building recommenders, performing model selection, and evaluating performance.\n\n1. [Data Overview:](https://github.com/fidelity/mab2rec/tree/master/notebooks/1_data_overview.ipynb) Overview of data required to train recommender.\n2. [Feature Engineering:](https://github.com/fidelity/mab2rec/tree/master/notebooks/2_feature_engineering.ipynb) Creating user and item features from structured, unstructured, and sequential data.\n3. [Model Selection:](https://github.com/fidelity/mab2rec/tree/master/notebooks/3_model_selection.ipynb) Model selection by benchmarking recommenders using cross-validation.\n4. [Evaluation:](https://github.com/fidelity/mab2rec/tree/master/notebooks/4_evaluation.ipynb) Benchmarking of selected recommenders and baselines on test data with detailed evaluation.\n5. [Advanced:](https://github.com/fidelity/mab2rec/tree/master/notebooks/5_advanced.ipynb) Demonstration of advanced functionality such as persistency, eligibility, item availability, and memory efficiency.\n\n## Installation\n\nMab2Rec requires **Python 3.8+** and can be installed from PyPI using ``pip install mab2rec`` or by building from source as shown in [installation instructions](https://fidelity.github.io/mab2rec/installation.html).\n\n## Support\n\nPlease submit bug reports and feature requests as [Issues](https://github.com/fidelity/mab2rec/issues).\n\n## License\n\nMab2Rec is licensed under the [Apache License 2.0](LICENSE).\n\n<br>\n",
"bugtrack_url": null,
"license": null,
"summary": "Mab2Rec: Multi-Armed Bandits Recommender",
"version": "1.3.1",
"project_urls": {
"Source": "https://github.com/fidelity/mab2rec"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "76491fc02014e2bca7bac777e227d0b1adf475e300176e269ac52f46d03f2c52",
"md5": "1f43b1d7e0b05c6ee0e138e32e51a685",
"sha256": "b46cb504f863e7b13eb036cb2b7be35d0eb228e7690eb1c47d6cab1c0e77cd96"
},
"downloads": -1,
"filename": "mab2rec-1.3.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1f43b1d7e0b05c6ee0e138e32e51a685",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 25917,
"upload_time": "2024-09-04T01:03:40",
"upload_time_iso_8601": "2024-09-04T01:03:40.268087Z",
"url": "https://files.pythonhosted.org/packages/76/49/1fc02014e2bca7bac777e227d0b1adf475e300176e269ac52f46d03f2c52/mab2rec-1.3.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8014a84d631d73e40e40eb17023cba1589144f3210b67a7c4023f40ccab33676",
"md5": "3253508aa49232448b6771eeff927015",
"sha256": "cff12f5834093d55efa225087ee7bfeaa726187dbd6c2dc0aef0bf064da03d9a"
},
"downloads": -1,
"filename": "mab2rec-1.3.1.tar.gz",
"has_sig": false,
"md5_digest": "3253508aa49232448b6771eeff927015",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35689,
"upload_time": "2024-09-04T01:03:41",
"upload_time_iso_8601": "2024-09-04T01:03:41.708938Z",
"url": "https://files.pythonhosted.org/packages/80/14/a84d631d73e40e40eb17023cba1589144f3210b67a7c4023f40ccab33676/mab2rec-1.3.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-04 01:03:41",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fidelity",
"github_project": "mab2rec",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "numpy",
"specs": [
[
">=",
"1.20.2"
]
]
},
{
"name": "pandas",
"specs": [
[
">=",
"1.1.0"
]
]
},
{
"name": "scikit-learn",
"specs": [
[
">=",
"0.24.0"
]
]
},
{
"name": "scipy",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "seaborn",
"specs": [
[
">=",
"0.1.0"
]
]
},
{
"name": "mabwiser",
"specs": [
[
">=",
"2.7.4"
]
]
},
{
"name": "jurity",
"specs": [
[
">=",
"1.3.2"
]
]
}
],
"lcname": "mab2rec"
}
JSON
