# Tell Me Why


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

## Current scope

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

<p align="center">

<img src="images/Tell_Me_Why_logo.png" alt="Tell Me Why logo" width="420">
</p>

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