# Tell Me Why


<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

<p align="center">

<img src="https://raw.githubusercontent.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io/main/nbs/images/Tell_Me_Why_logo.png" alt="Tell Me Why logo" width="420">
</p>

## What this library does

Tell Me Why helps you:

1.  **Train** an explainable xAAEnet on a two-class image task
    (`train_xaaenet`: adversarial → autoencoder → classifier).
2.  **Score** images with hand-crafted pixel cues
    (`compute_feature_score_table`: brightness, color, texture,
    frequency, …).
3.  **Interpret** the classifier by comparing those cues to the model’s
    PLS decision axis (`run_pls_feature_figures`: importance ranking and
    alignment panels).

You can use the built-in **`AAE`** model or attach xAAEnet blocks to
**your own encoder** (`EncoderWithAAEBlocks`).

## Scope

**Binary image classifiers only** for now. Multi-class classification,
regression, and non-image modalities are not supported yet.

Input images should be at least about **160×160** pixels (reconstruction
loss uses MS-SSIM).

## Model at a glance

An encoder maps each image to a representation vector **z**. A decoder
reconstructs the image; a discriminator regularizes **z**; a classifier
predicts the label from **z**.

<figure>
<img
src="https://raw.githubusercontent.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io/main/nbs/images/schema_bloc_AAE.png"
alt="xAAEnet block diagram" />
<figcaption aria-hidden="true">xAAEnet block diagram</figcaption>
</figure>

Details: [xAAEnet model](model_aae.html) · Training API: [Train an
explainable xAAEnet](training.html)

## Interpretation at a glance

After training, compare validation **z** and class labels to a table of
feature scores.

**Importance ranking** — which pixel cues align most with the decision
axis (start here):

<figure>
<img
src="https://raw.githubusercontent.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io/main/nbs/images/feature_importance_ranking_example.png"
alt="Feature importance ranking example" />
<figcaption aria-hidden="true">Feature importance ranking
example</figcaption>
</figure>

**Alignment panels** — one scatter per feature (PLS1 vs score); use this
to sanity-check the top-ranked cues:

<figure>
<img
src="https://raw.githubusercontent.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io/main/nbs/images/feature_alignment_panels_example.png"
alt="Feature alignment panels example" />
<figcaption aria-hidden="true">Feature alignment panels
example</figcaption>
</figure>

How to read these figures: [Classification
interpretation](visualization.html)

## Get started

**Install** (see also the [repository
README](https://github.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io/blob/main/README.md)):

``` bash
conda env create -f environment.yml
conda activate tell-me-why
pip install -e ".[dev]"
```

**Minimal training call:**

``` python
from tell_me_why.model_aae import AAE
from tell_me_why.training import train_xaaenet

model = AAE(input_size=160, input_channels=3, encoding_dims=128, classes=2)
learn = train_xaaenet(model, dls)  # fastai DataLoaders: ImageBlock + CategoryBlock
```

Recommended next step: [End-to-end walkthrough](walkthrough.html) (PETS,
cat vs dog).

## Documentation map

<table>
<colgroup>
<col style="width: 27%" />
<col style="width: 72%" />
</colgroup>
<thead>
<tr>
<th>Page</th>
<th>You will find</th>
</tr>
</thead>
<tbody>
<tr>
<td><a href="model_aae.html">xAAEnet model</a></td>
<td><code>AAE</code> architecture, decoder, losses</td>
</tr>
<tr>
<td><a href="feature_scores.html">Feature scores</a></td>
<td>Pixel scores and PETS example</td>
</tr>
<tr>
<td><a href="user_encoder.html">Add xAAEnet blocks to your
encoder</a></td>
<td><code>EncoderWithAAEBlocks</code></td>
</tr>
<tr>
<td><a href="training.html">Train an explainable xAAEnet</a></td>
<td><code>train_xaaenet</code>, phases, checkpoints</td>
</tr>
<tr>
<td><a href="visualization.html">Classification interpretation</a></td>
<td>Reading ranking and alignment figures</td>
</tr>
<tr>
<td><a href="walkthrough.html">End-to-end walkthrough</a></td>
<td>Full pipeline on PETS</td>
</tr>
</tbody>
</table>

## About this site

The library and this documentation were developed with
[nbdev](https://nbdev.fast.ai/) (notebooks in `nbs/` export to the
`tell_me_why/` package). The GitHub
[README](https://github.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io/blob/main/README.md)
is maintained separately for installation and repository overview.