How amshaker/unetr_plus_plus works
Project type and purpose
• This is an open-source deep learning pipeline for 3D medical image segmentation called UNETR++.
• It provides scripts and a modular Python package (unetr_pp/) to plan experiments, preprocess data, define the transformer-based UNETR++ network, train models, run inference, postprocess outputs, and evaluate results on multiple medical datasets.
A. Dataset
• Raw image volumes and labels organized per task (Synapse, ACDC, Lung, Tumor).
• Folder structure under DATASET_* with imagesTr, labelsTr, imagesTs, labelsTs, dataset.json.
B. Experiment Planner (unetr_pp/experiment_planning/)
• Analyzes dataset properties (voxel spacing, patch sizes, normalization).
• Generates plan files (plans.pkl) guiding cropping and network configuration.
C. Preprocessing (unetr_pp/preprocessing/)
• Cropping, normalization, sanity checks on raw volumes.
• Produces cropped, standardized input patches.
D. Training Pipeline
1. Configuration & Runner (unetr_pp/run/)
• Parses CLI args (default_configuration.py), builds training config.
• Calls run_training.py.
2. Data Loading & Augmentation
• unetr_pp/training/dataloading/dataset_loading.py
• unetr_pp/training/data_augmentation/ modules for different DA strategies.
3. Model Architecture (unetr_pp/network_architecture/)
• Defines UNETR++ encoder–decoder with Efficient Paired Attention blocks, transformer and conv components.
4. Optimization & Loss
• Learning rate schedulers (poly_lr.py), custom optimizers (ranger.py), loss functions (Dice, CrossEntropy, TopK, deep supervision).
5. Trainer Classes (unetr_pp/training/network_training/)
• Task-specific Trainers (e.g., unetr_pp_trainer_synapse.py), orchestration of forward/backward, checkpointing.
E. Inference (unetr_pp/inference/)
• CLI scripts (inference_synapse.py, predict.py) load saved model, apply to test set, output segmentation masks.
F. Postprocessing (unetr_pp/postprocessing/)
• Connected components filtering, consolidation for final submission files.
G. Evaluation (unetr_pp/evaluation/)
• Computes Dice, HD95 metrics, aggregates results, ranks models, ensembles predictions, writes JSON/CSV summaries.
H. Utilities (unetr_pp/utilities/)
• Shared helpers: file I/O, distributed training, one-hot encoding, sitk wrappers, tensor utilities.
• Dataset → Experiment Planner → Preprocessing → Training Pipeline → Checkpoint
• Checkpoint + Dataset → Inference → Raw Predictions → Postprocessing → Cleaned Masks
• Cleaned Masks + Ground Truth → Evaluation → Metrics & Summaries
• Configuration & Runner orchestrates Experiment Planner, Preprocessing, Training Pipeline.
Architectural patterns & design principles
• Modularity: clear separation of concerns in sub-packages (planning, preprocessing, training, inference, evaluation).
• Pipeline: linear sequential dataflow with checkpoints between stages.
• Extensibility: task-specific scripts, plugin-style experiment planners, data augmenters, loss functions.
• Reusability: shared utilities across tasks; network components parameterized per task.