# china-liuxiaopeng/brats-dmfnet architecture

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

- Interactive diagram: https://gitdiagram.com/china-liuxiaopeng/brats-dmfnet
- Repository: https://github.com/china-liuxiaopeng/brats-dmfnet

## Overview

##### Project type and purpose
- This is a deep-learning research codebase for real-time 3D brain tumor segmentation (BraTS 2018) using a Dilated Multi-Fiber Network (DMFNet) implemented in PyTorch.
- It contains data‐preprocessing, training, testing, experiment configuration, model definition (including synchronized batch-norm), and utilities.

##### File structure
- Top-level scripts:
- preprocess.py       → converts .nii to .pkl
- split.py            → k-fold split
- train_all.py/train_fold.py → orchestrate training over GPUs/folds
- test.py             → evaluation, TTA, postprocess
- predict.py          → (if used for inference)
- Directories:
- data/               → data loading pipeline (data_utils, datasets, transforms, sampler)
- models/             → DMFNet class, sync_batchnorm submodule
- experiments/        → YAML config files (hyperparams, data paths)
- ckpts/              → checkpoint storage
- utils/              → argument parsing, criterions, boolean flags
- submission results/ → saved CSV results
- Config/build:
- experiments/PATH.yaml → dataset path
- utils/parser.py       → reads YAML into experiment object
- Dependencies: PyTorch, nibabel, pickle, YAML parser.

##### Key insights from README
- Modular design: separate preprocess, split, train, test phases.
- Uses synchronized batch-norm for multi-GPU training (models/sync_batchnorm).
- Experiment driven by .yaml files in experiments/.
- Standard PyTorch training loop with DataLoader, optimizer, loss criterion.

##### Main components
a. External data source
- BraTS 2018 raw .nii files
b. Preprocessing pipeline
- preprocess.py
- Output: .pkl files in data/
c. Data ingestion & augmentation
- data/datasets.py, data/transforms.py, data/sampler.py
- DataLoader → batches
d. Experiment configuration
- experiments/*.yaml
- utils/parser.py → experiment hyperparams
e. Training orchestrator
- train_all.py / train_fold.py
- Builds model, DataLoaders, criterion, optimizer, scheduler
f. Model definition
- models/DMFNet_16x.py (network layers with dilated multi-fiber blocks)
- models/sync_batchnorm (distributed batch-norm)
g. Checkpointing & logging
- ckpts/DMFNet_GDL_all/
h. Testing & evaluation
- test.py (TTA, postprocess, snapshot)
- Outputs performance metrics (Dice scores) → submission results
i. Utilities
- utils/criterions.py, utils/str2bool.py

##### Architectural patterns & design principles
- Pipeline separation: distinct preprocessing, training, testing stages.
- Config-driven experiments: keeps code generic, hyperparams in YAML.
- Modular model code: network and sync_batchnorm submodule.
- Reusability: data utilities, parser, criterions abstract common logic.

##### Elements
- Clear labels on all components (e.g., “preprocess.py”, “data.datasets.DataLoader”, “models.DMFNet_16x”).
- Green for scripts (preprocess.py, train_all.py, test.py)
- Orange for external resources (raw dataset, checkpoints, YAML files)
- Annotations for technologies (PyTorch, nibabel, YAML).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Resources
    RawData["BraTS 2018 raw .nii files"]:::external
    GoogleDrive["Google Drive (pretrained weights)"]:::external

    %% Data Pipeline
    subgraph "Data Pipeline"
        Preprocess["preprocess.py"]:::script
        PKL[".pkl files"]:::storage
        DataUtils["data/data_utils.py"]:::module
        Datasets["data/datasets.py"]:::module
        Transforms["data/transforms.py"]:::module
        Sampler["data/sampler.py"]:::module
        Rand["data/rand.py"]:::module
        DataLoader["DataLoader"]:::module
    end

    %% Configuration
    subgraph "Experiment Configuration"
        Experiments["experiments/*.yaml"]:::config
        Parser["utils/parser.py"]:::module
    end

    %% Splitting
    subgraph "Dataset Splitting"
        Split["split.py"]:::script
    end

    %% Training
    subgraph "Training Engine"
        TrainAll["train_all.py"]:::script
        TrainFold["train_fold.py"]:::script
        Criterion["utils/criterions.py"]:::module
        Str2Bool["utils/str2bool.py"]:::module
    end

    %% Model Definition
    subgraph "Model"
        DMFNet["models/DMFNet_16x.py"]:::module
        SyncBN["models/sync_batchnorm/"]:::module
    end

    %% Checkpointing & Logging
    subgraph "Checkpointing & Logging"
        CKPTDir["ckpts/DMFNet_GDL_all/"]:::storage
        URLTxt["url.txt"]:::storage
    end

    %% Evaluation
    subgraph "Testing & Evaluation"
        Test["test.py"]:::script
        Predict["predict.py"]:::script
        Submission["submission results/DMFNet/Stats_Validation_final.csv"]:::storage
    end

    %% Flows
    RawData -->|"input .nii"| Preprocess
    Preprocess -->|"output .pkl"| PKL
    PKL --> DataLoader
    DataLoader -->|"batches"| TrainAll
    DataLoader -->|"batches"| Test

    Experiments --> Parser
    Parser --> TrainAll
    Parser --> Test

    Split -->|"k-fold splits"| PKL

    TrainAll --> DMFNet
    TrainAll --> SyncBN
    TrainAll --> Criterion
    TrainAll --> CKPTDir
    TrainFold --> TrainAll

    CKPTDir --> URLTxt

    Test --> CKPTDir
    Test --> DMFNet
    Test --> SyncBN
    Test --> Predict
    Test --> Submission

    %% Side utilities
    Str2Bool --> TrainAll
    Criterion --> TrainAll

    %% External pretrained
    GoogleDrive --> DMFNet

    %% Click Events
    click Preprocess "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/preprocess.py"
    click DataUtils "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/data/data_utils.py"
    click Datasets "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/data/datasets.py"
    click Transforms "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/data/transforms.py"
    click Sampler "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/data/sampler.py"
    click Rand "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/data/rand.py"
    click Experiments "https://github.com/china-liuxiaopeng/brats-dmfnet/tree/master/experiments/"
    click Parser "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/utils/parser.py"
    click Split "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/split.py"
    click TrainAll "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/train_all.py"
    click TrainFold "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/train_fold.py"
    click DMFNet "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/models/DMFNet_16x.py"
    click SyncBN "https://github.com/china-liuxiaopeng/brats-dmfnet/tree/master/models/sync_batchnorm/"
    click CKPTDir "https://github.com/china-liuxiaopeng/brats-dmfnet/tree/master/ckpts/DMFNet_GDL_all/"
    click URLTxt "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/ckpts/DMFNet_GDL_all/url.txt"
    click Test "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/test.py"
    click Predict "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/predict.py"
    click Submission "https://github.com/china-liuxiaopeng/brats-dmfnet/blob/master/submission results/DMFNet/Stats_Validation_final.csv"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef script fill:#afa,stroke:#333,stroke-width:1px
    classDef module fill:#ccf,stroke:#333,stroke-width:1px
    classDef storage fill:#ffc,stroke:#333,stroke-width:1px
    classDef config fill:#fcf,stroke:#333,stroke-width:1px
```
