# HW2 — Interpretability (Tabular & Vision)

Complete implementations and notebooks for interpretability experiments on tabular and image models (LIME/SHAP, Grad-CAM variants, activation maximization).

---

## Overview

- Tabular: MLP and Neural Additive Model (NAM) on the Pima diabetes dataset.
- Vision: Grad-CAM, Guided Backprop, SmoothGrad, activation maximization on pretrained CNNs.
- Includes notebook `HW2_solution.ipynb` with step-by-step experiments and report figures.

---

## Folder layout

- `code/` — scripts and modules (`tabular.py`, `vision.py`, `interpretability.py`, `models.py`).
- `notebooks/` — executed homework notebook and visual analysis.
- `report/` — LaTeX report and `figures/` used by the assignment.
- `description/` — assignment prompt and requirements.

---

## Quick setup & run

```bash
cd HomeWorks/HW2/code
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# Tabular baseline + plots
python tabular.py
python generate_report_plots.py
# Open the notebook for the full workflow
jupyter-notebook ../notebooks/HW2_solution.ipynb
```

---

## What to run for common tasks

- Tabular training & evaluation (script `tabular.py`) — loads `diabetes.csv` if present or downloads/falls back to a synthetic dataset.
- Interpretability (script `interpretability.py`) — functions for LIME and SHAP explanations on individual samples.
- Vision explanations (`vision.py`) — Grad-CAM, Guided Backprop, SmoothGrad. Notebook contains visualization examples.

---

## Custom images for the six-image vision set

The assignment asks for 6 images from different classes that the model classifies correctly. By default, the pipeline uses deterministic synthetic/demo images so it runs offline. To use your own images (files or URLs):

- **Environment variable:** set `HW2_VISION_IMAGES` to a comma-separated list of paths or URLs, then run `generate_report_plots.py` (or the notebook). Example:
  ```bash
  export HW2_VISION_IMAGES="path/to/img1.jpg,path/to/img2.png,https://example.com/img3.jpg"
  python code/generate_report_plots.py
  ```
- **CLI:** run `python code/generate_report_plots.py --images path1.jpg path2.png ...` with at least 6 paths or URLs.
- **Programmatic:** call `generate_vision_figures(custom_image_paths=["path1.jpg", "path2.png", ...])` with at least 6 paths or URLs. If you provide fewer than 6, the rest are filled with the default synthetic set.

---

## Reproducibility & notes

- The tabular loader saves a local copy `diabetes.csv` after download.
- If you have no internet, `tabular.py` uses a deterministic synthetic fallback so results are reproducible.
- Vision utilities will fall back to non‑pretrained weights if network access is unavailable (notebooks indicate that behavior).

---

## Building the report PDF

1. Generate all figures: run `python code/generate_report_plots.py` from `HomeWorks/HW2` (or from `code/`).
2. Build the PDF: run `cd report && make pdf`.

Figures are written to `report/figures/`; the LaTeX template expects them there. Run step 1 before step 2.

**One-command verification:** `python code/verify_report.py` checks that all 26 figures exist (runs the pipeline if any are missing). Use `python code/verify_report.py --build-pdf` to also build the PDF.

---

## Expected outputs

- Tabular: printed test metrics and `report/figures/` plots generated by `generate_report_plots.py`.
- Vision: saliency maps, Grad-CAM overlays, and activation-maximization images exported by the notebook.

---

## Further work (ideas)

- Compare LIME vs SHAP explanations for model bias on subpopulations.
- Use Guided Grad-CAM for class-specific visualization and compare to activation maximization.

If you want, I can expand `code/README.md` with a full CLI reference and example notebooks for each interpretability method.