https://github.com/sibyl-dev/pyreal
An easier approach to using and understanding ML models
https://github.com/sibyl-dev/pyreal
explainable-ai machine-learning python xai
Last synced: 3 months ago
JSON representation
An easier approach to using and understanding ML models
- Host: GitHub
- URL: https://github.com/sibyl-dev/pyreal
- Owner: sibyl-dev
- License: mit
- Created: 2020-04-17T18:52:50.000Z (about 6 years ago)
- Default Branch: dev
- Last Pushed: 2025-05-06T00:58:38.000Z (about 1 year ago)
- Last Synced: 2026-04-03T04:57:35.792Z (3 months ago)
- Topics: explainable-ai, machine-learning, python, xai
- Language: Jupyter Notebook
- Homepage:
- Size: 55.2 MB
- Stars: 24
- Watchers: 3
- Forks: 3
- Open Issues: 63
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- License: LICENSE
- Authors: AUTHORS.rst
Awesome Lists containing this project
README
An open source project from Data to AI Lab at MIT.
[](https://pypi.python.org/pypi/pyreal)
[](https://pypi.python.org/pypi/pyreal)
[](https://github.com/DAI-Lab/pyreal/actions)
[](https://join.slack.com/t/sibyl-ml/shared_invite/zt-2dyfwbgo7-2ALinuT2KDZpsVJ4rntJuA)
# Pyreal
An easier approach to understanding your model's predictions.
| Important Links | |
| --------------------------------------------- | -------------------------------------------------------------------- |
| :book: **[Documentation]** | Quickstarts and user guides |
| :memo: **[API Reference]** | Full library API |
| :apple: **[Tutorials]** | Notebooks with example usage |
| :scroll: **[License]** | This repository is published under the MIT License |
| :computer: **[Project Homepage]** | Check out the Sibyl project website for more information |
[Project Homepage]: https://sibyl-ml.dev/
[Documentation]: https://dtail.gitbook.io/pyreal/
[Tutorials]: https://github.com/sibyl-dev/pyreal/tree/dev/tutorials
[License]: https://github.com/sibyl-dev/pyreal/blob/dev/LICENSE
[Community]: https://join.slack.com/t/sibyl-ml/shared_invite/zt-2dyfwbgo7-2ALinuT2KDZpsVJ4rntJuA
[API Reference]: https://sibyl-ml.dev/pyreal/api_reference/index.html
# Overview
**Pyreal** gives you easy-to-understand explanations of your machine learning models in a low-code manner.
Pyreal wraps full ML pipelines in a RealApp object that makes it easy to use, understand, and interact with your ML model — regardless of your ML expertise.
See our tutorial series for an example of using Pyreal for house-price prediction:
- [Part 1: Learn about feature engineering and modelling](https://medium.com/mit-data-to-ai-lab/using-and-understanding-machine-learning-ml-models-ada6525cf192)
- [Part 2: Learn how to use Pyreal to use and understand ML models ](https://medium.com/mit-data-to-ai-lab/using-and-understanding-machine-learning-ml-models-0ce7c227837e)
# Install
## Requirements
**Pyreal** has been developed and tested on [Python 3.9, 3.10, and 3.11](https://www.python.org/downloads/)
The library uses Poetry for package management.
## Install from PyPI
We recommend using
[pip](https://pip.pypa.io/en/stable/) in order to install **Pyreal**:
```
pip install pyreal
```
This will pull and install the latest stable release from [PyPI](https://pypi.org/project/pyreal/).
## Install from source
If you do not have **poetry** installed, please head to [poetry installation guide](https://python-poetry.org/docs/#installation)
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](https://dtail.gitbook.io/pyreal/developer-guides/contributing-to-pyreal)
for more details about this process.
# Quickstart
In this short tutorial we will guide you through some steps to get your started with **Pyreal**.
We will use a RealApp object to get predictions and explanations on whether a passenger on the Titanic would have survived.
For a more detailed version of this tutorial, see [our documentation](https://dtail.gitbook.io/pyreal/getting-started/quickstart).
#### Load in the demo data and application
```python
import pyreal.sample_applications.titanic as titanic
real_app = titanic.load_app()
sample_data = titanic.load_data(n_rows=300)
```
#### Predict and produce explanation
```python
predictions = real_app.predict(sample_data)
explanation = real_app.produce_feature_contributions(sample_data)
```
#### Visualize explanation for one passenger
```python
passenger_id = 1
feature_bar_plot(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).
### Migrating your application to Pyreal
To create a RealApp object for your own application,
see our [migration tutorial](https://github.com/sibyl-dev/pyreal/blob/dev/tutorials/migrating_to_pyreal.ipynb).
For basic applications built on `sklearn` pipelines, you may be able to simply use:
```python
from pyreal import RealApp
pipeline = # YOUR SKLEARN PIPELINE
X_train, y_train = # YOUR TRAINING DATA
real_app = RealApp.from_sklearn(pipeline, X_train=X_train, y_train=y_train)
```
# Next Steps
For more information on using **Pyreal** for your use case, head over to the full [documentation site](https://dtail.gitbook.io/pyreal/getting-started/next-steps).