Tell Me Why

nbdev library for adding xAAEnet analysis blocks to binary image classifiers.

Current scope

This library currently supports only binary image classifiers. Multi-class classification, regression, and non-image modalities are not supported yet.

nbdev Workflow

1. The maintained code lives in the nbs/*.ipynb notebooks.
2. Cells exported to the library use the #| export directive.
3. The nbdev_export command regenerates the Python modules in tell_me_why/.
4. Tests verify that the package imports correctly and that the stabilized building blocks remain usable.

Generated .py files are not the source of truth: any lasting change must be made in the notebooks.

Notebook Map

• 01_model_aae.ipynb: definition of the AAE model, the U-Net decoder with dropout on skip connections, and the associated loss functions for binary classification.
• 02_feature_scores.ipynb: feature-score computation functions to reuse in analyses.
• 03_user_encoder.ipynb: logic for adding xAAEnet blocks to a user-provided binary classifier encoder.
• 04_training.ipynb: train_xaaenet and training callbacks (adversarial → autoencoder → classifier).
• 05_visualization.ipynb (Classification Interpretation): alignment panels and feature-importance ranking from latent z and feature scores.
• 06_tutorial.ipynb: complete example of how to use the library, without any requirement to export code.

Development Priority

The first goal is to stabilize a minimal API around the AAE model, then add the analysis building blocks one by one.

1. Finalize and export 01_model_aae.ipynb.
2. Add reusable scores in 02_feature_scores.ipynb.
3. Define the user-encoder interface in 03_user_encoder.ipynb.
4. Document the three-phase training workflow in 04_training.ipynb.
5. Connect binary-classification/feature-score visualizations in 05_visualization.ipynb.
6. Turn 06_tutorial.ipynb into a user walkthrough once the previous modules are usable.