How harryr8/irc-classification-project works
This repo is a reproducible ML training + evaluation pipeline for binary classification (benign vs malignant) from breast ultrasound images, with an emphasis on patient-level data splits and honest evaluation (ROC/PR AUC, F1, sensitivity/specificity, threshold sweeps).
• Data ingestion & splitting (CSV + images)
• Dataset abstraction (model-agnostic)
• Preprocessing/augmentation at collation-time (model-specific)
• Model factory (backbones + heads + freezing modes)
• Training loop + metrics
• Run artifacts (checkpoints/config/plots/json/csv)
• CLI entrypoints (train/evaluate/sanity)
From the tree + README, the natural components are:
Entry points (CLI / orchestration)
• scripts/train.py — training CLI
• scripts/evaluate.py — evaluation CLI (threshold selection, plots, JSON/CSV outputs)
• scripts/train_all.sh — batch experimentation runner
These scripts should be shown as top-level “controllers” that call into the library code under src/busbra.
Core library (src/busbra) — the “application” layers
Data layer (src/busbra/data/)
• prepare_data.py — creates patient-level splits and writes data/splits/*
• dataset.py — BUSBRADataset returns PIL.Image + metadata (model-agnostic)
• preprocessing.py — registry mapping model_key -> transforms/processors
• loaders.py — collate functions + create_dataloaders(...)
Model layer (src/busbra/models/)
• factory.py — registry + create_model, create_backbone, get_preprocess_key
• heads.py — head architectures (linear, mlp, mlp_deep)
• __init__.py — exports
Training/eval layer (src/busbra/training/)
• trainer.py — train_one_epoch + evaluate functions
• metrics.py — threshold sweep + clinically motivated operating points
• __init__.py
• data/raw/ — dataset images + CSV (bus_data.csv)
• data/splits/ — splits.csv, patient_splits.csv, split_info.json
• runs/<model>_<timestamp>/ (implied by README usage) — config.json, best.pt, eval outputs (JSON/PNG/CSV)
• HuggingFace cache (implied) — CLIP/DINO downloads (external dependency cache)
The critical architectural choice to highlight
The key design principle here is:
Model-agnostic dataset + model-specific preprocessing at DataLoader collation time.
• why dataset.py returns raw PIL.Image
• why preprocessing.py and loaders.py are pivotal
• how switching backbones (imagenet_cnn vs clip vs dinov2) is achieved without rewriting the dataset
Raw Data Store
• data/raw/*.png + bus_data.csv
Split Builder
• busbra.data.prepare_data → writes data/splits/*
Training Orchestrator
• scripts/train.py
Data Loading Subsystem
• BUSBRADataset (PIL.Image)
• create_dataloaders + collate
• preprocessing registry (per model_key)
Model Factory
• backbone registry (ResNet/EfficientNet/DenseNet vs CLIP/DINO via HF)
• head selection + freeze mode
Trainer
• forward/backprop/optimizer (in trainer.py)
Outputs
• runs/.../best.pt, config.json, logs (if any)
Then a branch:
• scripts/evaluate.py reads best.pt + config + loaders → metrics.py → eval_*.json, roc_curve.png, threshold_sweep.csv
Zoom into the DataLoader path:
• splits.csv → BUSBRADataset.__getitem__ returns:
• image: PIL.Image
• case (patient_id)
• image_id
• DataLoader collate_fn chooses preprocessing by model_key:
• imagenet_cnn: letterbox/resize + ImageNet norm + heavy augmentations
• clip: HF CLIPProcessor + light augmentation
• dinov2/dinov3: HF AutoImageProcessor (no aug)
• Output batch dict:
• image: torch.Tensor (B,3,H,W)
• metadata lists
create_model(model_name, head_type, freeze_backbone) assembling:
• Backbone (torchvision OR HuggingFace model wrapper)
• Embedding dimension (512/768/etc.)
• Head module (heads.py) producing logits for 2 classes
• Parameter-freezing path (backbone frozen vs full fine-tune)
Labeling
• “PIL.Image” vs “Tensor (B,3,224,224)”
• “splits.csv (train/val/test, patient-level)”
• “best.pt (model weights)”