tmw-xai 0.0.2

Explainable xAAEnet training and interpretation for binary image classifiers.

Tell Me Why

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.

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

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

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.