# amshaker/unetr_plus_plus architecture

> Architecture diagram of the GitHub repository amshaker/unetr_plus_plus, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/amshaker/unetr_plus_plus
- Repository: https://github.com/amshaker/unetr_plus_plus

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Source
    DATASET[(Dataset<br/>imagesTr, labelsTr)]:::data
    click DATASET "https://github.com/amshaker/unetr_plus_plus/tree/main/DATASET_*"

    %% Experiment Planning
    subgraph "Experiment Planner" 
        EXP_PLAN["Experiment Planner<br/>plans.pkl"]:::pipeline
        click EXP_PLAN "https://github.com/amshaker/unetr_plus_plus/tree/main/unetr_pp/experiment_planning/"
    end

    %% Preprocessing
    subgraph "Preprocessing"
        PREPROC["Preprocessing<br/>cropped patches"]:::pipeline
        click PREPROC "https://github.com/amshaker/unetr_plus_plus/tree/main/unetr_pp/preprocessing/"
    end

    %% Training Pipeline
    subgraph "Training Pipeline"
        subgraph "Configuration & Runner"
            CONFIG["default_configuration.py"]:::script
            RUNNER["run_training.py"]:::script
            click CONFIG "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/run/default_configuration.py"
            click RUNNER "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/run/run_training.py"
        end
        subgraph "Data Handling"
            DATALOAD["Dataset Loading"]:::pipeline
            DAUG["Data Augmentation"]:::pipeline
            click DATALOAD "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/training/dataloading/dataset_loading.py"
            click DAUG "https://github.com/amshaker/unetr_plus_plus/tree/main/unetr_pp/training/data_augmentation/"
        end
        subgraph "Model & Optimization"
            MODEL["UNETR++ Network"]:::model
            click MODEL "https://github.com/amshaker/unetr_plus_plus/tree/main/unetr_pp/network_architecture/"
            SCHED["poly_lr.py"]:::script
            OPT["ranger.py"]:::script
            LOSS["Loss Functions"]:::script
            click SCHED "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/training/learning_rate/poly_lr.py"
            click OPT "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/training/optimizer/ranger.py"
            click LOSS "https://github.com/amshaker/unetr_plus_plus/tree/main/unetr_pp/training/loss_functions/"
        end
        subgraph "Trainer Classes"
            TR_ACDC["unetr_pp_trainer_acdc.py"]:::script
            TR_LUNG["unetr_pp_trainer_lung.py"]:::script
            TR_SYN["unetr_pp_trainer_synapse.py"]:::script
            TR_TUM["unetr_pp_trainer_tumor.py"]:::script
            click TR_ACDC "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/training/network_training/unetr_pp_trainer_acdc.py"
            click TR_LUNG "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/training/network_training/unetr_pp_trainer_lung.py"
            click TR_SYN "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/training/network_training/unetr_pp_trainer_synapse.py"
            click TR_TUM "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/training/network_training/unetr_pp_trainer_tumor.py"
        end
    end

    %% Checkpoint Output
    CHECKPT[(Model Checkpoint)]:::output

    %% Inference
    subgraph "Inference"
        INF_SYN["inference_synapse.py"]:::script
        INF_ACDC["inference_acdc.py"]:::script
        INF_TUM["inference_tumor.py"]:::script
        PRED["predict.py / predict_simple.py"]:::script
        EXP["segmentation_export.py"]:::script
        click INF_SYN "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/inference/inference_synapse.py"
        click INF_ACDC "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/inference/inference_acdc.py"
        click INF_TUM "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/inference/inference_tumor.py"
        click PRED "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/inference/predict.py"
        click PRED "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/inference/predict_simple.py"
        click EXP "https://github.com/amshaker/unetr_plus_plus/blob/main/unetr_pp/inference/segmentation_export.py"
    end

    RAW_PRED[(Raw Predictions)]:::output

    %% Postprocessing
    subgraph "Postprocessing"
        POSTPROC["Postprocessing"]:::pipeline
        click POSTPROC "https://github.com/amshaker/unetr_plus_plus/tree/main/unetr_pp/postprocessing/"
    end

    CLEAN_PRED[(Cleaned Masks)]:::output

    %% Evaluation
    subgraph "Evaluation"
        EVAL["Evaluation Metrics"]:::output
        click EVAL "https://github.com/amshaker/unetr_plus_plus/tree/main/unetr_pp/evaluation/"
    end

    %% Utilities
    UTIL["Utilities"]:::utilities
    click UTIL "https://github.com/amshaker/unetr_plus_plus/tree/main/unetr_pp/utilities/"

    %% Script Entry Points
    subgraph "Scripts"
        TR_SCRIPTS["run_training_*.sh"]:::script
        click TR_SCRIPTS "https://github.com/amshaker/unetr_plus_plus/blob/main/training_scripts/run_training_synapse.sh"
        click TR_SCRIPTS "https://github.com/amshaker/unetr_plus_plus/blob/main/training_scripts/run_training_acdc.sh"
        click TR_SCRIPTS "https://github.com/amshaker/unetr_plus_plus/blob/main/training_scripts/run_training_lung.sh"
        click TR_SCRIPTS "https://github.com/amshaker/unetr_plus_plus/blob/main/training_scripts/run_training_tumor.sh"
        EV_SCRIPTS["run_evaluation_*.sh"]:::script
        click EV_SCRIPTS "https://github.com/amshaker/unetr_plus_plus/blob/main/evaluation_scripts/run_evaluation_synapse.sh"
        click EV_SCRIPTS "https://github.com/amshaker/unetr_plus_plus/blob/main/evaluation_scripts/run_evaluation_acdc.sh"
        click EV_SCRIPTS "https://github.com/amshaker/unetr_plus_plus/blob/main/evaluation_scripts/run_evaluation_lung.sh"
        click EV_SCRIPTS "https://github.com/amshaker/unetr_plus_plus/blob/main/evaluation_scripts/run_evaluation_tumor.sh"
    end

    %% Data Flow
    DATASET -->|"raw volumes"| EXP_PLAN -->|"plans.pkl"| PREPROC -->|"cropped patches"| CONFIG
    CONFIG --> RUNNER --> DATALOAD --> DAUG --> MODEL --> SCHED --> OPT --> LOSS --> TR_SYN --> CHECKPT
    CHECKPT -->|"checkpoint & data"| INF_SYN --> PRED --> RAW_PRED --> POSTPROC --> CLEAN_PRED --> EVAL
    DATASET -->|"labels"| EVAL
    UTIL -.-> EXP_PLAN
    UTIL -.-> PREPROC
    UTIL -.-> DATALOAD
    UTIL -.-> DAUG
    UTIL -.-> MODEL
    UTIL -.-> TR_SYN
    UTIL -.-> INF_SYN
    UTIL -.-> POSTPROC
    UTIL -.-> EVAL

    TR_SCRIPTS --> RUNNER
    EV_SCRIPTS --> EVAL

    %% Legend
    subgraph Legend
        direction LR
        D1["Dataset"]:::data
        P1["Pipeline Stage"]:::pipeline
        M1["Model"]:::model
        S1["Script"]:::script
        O1["Output"]:::output
        U1["Utilities"]:::utilities
    end

    classDef data fill:#cce5ff,stroke:#004085,color:#004085;
    classDef pipeline fill:#d4edda,stroke:#155724,color:#155724;
    classDef model fill:#ffe5b4,stroke:#e69500,color:#e69500;
    classDef script fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef output fill:#fff3cd,stroke:#856404,color:#856404;
    classDef utilities fill:#f3e6ff,stroke:#5e359a,color:#5e359a;
```
