Tell Me Why

Explainable xAAEnet models for binary image classification — train, then relate model representations to readable pixel-level feature scores.

Tell Me Why logo

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

Details: xAAEnet model · Training API: Train an explainable xAAEnet

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

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

Feature alignment panels example

How to read these figures: Classification interpretation

Get started

Install (see also the repository README):

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

Minimal training call:

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 (PETS, cat vs dog).

Documentation map

Page You will find
xAAEnet model AAE architecture, decoder, losses
Feature scores Pixel scores and PETS example
Add xAAEnet blocks to your encoder EncoderWithAAEBlocks
Train an explainable xAAEnet train_xaaenet, phases, checkpoints
Classification interpretation Reading ranking and alignment figures
End-to-end walkthrough Full pipeline on PETS

About this site

The library and this documentation were developed with nbdev (notebooks in nbs/ export to the tell_me_why/ package). The GitHub README is maintained separately for installation and repository overview.