Getting Started

Supported Platforms

Currently, due to libraries we use, this project only installs easily on Linux, and Python 3.6.

Other platforms such as Windows, OSX, and Google Colab may work, but not without additional effort.

Installation Tutorial

1. Checkout the project with git

git clone https://github.com/luksfarris/deeprecsys.git deeprecsys
cd deeprecsys

2. Create a virtual envirnoment and install python requirements

python3.6 -m venv venv
source ./venv/bin/activate
pip install pip==21.0.1 setuptools==56.0.0 wheel==0.36.2
# we use the fantastic Poetry dependency manager
pip install poetry==1.1.6
poetry install

3. Prepare the MLFairnessGym fork and download the dataset

# prepare submodules
git submodule init
git submodule update --remote
# install ml fairness using custom setup script
python mlfairnessgym.setup.py install
# download movielens data
python -m mlfairnessgym.environments.recommenders.download_movielens

You should now see the following CSV files in the /output folder: movies.csv, ratings.csv, and users.csv.

You can now start a notebook server by running:

cd notebooks
jupyter notebook

Checkout the getting_started notebook (nbviewer link) for an overview of the environment and the behavior of a random agent.

Optional Steps

Running Unit Tests

This project uses pytest and coverage.

# from project root
poetry run coverage run -m pytest
# to generate a coverage report run
poetry run coverage html -d html/coverage

The coverage report can be located at html/coverage/index.html.

Generating Docs

# from project root
poetry run pdoc --html --force deeprecsys -o docs/api

Some errors may be raised, but feel free to ignore them. The technical documentation for the project can be found in docs/api/deeprecsys/index.html.