# harryr8/irc-classification-project architecture

> Architecture diagram of the GitHub repository harryr8/irc-classification-project, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-03-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harryr8/irc-classification-project
- Repository: https://github.com/harryr8/irc-classification-project

## Overview

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)”

## Diagram (Mermaid)

```mermaid
flowchart TD

%% =========================
%% Orchestration / Actors
%% =========================
U["User / Researcher"]:::actor

subgraph "Orchestration (scripts/)"
direction TB
TRAIN["CLI: train.py"]:::cli
EVAL["CLI: evaluate.py"]:::cli
SANITY["CLI: sanity_dataloader.py"]:::cli
BATCH["Batch Runner: train_all.sh"]:::cli
end

%% =========================
%% Storage (data & artifacts)
%% =========================
subgraph "Storage (data/, runs/, caches)"
direction TB
RAW[("data/raw/\nImages + bus_data.csv")]:::store
MASKS_OPT[("masks/ (optional)\nlesion masks/crops")]:::store
SPLITS_DIR[("data/splits/")]:::store
SPLITS_CSV[("splits.csv\n(train/val/test)")]:::store
PATIENT_SPLITS_CSV[("patient_splits.csv\n(patient-level)")]:::store
SPLIT_INFO[("split_info.json\n(auditable metadata)")]:::store
RUNS[("runs/<run_id>/\nconfig.json + best.pt + eval outputs")]:::store
HF_CACHE[("HuggingFace Hub / cache\n(CLIP/DINO downloads)")]:::store
end

%% =========================
%% Library (src/busbra)
%% =========================
subgraph "Library (src/busbra)"
direction TB

subgraph "Data Layer (busbra.data)"
direction TB
PREPARE["prepare_data.py\nPatient-level split builder"]:::module
DATASET["dataset.py\nBUSBRADataset\nreturns PIL.Image + metadata"]:::module
PREPROC["preprocessing.py\nPreprocess registry\n(model_key → processor/transforms)"]:::module
LOADERS["loaders.py\ncreate_dataloaders + collate_fn\n(collation-time preprocessing)"]:::module

subgraph "Collation-time preprocessing (detail)"
direction TB
GETITEM["__getitem__\nPIL.Image + label + patient_id + image_id"]:::detail
SELECT_KEY["get_preprocess_key\n(model_key / preprocess_key)"]:::detail
PROC_IMAGENET["imagenet_cnn\nresize/letterbox + ImageNet norm\n(+ heavy aug)"]:::detail
PROC_CLIP["clip\nCLIPProcessor\n(+ light aug)"]:::detail
PROC_DINO["dinov2/dinov3\nAutoImageProcessor\n(no aug)"]:::detail
BATCH_OUT["Batch dict\nimage: Tensor (B,3,H,W)\nlabel:int64 + metadata"]:::detail
end
end

subgraph "Model Layer (busbra.models)"
direction TB
FACTORY["factory.py\ncreate_model/create_backbone\nregistry + get_preprocess_key"]:::module
HEADS["heads.py\nlinear / mlp / mlp_deep"]:::module
MODELS_INIT["models/__init__.py\nexports"]:::module
TORCHVISION["External: Torchvision model zoo\n(ResNet/EfficientNet/DenseNet)"]:::external
HF_HUB["External: HuggingFace vision models\n(CLIP/DINO wrappers)"]:::external
end

subgraph "Training & Eval Layer (busbra.training)"
direction TB
TRAINER["trainer.py\ntrain_one_epoch + evaluate"]:::module
METRICS["metrics.py\nROC/PR AUC + threshold sweep\noperating points (sens/spec/F1)"]:::module
TRAINING_INIT["training/__init__.py\nexports"]:::module
end

end

%% =========================
%% Tests / Verification
%% =========================
subgraph "Tests / Verification"
direction TB
TESTS["tests/ (pytest suite)"]:::test
TCHK["test_checkpoint_loading.py"]:::test
TFAC["test_factory_smoke.py"]:::test
TGRID["test_grid.py"]:::test
end

%% =========================
%% High-level pipeline flows
%% =========================
U -->|"runs"| BATCH
U -->|"runs"| TRAIN
U -->|"runs"| EVAL
U -->|"checks"| SANITY

%% Split building (auditable)
RAW -->|"bus_data.csv + metadata"| PREPARE
PREPARE -->|"writes patient-level splits"| SPLITS_DIR
SPLITS_DIR -->|"contains"| SPLITS_CSV
SPLITS_DIR -->|"contains"| PATIENT_SPLITS_CSV
SPLITS_DIR -->|"contains"| SPLIT_INFO

%% Training orchestration
BATCH -->|"invokes"| TRAIN
TRAIN -->|"reads splits (csv/json)"| SPLITS_DIR
TRAIN -->|"reads images"| RAW
TRAIN -->|"creates"| LOADERS
TRAIN -->|"creates"| FACTORY
FACTORY -->|"selects head_type"| HEADS
FACTORY -->|"loads backbone"| TORCHVISION
FACTORY -->|"loads backbone"| HF_HUB
HF_HUB -->|"downloads/caches"| HF_CACHE

%% Data loading + preprocessing (differentiator)
SPLITS_CSV -->|"index + split labels"| DATASET
PATIENT_SPLITS_CSV -->|"patient grouping"| DATASET
RAW -->|"image paths"| DATASET
DATASET -->|"__getitem__"| GETITEM
GETITEM -->|"to collate_fn"| LOADERS
FACTORY -->|"preprocess_key"| SELECT_KEY
PREPROC -->|"registry lookup"| SELECT_KEY
SELECT_KEY -->|"routes"| PROC_IMAGENET
SELECT_KEY -->|"routes"| PROC_CLIP
SELECT_KEY -->|"routes"| PROC_DINO
PROC_IMAGENET -->|"tensors"| BATCH_OUT
PROC_CLIP -->|"tensors"| BATCH_OUT
PROC_DINO -->|"tensors"| BATCH_OUT
BATCH_OUT -->|"batches"| TRAINER

%% Training outputs
TRAINER -->|"writes best.pt + config + logs"| RUNS
TRAIN -->|"saves run artifacts"| RUNS

%% Evaluation branch (threshold-aware)
EVAL -->|"reads best.pt + config"| RUNS
EVAL -->|"reads splits"| SPLITS_DIR
EVAL -->|"reads images"| RAW
EVAL -->|"optional masks_dir"| MASKS_OPT
EVAL -->|"creates"| LOADERS
EVAL -->|"calls evaluate"| TRAINER
TRAINER -->|"preds + probs + labels"| METRICS
METRICS -->|"writes roc/pr plots + sweep csv + json"| RUNS

%% Sanity checks
SANITY -->|"reads splits"| SPLITS_DIR
SANITY -->|"reads images"| RAW
SANITY -->|"creates"| LOADERS
SANITY -->|"validates batch shapes/dtypes"| BATCH_OUT

%% Tests (quality gates)
TESTS -->|"covers"| PREPARE
TESTS -->|"covers"| DATASET
TESTS -->|"covers"| LOADERS
TESTS -->|"covers"| FACTORY
TESTS -->|"covers"| TRAINER
TCHK -->|"smoke: load best.pt"| RUNS
TFAC -->|"smoke: create_model"| FACTORY
TGRID -->|"grid: configs/models"| FACTORY

%% =========================
%% Click events (component mapping)
%% =========================
click TRAIN "https://github.com/harryr8/irc-classification-project/blob/main/scripts/train.py"
click EVAL "https://github.com/harryr8/irc-classification-project/blob/main/scripts/evaluate.py"
click SANITY "https://github.com/harryr8/irc-classification-project/blob/main/scripts/sanity_dataloader.py"
click BATCH "https://github.com/harryr8/irc-classification-project/blob/main/scripts/train_all.sh"

click PREPARE "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/data/prepare_data.py"
click DATASET "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/data/dataset.py"
click PREPROC "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/data/preprocessing.py"
click LOADERS "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/data/loaders.py"

click FACTORY "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/models/factory.py"
click HEADS "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/models/heads.py"
click MODELS_INIT "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/models/__init__.py"

click TRAINER "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/training/trainer.py"
click METRICS "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/training/metrics.py"
click TRAINING_INIT "https://github.com/harryr8/irc-classification-project/blob/main/src/busbra/training/__init__.py"

click SPLITS_CSV "https://github.com/harryr8/irc-classification-project/blob/main/data/splits/splits.csv"
click PATIENT_SPLITS_CSV "https://github.com/harryr8/irc-classification-project/blob/main/data/splits/patient_splits.csv"
click SPLIT_INFO "https://github.com/harryr8/irc-classification-project/blob/main/data/splits/split_info.json"
click SPLITS_DIR "https://github.com/harryr8/irc-classification-project/tree/main/data/splits/"

click TESTS "https://github.com/harryr8/irc-classification-project/tree/main/tests/"
click TCHK "https://github.com/harryr8/irc-classification-project/blob/main/test_checkpoint_loading.py"
click TFAC "https://github.com/harryr8/irc-classification-project/blob/main/test_factory_smoke.py"
click TGRID "https://github.com/harryr8/irc-classification-project/blob/main/test_grid.py"

%% =========================
%% Styles (color is critical)
%% =========================
classDef actor fill:#0b1320,stroke:#6ea8fe,color:#eaf2ff,stroke-width:1px
classDef cli fill:#1f4b99,stroke:#9ec5fe,color:#ffffff,stroke-width:1px
classDef module fill:#198754,stroke:#8fd19e,color:#ffffff,stroke-width:1px
classDef store fill:#6f42c1,stroke:#d0bfff,color:#ffffff,stroke-width:1px
classDef external fill:#343a40,stroke:#adb5bd,color:#ffffff,stroke-dasharray: 6 4,stroke-width:1px
classDef test fill:#b02a37,stroke:#f1aeb5,color:#ffffff,stroke-width:1px
classDef detail fill:#20c997,stroke:#96f2d7,color:#073b2c,stroke-width:1px
```
