HomeWorks/HW2/README.md

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

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:

  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.