Metadata-Version: 2.1
Name: pyreal
Version: 0.4.6
Summary: Library for evaluating and deploying human readable machine learning explanations.
Home-page: https://sibyl-ml.dev/
Keywords: pyreal,Pyreal
Author: Alexandra Zytek
Author-email: zyteka@mit.edu
Maintainer: MIT Data To AI Lab
Maintainer-email: dailabmit@gmail.com
Requires-Python: >=3.9,<3.12
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Requires-Dist: lime (>=0.2.0.1,<0.3.0.0)
Requires-Dist: matplotlib (>=3.6.0,<4.0.0)
Requires-Dist: numba (>=0.57.0,<0.58.0)
Requires-Dist: numpy (>=1.24.3,<2.0.0)
Requires-Dist: pandas (>=1.5,<3.0)
Requires-Dist: scikit-learn (>=1.1.2,<2.0.0)
Requires-Dist: seaborn (>=0.12.2,<0.13.0)
Requires-Dist: shap (==0.42.1)
Project-URL: Documentation, https://sibyl-dev.github.io/pyreal
Project-URL: Repository, https://github.com/DAI-Lab/pyreal
Description-Content-Type: text/markdown

<p align="left">
<img width=15% src="https://dai.lids.mit.edu/wp-content/uploads/2018/06/Logo_DAI_highres.png" alt=“DAI-Lab” />
<i>An open source project from Data to AI Lab at MIT.</i>
</p>

<!-- Uncomment these lines after releasing the package to PyPI for version and downloads badges -->

[![PyPI Shield](https://img.shields.io/pypi/v/pyreal.svg)](https://pypi.python.org/pypi/pyreal)

<!--[![Downloads](https://pepy.tech/badge/pyreal)](https://pepy.tech/project/pyreal)-->
<!--[![Travis CI Shield](https://travis-ci.org/DAI-Lab/pyreal.svg?branch=stable)](https://travis-ci.org/DAI-Lab/pyreal)-->
<!--[![Coverage Status](https://codecov.io/gh/DAI-Lab/pyreal/branch/stable/graph/badge.svg)](https://codecov.io/gh/DAI-Lab/pyreal)-->

[![Build Action Status](https://github.com/DAI-Lab/pyreal/workflows/Test%20CI/badge.svg)](https://github.com/DAI-Lab/pyreal/actions)

# Pyreal

Library for generating useful and usable machine learning explanations.

-   License: MIT
-   Documentation: [https://pyreal.gitbook.io/pyreal](https://dtail.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.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 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](https://dtail.gitbook.io/pyreal/getting-started/quickstart).

#### 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
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.

![Quickstart](docs/images/titanic.png)

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](https://dtail.gitbook.io/pyreal/developing-applications/developer-terminology-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](https://dtail.gitbook.io/pyreal/).

