Overview

docs
tests
package

MARS-Gym (MArketplace Recommender Systems Gym), a benchmark framework for modeling, training, and evaluating RL-based recommender systems for marketplaces.

Three main components composes the framework:

• Data Engineering Module: A highly customizable module where the consumer can ingest and process a massive amount of data for learning using spark jobs.
• Simulation Module: Holds an extensible module built on top of PyTorch to design learning architectures. It also possesses an OpenAI’s Gym environment that ingests the processed dataset to run a multi-agent system that simulates the targeted marketplace.
• Evaluation Module: Provides a set of distinct perspectives on the agent’s performance. It presents traditional recommendation metrics, off-policy evaluation metrics, and fairness indicators. This component is powered by a user-friendly interface to facilitate the analysis and comparison betweenagents

Framework

Dependencies and Requirements

• python=3.6.7
• pandas=0.25.1
• matplotlib=2.2.2
• scipy=1.3.1
• numpy=1.17.0
• seaborn=0.8.1
• scikit-learn=0.21.2
• pytorch=1.2.0
• tensorboardx=1.6
• luigi=2.7.5
• tqdm=4.33
• requests=2.18.4
• jupyterlab=1.0.2
• ipywidgets=7.5.1
• diskcache=3.0.6
• pyspark=2.4.3
• psutil=5.2.2
• category_encoders
• plotly=4.4.1
• imbalanced-learn==0.4.3
• torchbearer==0.5.1
• pytorch-nlp==0.4.1
• unidecode==1.1.1
• streamlit==0.52.2
• gym==0.15.4

Free software: MIT license

Installation

pip install mars-gym

You can also install the in-development version with:

pip install https://github.com/deeplearningbrasil/mars-gym/archive/master.zip

Documentation

https://mars-gym.readthedocs.io/

Development

To run the all tests run:

tox

Note, to combine the coverage data from all the tox environments run:

Windows	set PYTEST_ADDOPTS=--cov-append tox
Other	PYTEST_ADDOPTS=--cov-append tox

Usage

Simulate Example

mars-gym run interaction --project PROJECT \
--n-factors N_FACTORS --learning-rate LR --optimizer OPTIMIZER \
--epochs EPOCHS --obs-batch-size OBS_BATCH \
--batch-size BATCH_SIZE --num-episodes NUM_EP \
--bandit-policy BANDIT --bandit-policy-params BANDIT_PARAMS

Evaluate Example

mars-gym evaluate iteraction \
 --model-task-id MODEL_TASK_ID --fairness-columns "[]" \
 --direct-estimator-class DE_CLASS

Evaluation Module

mars-gym viz

Cite

Please cite the associated paper for this work if you use this code:

@misc{santana2020marsgym,
      title={MARS-Gym: A Gym framework to model, train, and evaluate Recommender Systems for Marketplaces},
      author={Marlesson R. O. Santana and Luckeciano C. Melo and Fernando H. F. Camargo and Bruno Brandão and Anderson Soares and Renan M. Oliveira and Sandor Caetano},
      year={2020},
      eprint={2010.07035},
      archivePrefix={arXiv},
      primaryClass={cs.IR}
}