File: README.md
What's New (April, 2025)
We reached 20,000 stars!!
We are happy to announce that we have reached 20,000 stars on GitHub! Thank you for your support and contributions to the Recommenders project. We are excited to continue building and improving this project with your help.
Check out the release Recommenders 1.2.1!
We fixed a lot of bugs due to dependencies, improved security, reviewed the notebooks and the libraries.
Introduction
Recommenders objective is to assist researchers, developers and enthusiasts in prototyping, experimenting with and bringing to production a range of classic and state-of-the-art recommendation systems.
Recommenders is a project under the Linux Foundation of AI and Data.
This repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks. The examples detail our learnings on five key tasks:
- Prepare Data: Preparing and loading data for each recommendation algorithm.
- Model: Building models using various classical and deep learning recommendation algorithms such as Alternating Least Squares (ALS) or eXtreme Deep Factorization Machines (xDeepFM).
- Evaluate: Evaluating algorithms with offline metrics.
- Model Select and Optimize: Tuning and optimizing hyperparameters for recommendation models.
- Operationalize: Operationalizing models in a production environment on Azure.
Several utilities are provided in recommenders to support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications. See the Recommenders documentation.
For a more detailed overview of the repository, please see the documents on the wiki page.
For some of the practical scenarios where recommendation systems have been applied, see scenarios.
Getting Started
We recommend uv for environment management (10-100x faster than conda/pip), and VS Code for development. To install the recommenders package and run an example notebook on Linux/WSL:
# 1. Install gcc if it is not installed already. On Ubuntu, this could done by using the command
# sudo apt install gcc
# 2. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh
# 3. Create and activate a new virtual environment
uv venv ~/.venvs/recommenders --python 3.11
source ~/.venvs/recommenders/bin/activate
# 4. Install the core recommenders package. It can run all the CPU notebooks.
uv pip install recommenders
# 5. Create a Jupyter kernel
uv pip install ipykernel
python -m ipykernel install --user --name recommenders --display-name "Python (recommenders)"
# 6. Clone this repo within VSCode or using command line:
git clone https://github.com/recommenders-team/recommenders.git
# 7. Within VSCode:
# a. Open a notebook, e.g., examples/00_quick_start/sar_movielens.ipynb;
# b. Select Jupyter kernel "Python (recommenders)";
# c. Run the notebook.For more information about setup on other platforms (e.g., Windows and macOS) and different configurations (e.g., GPU, Spark and experimental features), see the Setup Guide.
In addition to the core package, several extras are also provided, including:
[gpu]: Needed for running GPU models.[spark]: Needed for running Spark models.[dev]: Needed for development for the repo.[all]:[gpu]|[spark]|[dev][experimental]: Models that are not thoroughly tested and/or may require additional steps in installation.
Algorithms
The table below lists the recommendation algorithms currently available in the repository. Notebooks are linked under the Example column as Quick start, showcasing an easy to run example of the algorithm, or as Deep dive, explaining in detail the math and implementation of the algorithm.
| Algorithm | Type | Description | Example |
|---|---|---|---|
| Alternating Least Squares (ALS) | Collaborative Filtering | Matrix factorization algorithm for explicit or implicit feedback in large datasets, optimized for scalability and distributed computing capability. It works in the PySpark environment. | Quick start / Deep dive |
| Attentive Asynchronous Singular Value Decomposition (A2SVD)* | Collaborative Filtering | Sequential-based algorithm that aims to capture both long and short-term user preferences using attention mechanism. It works in the CPU/GPU environment. | Quick start |
| Cornac/Bayesian Personalized Ranking (BPR) | Collaborative Filtering | Matrix factorization algorithm for predicting item ranking with implicit feedback. It works in the CPU environment. | Deep dive |
| Cornac/Bilateral Variational Autoencoder (BiVAE) | Collaborative Filtering | Generative model for dyadic data (e.g., user-item interactions). It works in the CPU/GPU environment. | Deep dive |
| Convolutional Sequence Embedding Recommendation (Caser) | Collaborative Filtering | Algorithm based on convolutions that aim to capture both user’s general preferences and sequential patterns. It works in the CPU/GPU environment. | Quick start |
| Deep Knowledge-Aware Network (DKN)* | Content-Based Filtering | Deep learning algorithm incorporating a knowledge graph and article embeddings for providing news or article recommendations. It works in the CPU/GPU environment. | Quick start / Deep dive |
| Extreme Deep Factorization Machine (xDeepFM)* | Collaborative Filtering | Deep learning based algorithm for implicit and explicit feedback with user/item features. It works in the CPU/GPU environment. | Quick start |
| Embedding Dot Bias | Collaborative Filtering | General purpose algorithm with embeddings and biases for users and items. It works in the CPU/GPU environment. | Quick start |
| LightFM/Factorization Machine | Collaborative Filtering | Factorization Machine algorithm for both implicit and explicit feedbacks. It works in the CPU environment. | Quick start |
| LightGBM/Gradient Boosting Tree* | Content-Based Filtering | Gradient Boosting Tree algorithm for fast training and low memory usage in content-based problems. It works in the CPU/GPU/PySpark environments. | Quick start in CPU / Deep dive in PySpark |
| LightGCN | Collaborative Filtering | Deep learning algorithm which simplifies the design of GCN for predicting implicit feedback. It works in the CPU/GPU environment. | Deep dive |
| GeoIMC* | Collaborative Filtering | Matrix completion algorithm that takes into account user and item features using Riemannian conjugate gradient optimization and follows a geometric approach. It works in the CPU environment. | Quick start |
| GRU | Collaborative Filtering | Sequential-based algorithm that aims to capture both long and short-term user preferences using recurrent neural networks. It works in the CPU/GPU environment. | Quick start |
| Multinomial VAE | Collaborative Filtering | Generative model for predicting user/item interactions. It works in the CPU/GPU environment. | Deep dive |
| Neural Recommendation with Long- and Short-term User Representations (LSTUR)* | Content-Based Filtering | Neural recommendation algorithm for recommending news articles with long- and short-term user interest modeling. It works in the CPU/GPU environment. | Quick start |
| Neural Recommendation with Attentive Multi-View Learning (NAML)* | Content-Based Filtering | Neural recommendation algorithm for recommending news articles with attentive multi-view learning. It works in the CPU/GPU environment. | Quick start |
| Neural Collaborative Filtering (NCF) | Collaborative Filtering | Deep learning algorithm with enhanced performance for user/item implicit feedback. It works in the CPU/GPU environment. | Quick start / Deep dive |
| Neural Recommendation with Personalized Attention (NPA)* | Content-Based Filtering | Neural recommendation algorithm for recommending news articles with personalized attention network. It works in the CPU/GPU environment. | Quick start |
| Neural Recommendation with Multi-Head Self-Attention (NRMS)* | Content-Based Filtering | Neural recommendation algorithm for recommending news articles with multi-head self-attention. It works in the CPU/GPU environment. | Quick start |
| Next Item Recommendation (NextItNet) | Collaborative Filtering | Algorithm based on dilated convolutions and residual network that aims to capture sequential patterns. It considers both user/item interactions and features. It works in the CPU/GPU environment. | Quick start |
| Restricted Boltzmann Machines (RBM) | Collaborative Filtering | Neural network based algorithm for learning the underlying probability distribution for explicit or implicit user/item feedback. It works in the CPU/GPU environment. | Quick start / Deep dive |
| Riemannian Low-rank Matrix Completion (RLRMC)* | Collaborative Filtering | Matrix factorization algorithm using Riemannian conjugate gradients optimization with small memory consumption to predict user/item interactions. It works in the CPU environment. | Quick start |
| Simple Algorithm for Recommendation (SAR)* | Collaborative Filtering | Similarity-based algorithm for implicit user/item feedback. It works in the CPU environment. | Quick start / Deep dive |
| Self-Attentive Sequential Recommendation (SASRec) | Collaborative Filtering | Transformer based algorithm for sequential recommendation. It works in the CPU/GPU environment. | Quick start |
| Short-term and Long-term Preference Integrated Recommender (SLi-Rec)* | Collaborative Filtering | Sequential-based algorithm that aims to capture both long and short-term user preferences using attention mechanism, a time-aware controller and a content-aware controller. It works in the CPU/GPU environment. | Quick start |
| Multi-Interest-Aware Sequential User Modeling (SUM)* | Collaborative Filtering | An enhanced memory network-based sequential user model which aims to capture users' multiple interests. It works in the CPU/GPU environment. | Quick start |
| Sequential Recommendation Via Personalized Transformer (SSEPT) | Collaborative Filtering | Transformer based algorithm for sequential recommendation with User embedding. It works in the CPU/GPU environment. | Quick start |
| Standard VAE | Collaborative Filtering | Generative Model for predicting user/item interactions. It works in the CPU/GPU environment. | Deep dive |
| Surprise/Singular Value Decomposition (SVD) | Collaborative Filtering | Matrix factorization algorithm for predicting explicit rating feedback in small datasets. It works in the CPU/GPU environment. | Deep dive |
| Term Frequency - Inverse Document Frequency (TF-IDF) | Content-Based Filtering | Simple similarity-based algorithm for content-based recommendations with text datasets. It works in the CPU environment. | Quick start |
| Vowpal Wabbit (VW)* | Content-Based Filtering | Fast online learning algorithms, great for scenarios where user features / context are constantly changing. It uses the CPU for online learning. | Deep dive |
| Wide and Deep | Collaborative Filtering | Deep learning algorithm that can memorize feature interactions and generalize user features. It works in the CPU/GPU environment. | Quick start |
| xLearn/Factorization Machine (FM) & Field-Aware FM (FFM) | Collaborative Filtering | Quick and memory efficient algorithm to predict labels with user/item features. It works in the CPU/GPU environment. | Deep dive |
NOTE: * indicates algorithms invented/contributed by Microsoft.
Independent or incubating algorithms and utilities are candidates for the contrib folder. This will house contributions which may not easily fit into the core repository or need time to refactor or mature the code and add necessary tests.
| Algorithm | Type | Description | Example |
|---|---|---|---|
| SARplus * | Collaborative Filtering | Optimized implementation of SAR for Spark | Quick start |
Algorithm Comparison
We provide a benchmark notebook to illustrate how different algorithms could be evaluated and compared. In this notebook, the MovieLens dataset is split into training/test sets at a 75/25 ratio using a stratified split. A recommendation model is trained using each of the collaborative filtering algorithms below. We utilize empirical parameter values reported in literature here. For ranking metrics we use k=10 (top 10 recommended items). We run the comparison on a machine with 24 CPUs, 30Gb of RAM, and 1 GPU GeForce RTX 5090 GPU with 24Gb of memory. Spark ALS is run in local standalone mode. In this table we show the results on Movielens 100k. For BPR, ratings are binarized with a threshold of 3.5 (ratings ≥ 4 treated as positive implicit feedback) for both training and evaluation.
| Algo | MAP | nDCG@k | Precision@k | Recall@k | RMSE | MAE | R2 | Explained Variance |
|---|---|---|---|---|---|---|---|---|
| ALS | 0.010400 | 0.032800 | 0.038100 | 0.013200 | 0.966732 | 0.752552 | 0.267438 | 0.263534 |
| BiVAE | 0.330000 | 0.471700 | 0.411300 | 0.224300 | N/A | N/A | N/A | N/A |
| BPR | 0.229200 | 0.362300 | 0.285500 | 0.251700 | N/A | N/A | N/A | N/A |
| embdotbias | 0.054900 | 0.119000 | 0.107000 | 0.042300 | 0.992760 | 0.776040 | 0.223344 | 0.223393 |
| LightGCN | 0.277200 | 0.419100 | 0.359900 | 0.197100 | N/A | N/A | N/A | N/A |
| NCF | 0.260300 | 0.393100 | 0.346900 | 0.181900 | N/A | N/A | N/A | N/A |
| SAR | 0.258500 | 0.393800 | 0.340600 | 0.185400 | 1.229103 | 1.035996 | -0.487843 | 0.097283 |
Contributing
This project welcomes contributions and suggestions. Before contributing, please see our contribution guidelines.
This project adheres to this Code of Conduct in order to foster a welcoming and inspiring community for all.
References
- FREE COURSE: M. González-Fierro, "Recommendation Systems: A Practical Introduction", LinkedIn Learning, 2024. Available on this link.
- D. Li, J. Lian, L. Zhang, K. Ren, D. Lu, T. Wu, X. Xie, "Recommender Systems: Frontiers and Practices", Springer, Beijing, 2024. Available on this link.
- A. Argyriou, M. González-Fierro, and L. Zhang, "Microsoft Recommenders: Best Practices for Production-Ready Recommendation Systems", WWW 2020: International World Wide Web Conference Taipei, 2020. Available online: https://dl.acm.org/doi/abs/10.1145/3366424.3382692
- S. Graham, J.K. Min, T. Wu, "Microsoft recommenders: tools to accelerate developing recommender systems", RecSys '19: Proceedings of the 13th ACM Conference on Recommender Systems, 2019. Available online: https://dl.acm.org/doi/10.1145/3298689.3346967
- L. Zhang, T. Wu, X. Xie, A. Argyriou, M. González-Fierro and J. Lian, "Building Production-Ready Recommendation System at Scale", ACM SIGKDD Conference on Knowledge Discovery and Data Mining 2019 (KDD 2019), 2019.
File: contrib/azureml_designer_modules/README.md
Integration of Recommenders into AzureML Designer
AzureML Designer lets you visually connect datasets and modules on an interactive canvas to create machine learning models.
One of the features of AzureML Designer is that it is possible for developers to integrate any python library to make it available as a module/component. This folder contains the modules to integrate a Recommenders algorithm in AzureML Designer.
File: contrib/sarplus/python/README.md
SARplus
Simple Algorithm for Recommendation (SAR) is a neighborhood based
algorithm for personalized recommendations based on user transaction
history. SAR recommends items that are most similar to the ones
that the user already has an existing affinity for. Two items are
similar if the users that interacted with one item are also likely
to have interacted with the other. A user has an affinity to an
item if they have interacted with it in the past.
SARplus is an efficient implementation of this algorithm for Spark.
More details can be found at
sarplus@microsoft/recommenders.
File: contrib/sarplus/README.md
SARplus
Pronounced surplus as it's simply better if not best!
Simple Algorithm for Recommendation (SAR) is a neighborhood based
algorithm for personalized recommendations based on user transaction
history. SAR recommends items that are most similar to the ones
that the user already has an existing affinity for. Two items are
similar if the users that interacted with one item are also likely
to have interacted with the other. A user has an affinity to an
item if they have interacted with it in the past.
SARplus is an efficient implementation of this algorithm for Spark.
Features:
- Scalable PySpark based implementation
- Fast C++ based predictions
- Reduced memory consumption: similarity matrix cached in-memory once
per worker, shared across python executors
Benchmarks
| # Users | # Items | # Ratings | Runtime | Environment | Dataset |
|---|---|---|---|---|---|
| 2.5mio | 35k | 100mio | 1.3h | Databricks, 8 workers, Azure Standard DS3 v2 (4 core machines) |
Top-K Recommendation Optimization
There are a couple of key optimizations:
- map item ids (e.g. strings) to a continuous set of indexes to
optimize storage and simplify access - convert similarity matrix to exactly the representation the C++
component needs, thus enabling simple shared, memory mapping of the
cache file and avoid parsing. This requires a customer formatter,
written in Scala - shared read-only memory mapping allows us to re-use the same memory
from multiple python executors on the same worker node - partition the input test users and past seen items by users,
allowing for scale out - perform as much of the work as possible in PySpark (way simpler)
- top-k computation
- reverse the join by summing reverse joining the users past seen
items with any related items - make sure to always just keep top-k items in-memory
- use standard join using binary search between users past seen
items and the related items
- reverse the join by summing reverse joining the users past seen
Usage
Two packages should be installed:
- pysarplus@PyPI
- sarplus@MavenCentralRepository (or sarplus-spark-3-2-plus@MavenCentralRepository if run on Spark 3.2+)
Python
from pysarplus import SARPlus
# spark dataframe with user/item/rating/optional timestamp tuples
train_df = spark.createDataFrame(
[(1, 1, 1), (1, 2, 1), (2, 1, 1), (3, 1, 1), (3, 3, 1)],
["user_id", "item_id", "rating"]
)
# spark dataframe with user/item tuples
test_df = spark.createDataFrame(
[(1, 1, 1), (3, 3, 1)],
["user_id", "item_id", "rating"],
)
# To use C++ based fast prediction, a local cache directory needs to be
# specified.
# * On local machine, `cache_path` can be any valid directories. For example,
#
# ```python
# model = SARPlus(
# spark,
# col_user="user_id",
# col_item="item_id",
# col_rating="rating",
# col_timestamp="timestamp",
# similarity_type="jaccard",
# cache_path="cache",
# )
# ```
#
# * On Databricks, `cache_path` needs to be mounted on DBFS. For example,
#
# ```python
# model = SARPlus(
# spark,
# col_user="user_id",
# col_item="item_id",
# col_rating="rating",
# col_timestamp="timestamp",
# similarity_type="jaccard",
# cache_path="dbfs:/mnt/sarpluscache/cache",
# )
# ```
#
# * On Azure Synapse, `cache_path` needs to be mounted on Spark pool's driver
# node. For example,
#
# ```python
# model = SARPlus(
# spark,
# col_user="user_id",
# col_item="item_id",
# col_rating="rating",
# col_timestamp="timestamp",
# similarity_type="jaccard",
# cache_path=f"synfs:/{job_id}/mnt/sarpluscache/cache",
# )
# ```
#
# where `job_id` can be obtained by
#
# ```python
# from notebookutils import mssparkutils
# job_id = mssparkutils.env.getJobId()
# ```
model = SARPlus(
spark,
col_user="user_id",
col_item="item_id",
col_rating="rating",
col_timestamp="timestamp",
similarity_type="jaccard",
)
model.fit(train_df)
# To use C++ based fast prediction, the `use_cache` parameter of
# `SARPlus.recommend_k_items()` also needs to be set to `True`.
#
# ```
# model.recommend_k_items(test_df, top_k=3, use_cache=True).show()
# ```
model.recommend_k_items(test_df, top_k=3, remove_seen=False).show()Jupyter Notebook
Insert this cell prior to the code above.
import os
SARPLUS_MVN_COORDINATE = "com.microsoft.sarplus:sarplus_2.12:0.6.6"
SUBMIT_ARGS = f"--packages {SARPLUS_MVN_COORDINATE} pyspark-shell"
os.environ["PYSPARK_SUBMIT_ARGS"] = SUBMIT_ARGS
from pyspark.sql import SparkSession
spark = (
SparkSession.builder.appName("sample")
.master("local[*]")
.config("memory", "1G")
.config("spark.sql.shuffle.partitions", "1")
.config("spark.sql.crossJoin.enabled", True)
.config("spark.sql.sources.default", "parquet")
.config("spark.sql.legacy.createHiveTableByDefault", True)
.config("spark.ui.enabled", False)
.getOrCreate()
)PySpark Shell
SARPLUS_MVN_COORDINATE="com.microsoft.sarplus:sarplus_2.12:0.6.6"
# Install pysarplus
pip install pysarplus
# Specify sarplus maven coordinate and configure Spark environment
pyspark --packages "${SARPLUS_MVN_COORDINATE}" \
--conf spark.sql.crossJoin.enabled=true \
--conf spark.sql.sources.default=parquet \
--conf spark.sql.legacy.createHiveTableByDefault=trueDatabricks
Install libraries
- Navigate to your Databricks Workspace
- Create Library
- Under
Library SourceselectMaven - Enter into
Coordinates:com.microsoft.sarplus:sarplus_2.12:0.6.6- or
com.microsoft.sarplus:sarplus-spark-3-2-plus_2.12:0.6.6(if
you're on Spark 3.2+)
- Hit
Create - Attach to your cluster
- Create 2nd library
- Under
Library SourceselectPyPI - Enter
pysarplus==0.6.6 - Hit
Create
This will install C++, Python and Scala code on your cluster. See
Libraries
for details on how to install libraries on Azure Databricks.
Configurations
Navigate to your Databricks Compute
Navigate to your cluster's
Configuration->Advanced options->SparkPut the following configurations into
Spark configtextspark.sql.crossJoin.enabled true spark.sql.sources.default parquet spark.sql.legacy.createHiveTableByDefault true
These will set the crossJoin property to enable calculation of the
similarity matrix, and set default sources to parquet.
It can also be configured by putting the following Python code in a
notebook cell:
spark.conf.set("spark.sql.crossJoin.enabled", "true")
spark.conf.set("spark.sql.sources.default", "parquet")
spark.conf.set("spark.sql.legacy.createHiveTableByDefault", "true")Prepare local file system for cache
To use C++ based fast prediction inpysarplus.SARPlus.recommend_k_items(), a local cache directory needs
to be specified as the cache_path parameter of pysarplus.SARPlus()
to store intermediate files during its calculation, so you'll also
have to mount shared storage.
For example, you can create a storage
account
(e.g. sarplusstorage) and a container (e.g. sarpluscache) in the
storage account, copy the access key of the storage account, and then
run the following code to mount the storage.
dbutils.fs.mount(
source = "wasbs://<container>@<storage-account>.blob.core.windows.net",
mount_point = "/mnt/<container>",
extra_configs = {
"fs.azure.account.key.<storage-account>.blob.core.windows.net":
"<access-key>"
}
)where <storage-account>, <container> and <access-key> should be
replaced with the actual values, such as sarplusstorage,sarpluscache and the access key of the storage account. Then passcache_path="dbfs:/mnt/<container>/cache" to pysarplus.SARPlus(),
where cache is the cache's name.
To disable logging messages:
import logging
logging.getLogger("py4j").setLevel(logging.ERROR)Azure Synapse
Install libraries
Download pysarplus WHL file from
pysarplus@PyPIDownload sarplus JAR file
from sarplus@MavenCentralRepository(or
sarplus-spark-3-2-plus@MavenCentralRepository
if run on Spark 3.2+)Navigate to your Azure Synapse workspace ->
Manage->Workspace packagesUpload pysarplus WHL file and sarplus JAR file as workspace
packagesNavigate to your Azure Synapse workspace ->
Manage->Apache Spark poolsFind the Spark pool to install the packages ->
...->Packages
->Workspace packages->+ Select from workspace packagesand
select pysarplus TAR file and sarplus JAR file uploaded in the
previous stepApply
pysarplus can also be installed via requirements.txt. See Manage
libraries for Apache Spark in Azure Synapse
Analytics
for details on how to manage libraries in Azure Synapse.
Prepare local file system for cache
To use C++ based fast prediction inpysarplus.SARPlus.recommend_k_items(), a local cache directory needs
to be specified as the cache_path parameter of pysarplus.SARPlus()
to store intermediate files during its calculation, so you'll also
have to mount shared storage.
For example, you can run the following code to mount the file system
(container) of the default/primary storage account.
from notebookutils import mssparkutils
mssparkutils.fs.mount(
"abfss://<container>@<storage-account>.dfs.core.windows.net",
"/mnt/<container>",
{ "linkedService": "<storage-linked-service>"}
)
job_id = mssparkutils.env.getJobId()Then pass cache_path=f"synfs:/{job_id}/mnt/<container>/cache" topysarplus.SARPlus(), where cache is the cache's name. NOTE:job_id should be prepended to the local path.
See How to use file mount/unmount API in Synapse
for more details.
Development
See DEVELOPMENT.md for implementation details and
development information.
File: contrib/README.md
Contrib
Independent or incubating algorithms and utilities are candidates for the contrib folder. This will house contributions which may not easily fit into the core repository or need time to refactor or mature the code and add necessary tests.
| Name | Description |
|---|---|
| AzureML Designer Modeules | Implementation of Recommenders algorithm on AzureML Designer |
| SARplus | Optimized implementation of SAR for Spark |
File: docs/datasets.rst
.. _dataset:
Dataset module
##############
Recommendation datasets and related utilities
Recommendation datasets
Amazon Reviews
Amazon Reviews dataset <https://snap.stanford.edu/data/web-Amazon.html>_ consists of reviews from Amazon.
The data span a period of 18 years, including ~35 million reviews up to March 2013. Reviews include product and user
information, ratings, and a plaintext review.
:Citation:
J. McAuley and J. Leskovec, "Hidden factors and hidden topics: understanding rating dimensions with review text",
RecSys, 2013... automodule:: recommenders.datasets.amazon_reviews
:members:
CORD-19
COVID-19 Open Research Dataset (CORD-19) <https://azure.microsoft.com/en-us/services/open-datasets/catalog/covid-19-open-research/>_ is a full-text
and metadata dataset of COVID-19 and coronavirus-related scholarly articles optimized
for machine readability and made available for use by the global research community.
In response to the COVID-19 pandemic, the Allen Institute for AI has partnered with leading research groups
to prepare and distribute the COVID-19 Open Research Dataset (CORD-19), a free resource of
over 47,000 scholarly articles, including over 36,000 with full text, about COVID-19 and the
coronavirus family of viruses for use by the global research community.
This dataset is intended to mobilize researchers to apply recent advances in natural language processing
to generate new insights in support of the fight against this infectious disease.
:Citation:
Wang, L.L., Lo, K., Chandrasekhar, Y., Reas, R., Yang, J., Eide, D.,
Funk, K., Kinney, R., Liu, Z., Merrill, W. and Mooney, P. "Cord-19: The COVID-19 Open Research Dataset.", 2020... automodule:: recommenders.datasets.covid_utils
:members:
Criteo
Criteo dataset <https://www.kaggle.com/c/criteo-display-ad-challenge/overview>_, released by Criteo Labs, is an online advertising dataset that contains feature values and click feedback
for millions of display Ads. Every Ad has has 40 attributes, the first attribute is the label where a value 1 represents
that the Ad has been clicked on and a 0 represents it wasn't clicked on. The rest consist of 13 integer columns and
26 categorical columns.
.. automodule:: recommenders.datasets.criteo
:members:
MIND
MIcrosoft News Dataset (MIND) <https://msnews.github.io/>_, is a large-scale dataset for news recommendation research. It was collected from
anonymized behavior logs of Microsoft News website.
MIND contains about 160k English news articles and more than 15 million impression logs generated by 1 million users.
Every news article contains rich textual content including title, abstract, body, category and entities.
Each impression log contains the click events, non-clicked events and historical news click behaviors of this user before
this impression. To protect user privacy, each user was de-linked from the production system when securely hashed into an anonymized ID.
:Citation:
Fangzhao Wu, Ying Qiao, Jiun-Hung Chen, Chuhan Wu, Tao Qi, Jianxun Lian, Danyang Liu, Xing Xie, Jianfeng Gao, Winnie Wu
and Ming Zhou, "MIND: A Large-scale Dataset for News Recommendation", ACL, 2020... automodule:: recommenders.datasets.mind
:members:
MovieLens
The MovieLens datasets <https://grouplens.org/datasets/movielens/>_, first released in 1998,
describe people's expressed preferences
for movies. These preferences take the form of `` tuples,
each the result of a person expressing a preference (a 0-5 star rating) for a movie
at a particular time.
It comes with several sizes:
- MovieLens 100k: 100,000 ratings from 1000 users on 1700 movies.
- MovieLens 1M: 1 million ratings from 6000 users on 4000 movies.
- MovieLens 10M: 10 million ratings from 72000 users on 10000 movies.
- MovieLens 20M: 20 million ratings from 138000 users on 27000 movies
:Citation:
F. M. Harper and J. A. Konstan. "The MovieLens Datasets: History and Context".
ACM Transactions on Interactive Intelligent Systems (TiiS) 5, 4, Article 19,
DOI=http://dx.doi.org/10.1145/2827872, 2015... automodule:: recommenders.datasets.movielens
:members:
Download utilities
.. automodule:: recommenders.datasets.download_utils
:members:
Pandas dataframe utilities
.. automodule:: recommenders.datasets.pandas_df_utils
:members:
Splitter utilities ****************** Python splitters
.. automodule:: recommenders.datasets.python_splitters
:members:
PySpark splitters
.. automodule:: recommenders.datasets.spark_splitters
:members:
Other splitters utilities
.. automodule:: recommenders.datasets.split_utils
:members:
Sparse utilities
.. automodule:: recommenders.datasets.sparse
:members:
Knowledge graph utilities
.. automodule:: recommenders.datasets.wikidata
:members:
File: docs/evaluation.rst
.. _evaluation:
Evaluation module
Python evaluation
.. automodule:: recommenders.evaluation.python_evaluation
:members:
PySpark evaluation
.. automodule:: recommenders.evaluation.spark_evaluation
:members:
:special-members: init
File: docs/intro.md
Welcome to Recommenders
Recommenders objective is to assist researchers, developers and enthusiasts in prototyping, experimenting with and bringing to production a range of classic and state-of-the-art recommendation systems.
```sh
pip install recommenders
```
<a class="github-button" href="https://github.com/recommenders-team/recommenders" data-icon="octicon-star" style="margin:auto" data-size="large" data-show-count="true" aria-label="Star Recommenders on GitHub">Star Us</a><script async defer src="https://buttons.github.io/buttons.js"></script>Recommenders is a project under the Linux Foundation of AI and Data.
This repository contains examples and best practices for building recommendation systems, provided as Jupyter notebooks.
The examples detail our learnings on five key tasks:
- Prepare Data: Preparing and loading data for each recommendation algorithm.
- Model: Building models using various classical and deep learning recommendation algorithms such as Alternating Least Squares (ALS) or eXtreme Deep Factorization Machines (xDeepFM).
- Evaluate: Evaluating algorithms with offline metrics.
- Model Select and Optimize: Tuning and optimizing hyperparameters for recommendation models.
- Operationalize: Operationalizing models in a production environment.
Several utilities are provided in the recommenders library to support common tasks such as loading datasets in the format expected by different algorithms, evaluating model outputs, and splitting training/test data. Implementations of several state-of-the-art algorithms are included for self-study and customization in your own applications.
File: docs/models.rst
.. _recommender:
Recommender algorithms module
##############################
Recommender system algorithms and utilities.
Cornac utilities
.. automodule:: recommenders.models.cornac.cornac_utils
:members:
.. automodule:: recommenders.models.cornac.bpr
:members:
:special-members: init
DeepRec utilities ****************************** Base model
.. automodule:: recommenders.models.deeprec.models.base_model
:members:
:special-members: init
Sequential base model
.. automodule:: recommenders.models.deeprec.models.sequential.sequential_base_model
:members:
:special-members: init
Iterators
.. automodule:: recommenders.models.deeprec.io.iterator
:members:
:special-members: init
.. automodule:: recommenders.models.deeprec.io.dkn_iterator
:members:
:special-members: init
.. automodule:: recommenders.models.deeprec.io.dkn_item2item_iterator
:members:
:special-members: init
.. automodule:: recommenders.models.deeprec.io.nextitnet_iterator
:members:
:special-members: init
.. automodule:: recommenders.models.deeprec.io.sequential_iterator
:members:
:special-members: init
Data processing utilities
.. automodule:: recommenders.models.deeprec.DataModel.ImplicitCF
:members:
:special-members: init
Utilities
.. automodule:: recommenders.models.deeprec.deeprec_utils
:members:
:special-members: init, repr
DKN
.. automodule:: recommenders.models.deeprec.models.dkn
:members:
:special-members: init
DKN item-to-item
.. automodule:: recommenders.models.deeprec.models.dkn_item2item
:members:
:special-members: init
xDeepFM
.. automodule:: recommenders.models.deeprec.models.xDeepFM
:members:
:special-members: init
LightGCN
.. automodule:: recommenders.models.deeprec.models.graphrec.lightgcn
:members:
:special-members: init
A2SVD
.. automodule:: recommenders.models.deeprec.models.sequential.asvd
:members:
:special-members: init
Caser
.. automodule:: recommenders.models.deeprec.models.sequential.caser
:members:
:special-members: init
GRU
.. automodule:: recommenders.models.deeprec.models.sequential.gru
:members:
:special-members: init
NextItNet
.. automodule:: recommenders.models.deeprec.models.sequential.nextitnet
:members:
:special-members: init
SUM
.. automodule:: recommenders.models.deeprec.models.sequential.sum
:members:
:special-members: init
.. automodule:: recommenders.models.deeprec.models.sequential.sum_cells
:members:
:special-members: init
SLIRec
.. automodule:: recommenders.models.deeprec.models.sequential.pytorch.sli_rec
:members:
:special-members: init
.. automodule:: recommenders.models.deeprec.models.sequential.pytorch.sequential_base
:members:
:special-members: init
.. automodule:: recommenders.models.deeprec.models.sequential.pytorch.rnn_cell
:members:
:special-members: init
EmbDotBias utilities
.. automodule:: recommenders.models.embdotbias.data_loader
:members:
:special-members: init
.. automodule:: recommenders.models.embdotbias.model
:members:
:special-members: init
.. automodule:: recommenders.models.embdotbias.training_utils
:members:
:special-members: init
.. automodule:: recommenders.models.embdotbias.utils
:members:
LightFM utilities
.. automodule:: recommenders.models.lightfm.lightfm_utils
:members:
LightGBM utilities
.. automodule:: recommenders.models.lightgbm.lightgbm_utils
:members:
NCF
.. automodule:: recommenders.models.ncf.dataset
:members:
:special-members: init
.. automodule:: recommenders.models.ncf.ncf_singlenode
:members:
:special-members: init
NewsRec utilities ****************************** Base model
.. automodule:: recommenders.models.newsrec.models.base_model
:members:
:special-members: init
Iterators
.. automodule:: recommenders.models.newsrec.io.mind_iterator
:members:
:special-members: init
.. automodule:: recommenders.models.newsrec.io.mind_all_iterator
:members:
:special-members: init
Utilities
.. automodule:: recommenders.models.newsrec.models.layers
:members:
:special-members: init
.. automodule:: recommenders.models.newsrec.newsrec_utils
:members:
:special-members: init
LSTUR
.. automodule:: recommenders.models.newsrec.models.lstur
:members:
:special-members: init
NAML
.. automodule:: recommenders.models.newsrec.models.naml
:members:
:special-members: init
NPA
.. automodule:: recommenders.models.newsrec.models.npa
:members:
:special-members: init
NRMS
.. automodule:: recommenders.models.newsrec.models.nrms
:members:
:special-members: init
RBM
.. automodule:: recommenders.models.rbm.rbm
:members:
:special-members: init
.. FIXME: Fix Pymanopt dependency. Issue #2038
.. GeoIMC
.. ******************************
.. .. automodule:: recommenders.models.geoimc.geoimc_algorithm
.. :members:
.. :special-members: init
.. .. automodule:: recommenders.models.geoimc.geoimc_data
.. :members:
.. :special-members: init
.. .. automodule:: recommenders.models.geoimc.geoimc_predict
.. :members:
.. .. automodule:: recommenders.models.geoimc.geoimc_utils
.. :members:
.. FIXME: Fix Pymanopt dependency. Issue #2038
.. RLRMC
.. ******************************
.. .. automodule:: recommenders.models.rlrmc.RLRMCdataset
.. :members:
.. :special-members: init
.. .. automodule:: recommenders.models.rlrmc.RLRMCalgorithm
.. :members:
.. :special-members: init
.. .. automodule:: recommenders.models.rlrmc.conjugate_gradient_ms
.. :members:
.. :special-members: init
SAR
.. automodule:: recommenders.models.sar.sar_singlenode
:members:
:special-members: init
SASRec
.. automodule:: recommenders.models.sasrec.model
:members:
:special-members: init
.. automodule:: recommenders.models.sasrec.sampler
:members:
:special-members: init
.. automodule:: recommenders.models.sasrec.util
:members:
SSE-PT
.. automodule:: recommenders.models.sasrec.ssept
:members:
:special-members: init
Surprise utilities
.. automodule:: recommenders.models.surprise.surprise_utils
:members:
TF-IDF utilities
.. automodule:: recommenders.models.tfidf.tfidf_utils
:members:
Standard VAE
.. automodule:: recommenders.models.vae.standard_vae
:members:
:special-members: init
Multinomial VAE
.. automodule:: recommenders.models.vae.multinomial_vae
:members:
:special-members: init
Vowpal Wabbit utilities
.. automodule:: recommenders.models.vowpal_wabbit.vw
:members:
Wide & Deep
.. automodule:: recommenders.models.wide_deep.wide_deep_utils
:members:
:special-members: init
File: docs/tuning.rst
.. _tuning:
Hyperparameter tuning module
Hyperparameter tuning module from Recommenders utilities.
Parameter sweep utils
.. automodule:: recommenders.tuning.parameter_sweep
:members: