An open source project from Data to AI Lab at MIT.

Pyreal

Library for generating useful and usable machine learning explanations.

• License: MIT
• Documentation: https://pyreal.gitbook.io/pyreal
• API Documentation: https://sibyl-ml.dev/pyreal/api_reference/index.html
• Homepage: https://sibyl-ml.dev/

Overview

Pyreal wraps the complete machine learning explainability pipeline into RealApp objects, which seamlessly provide usable explanations in a low-code manner.

Install

Requirements

Pyreal has been developed and tested on Python 3.8, 3.9, and 3.10 The library uses Poetry for package management.

Install from PyPI

We recommend using pip in order to install Pyreal:

pip install pyreal

This will pull and install the latest stable release from PyPI.

Install from source

If you do not have poetry installed, please head to poetry installation guide and install poetry according to the instructions.
Run the following command to make sure poetry is activated. You may need to close and reopen the terminal.

poetry --version

Finally, you can clone this repository and install it from source by running poetry install, with the optional examples extras if you'd like to run our tutorial scripts.

git clone https://github.com/sibyl-dev/pyreal.git
cd pyreal
poetry install

Install for Development

If you want to contribute to the project, a few more steps are required to make the project ready for development.

Please head to the Contributing Guide for more details about this process.

Quickstart

In this short tutorial we will guide you through a series of steps that will help you getting started with Pyreal. We will get an explanation for a prediction on whether a passenger on the Titanic would have survived.

For a more detailed version of this tutorial, see our documentation.

Load in the demo data and application

>>> import pyreal.sample_applications.titanic as titanic

>>> real_app = titanic.load_app()
>>> sample_data = titanic.load_data(n_rows=300)

Predict and produce explanation

>>> predictions = real_app.predict(sample_data)

>>> explanation = real_app.produce_feature_contributions(sample_data)

Visualize explanation for one passenger

passenger_id = 1
plot_top_contributors(explanation[passenger_id], prediction=predictions[passenger_id], show=False)

The output will be a bar plot showing the most contributing features, by absolute value.

We can see here that the input passenger's predicted chance of survival was greatly reduced because of their sex (male) and ticket class (3rd class).

Troubleshoot

For macOS users, an error regarding lightgbm might arise when running the titanic tutorial due to lack of lightgbm installation. If this occurs, please run the following line in your terminal to install lightgbm.

brew install lightgbm

Terminology

Pyreal introduces specific terms and naming schemes to refer to different feature spaces and transformations. The Terminology User Guide provides an introduction to these terms.

What's next?

For more details about Pyreal and all its possibilities and features, please check the documentation site.