BNNR
Summer learning series

Cookings: Butterfly Round 1

A student-friendly computer vision journey for summer: move from "I only have accuracy" to "I understand my model" through guided experiments.

Open in ColabView Notebook in GitHub

Launch the notebook directly in Google Colab and follow each step from training to explainability and experiment reporting.

Why this cooking?

The common student pain

Many first CV projects stop at one number. Accuracy goes up, but you still do not know whether the model learned meaningful features or just lucky shortcuts.

The BNNR mindset

This cooking teaches a practical loop: train, test augmentations, inspect XAI overlays, and connect outcomes through report.json plus events/history. You learn what changed and why.

Educational path: from baseline to insight

1

Step 1: Run baseline

Start with a clean training run so you can compare every later decision against a clear reference point.

2

Step 2: Explore augmentations

Test augmentation variants and see how data strategy changes stability, confidence, and final metrics.

3

Step 3: Inspect XAI overlays

Use explanations to check what the model focuses on, and catch shortcuts before they become deployment risks.

4

Step 4: Read report + events

Review report.json and the events/history log to connect training choices with concrete model behavior.

5

Step 5: Write insights for CV/portfolio

Turn your experiment into a clear engineering story: what you changed, what improved, and why it matters.

Notebook walkthrough for students (what and why)

Read this once before running the notebook. Then execute cell-by-cell and compare your observations with what the code is designed to do.

Step 1: Run baseline (setup + first run)

First, set up the environment and run a baseline training pass. This result is your reference point for every change you test later.

  • Run install and import cells without skipping.
  • Check `DEVICE` so you know if you are on GPU.
  • Write down baseline metrics for comparison.
%pip install -q "bnnr[dashboard]" matplotlib kagglehub pillow

from bnnr import BNNRConfig, BNNRTrainer, SimpleTorchAdapter

DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Device: {DEVICE}")

Step 2: Explore augmentations

Define augmentation candidates here. BNNR evaluates which combinations truly help the model instead of relying on guesswork.

  • Change augmentations intentionally, not all at once.
  • Compare each trial against the baseline.
  • Check which augmentations were finally selected.
augmentations = [
    ChurchNoise(probability=0.5, intensity=0.45, random_state=SEED),
    BasicAugmentation(probability=0.5, intensity=0.5, random_state=SEED + 1),
    TorchvisionAugmentation(
        transforms.ColorJitter(brightness=0.25, contrast=0.25, saturation=0.15),
        name_override="tv_color_jitter",
        probability=0.5,
        random_state=SEED + 20,
    ),
]

Step 3: Inspect XAI overlays

After training, inspect XAI maps to see where the model is looking in each image. This tells you whether it learns meaningful visual features.

  • Review several XAI images across different classes.
  • Check if focus is on the object, not the background.
  • Write 1-2 qualitative observations.
xai_files = sorted(glob.glob(str(run_dir / "artifacts" / "xai" / "**" / "*.png"), recursive=True))
if xai_files:
    print(f"Found {len(xai_files)} XAI PNGs. Showing up to 6:")
    for f in xai_files[:6]:
        display(IPImage(filename=f, width=560))

Step 4: Read report + events

In this step, connect metrics with process history. `report.json` shows the best result and path, while `events.jsonl` shows what happened during the run.

  • Read `best_metrics`, `best_path`, and `selected_augmentations`.
  • Check whether `events.jsonl` exists and how many entries it has.
  • Match metric changes with the event timeline.
with open(result.report_json_path, encoding="utf-8") as f:
    rep = json.load(f)
print("best_metrics:", rep.get("best_metrics"))
print("best_path:", rep.get("best_path"))
print("selected_augmentations:", rep.get("selected_augmentations"))

events = load_events(run_dir / "events.jsonl")
print("Total events:", len(events))

Step 5: Write insights for CV/portfolio

Finally, write a short engineering summary: what you tested, what worked, and why. This turns the notebook into a portfolio-ready project.

  • Compare baseline and best-performing branch.
  • Add one insight from XAI and one from events.
  • Propose one next experiment you would code yourself.
print("Best augmentation path :", result.best_path)
print("Best metrics           :", result.best_metrics)
print("Selected augmentations :", result.selected_augmentations)
print("Report JSON            :", result.report_json_path)

Student tips before and during Colab run

First pass: do not run yet. Mark where model is defined, where config is created, where training starts, and where `report.json` / `events.jsonl` are analyzed.

Second pass: run cell-by-cell and keep a mini lab note with 3 lines per step: what changed, what you expected, what actually happened.

Best portfolio format for this round: baseline metrics, strongest augmentation branch, one XAI insight, and one next experiment you would code yourself.

What you'll ship after this

  • A reproducible training notebook run you can show in interviews.
  • XAI screenshots and interpretation notes that prove model understanding.
  • A report.json and event-history narrative for experiment traceability.
  • A compact augmentation comparison with practical conclusions.
  • A portfolio-ready write-up from accuracy-only to model insight.

Ready for Cooking Round 1?

Start now in Colab, then continue in the docs to prepare for future rounds and deeper experiments.

Open in ColabExplore notebooks in docs