Beta-RecSys

Beta-RecSys an open source project for Building, Evaluating and Tuning Automated Recommender Systems. Beta-RecSys aims to provide a practical data toolkit for building end-to-end recommendation systems in a standardized way. It provided means for dataset preparation and splitting using common strategies, a generalized model engine for implementing recommender models using Pytorch with a lot of models available out-of-the-box, as well as a unified training, validation, tuning and testing pipeline. Furthermore, Beta-RecSys is designed to be both modular and extensible, enabling new models to be quickly added to the framework. It is deployable in a wide range of environments via pre-built docker containers and supports distributed parameter tuning using Ray.

Installation

conda

If you use conda, you can install it with:

conda install beta-rec

pip

If you use pip, you can install it with:

pip install beta-rec

Docker

We also provide docker image for you to run this project on any platform. You can use the image with:

  1. Pull image from Docker Hub

    docker pull betarecsys/beta-recsys:latest

  2. Start a docker container with this image (Make sure the port 8888 is available on you local machine, or you can change the port in the command)

    docker run -ti --name beta-recsys -p 8888:8888 -d beta-recsys

  3. Open Jupyter on a brower with this URL:

    http://localhost:8888

  4. Enter root as the password for the notebook.

Quick Start

Downloading and Splitting Datasets

from beta_rec.datasets.movielens import Movielens_100k
from beta_rec.data import BaseData
dataset = Movielens_100k()
split_dataset = dataset.load_leave_one_out(n_test=1)
data =  BaseData(split_dataset)

Training model with MatrixFactorization

config = {
    "config_file":"./configs/mf_default.json"
}
from beta_rec.recommenders import MatrixFactorization
model = MatrixFactorization(config)
model.train(data)
result = model.test(data.test[0])

where a default config josn file ./configs/mf_default.json will be loaded for traning the model.

Tuning Model Hyper-parameters

config = {
    "config_file":"../configs/mf_default.json",
    "tune":True,
}
tune_result = model.train(data)

Experiment with multiple models

from beta_rec.recommenders import MatrixFactorization
from beta_rec.experiment.experiment import Experiment

# Initialise recommenders with their default configuration file

config = {
    "config_file":"configs/mf_default.json"
}

mf_1 = MatrixFactorization(config)
mf_2 = MatrixFactorization(config)

# Run experiments of the recommenders on the selected dataset

Experiment(
  datasets=[data],
  models=[mf_1, mf_2],
).run()

where the model will tune the hyper-parameters according to the specifed tuning scheme (e.g. the default for MF).

Models

The following is a list of recommender models currently available in the repository, or to be implemented soon.

GitHub