Metadata-Version: 2.4
Name: tmw-xai
Version: 0.0.2
Summary: Explainable xAAEnet training and interpretation for binary image classifiers.
Author: Tell Me Why contributors
License: MIT
Project-URL: Repository, https://github.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io
Project-URL: Documentation, https://tell-me-why-xai.github.io
Keywords: pytorch,fastai,adversarial-autoencoder,explainability,binary-classification,feature-scores
Classifier: Natural Language :: English
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: <3.13,>=3.10
Description-Content-Type: text/markdown
Requires-Dist: torch>=2.4
Requires-Dist: torchvision>=0.19
Requires-Dist: fastai>=2.8.7
Requires-Dist: pytorch-msssim>=1.0
Requires-Dist: numpy<2,>=1.23
Requires-Dist: matplotlib>=3.7
Requires-Dist: scikit-learn>=1.2
Requires-Dist: scipy>=1.10
Requires-Dist: seaborn>=0.12
Provides-Extra: dev
Requires-Dist: nbdev>=3.0; extra == "dev"
Requires-Dist: jupyter>=1.0; extra == "dev"
Requires-Dist: ipykernel>=6.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"

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

![xAAEnet block
diagram](https://raw.githubusercontent.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io/main/nbs/images/schema_bloc_AAE.png)

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):

![Feature importance ranking
example](https://raw.githubusercontent.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io/main/nbs/images/feature_importance_ranking_example.png)

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

![Feature alignment panels
example](https://raw.githubusercontent.com/Tell-Me-Why-xAI/tell-me-why-xai.github.io/main/nbs/images/feature_alignment_panels_example.png)

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

| Page | You will find |
|----|----|
| [xAAEnet model](model_aae.html) | `AAE` architecture, decoder, losses |
| [Feature scores](feature_scores.html) | Pixel scores and PETS example |
| [Add xAAEnet blocks to your encoder](user_encoder.html) | `EncoderWithAAEBlocks` |
| [Train an explainable xAAEnet](training.html) | `train_xaaenet`, phases, checkpoints |
| [Classification interpretation](visualization.html) | Reading ranking and alignment figures |
| [End-to-end walkthrough](walkthrough.html) | Full pipeline on PETS |

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