# billhhh/shaspec architecture

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

- Interactive diagram: https://gitdiagram.com/billhhh/shaspec
- Repository: https://github.com/billhhh/shaspec

## Overview

The ShaSpec repository is a research-focused deep learning codebase for multi‐modal segmentation based on the BraTS dataset. Its primary purpose is to train and evaluate a segmentation model as described in the CVPR2023 paper “Multi-modal Learning with Missing Modality via Shared-Specific Feature Modelling.” The repository intertwines model architectures, training utilities, and several custom modifications (including mixed-precision support through its integrated apex code) to ensure sample efficiency and to operate effectively on complex neuroimaging data.

##### Main Components
- Data Input & Preprocessing:
- “BraTSDataSet.py” handles the data loading and possibly preprocessing of the BraTS dataset.
- The “datalist” directory contains CSV files that specify train, validation, and test splits.
- Utility functions in “utils/” (e.g., custom_transforms, logger, etc.) support data normalization, logging, and additional processing.

- Model Definitions & Architecture:
- Files such as “DualNet_SS.py” and “Res50.py” likely define different network architectures or components used for segmentation.
- Backend model components (shared and specific feature extractors) may be split across multiple modules.

- Training Engine & Execution:
- “engine.py” and “train_SS.py” are responsible for setting up the training process (e.g., feeding data, loss calculations, optimization, and iteration control).
- “run.sh” serves as the primary script to launch training, incorporating the necessary environment (GPU settings, hyperparameters, etc.).

- Evaluation & Post-Processing:
- “eval.py” and “eval.sh” form the evaluation part of the system where trained models are loaded, and predictions are made.
- “postprocess.py” is used to refine and format the model predictions (e.g., converting raw outputs to the final segmented outputs uploaded for online evaluation).

- Mixed Precision & Accelerated Computing (Apex Integration):
- The “apex” directory contains several submodules (such as amp, RNN, normalization, optimizers, pyprof, etc.) that offer mixed precision training, performance utilities, and custom operations.
- These components interact with the core model training pipeline to improve efficiency (e.g., handling FP16 computations, parallelism, and better memory management).

##### Determining Relationships & Interactions
- Data flows from the data directory (CSV files in “datalist”) to the data loading module (“BraTSDataSet.py”).
- Preprocessed data is fed to the training engine (“engine.py” and “train_SS.py”), which then uses one or more network definitions (from “DualNet_SS.py” and “Res50.py”).
- Evaluations run via “eval.py”/“eval.sh” and produce outputs that are then refined through “postprocess.py.”

##### Highlighting Key Architectural Patterns
- Layered Architecture: Show separation between the Data Layer, Model Layer, Training Engine, and Evaluation/Post-Processing pipeline.
- Modularity: Emphasize that components (e.g., data handling, model training, evaluation) are isolated but interact through well-defined interfaces – for instance, pipelines exchange data and logs.
- Integration with Performance Libraries: Apex is a distinct module that provides accelerated operations and should be highlighted as interfacing directly with core training scripts.

##### Relevant Technologies & Frameworks
- Python & PyTorch (the structure implies deep learning in PyTorch).
- NVIDIA Apex – integrated directly within the repository for AMP, optimizers, and mixed-precision utilities.
- Shell scripting for training/evaluation orchestration (“run.sh”, “eval.sh”).

##### Essential Elements
- Clear labels on each module/component.

- Conclude with the Evaluation and Post-Processing phases that prepare final outputs for online submission.
- To include an auxiliary section for environment and configuration files (e.g., environment.yml, requirements.txt, run.sh, eval.sh) as they provide orchestration context.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        datalistCSV["Data Source: datalist/"]:::dataLayer
        utilsCT["Utils: custom_transforms.py"]:::dataLayer
        utilsLogger["Utils: logger.py"]:::dataLayer
        dataLoader["Data Loader: BraTSDataSet.py"]:::dataLayer
    end

    %% Training Engine
    subgraph "Training Engine"
        engine["Engine: engine.py"]:::trainingLayer
        train["Trainer: train_SS.py"]:::trainingLayer
        runScript["Run Script: run.sh"]:::trainingLayer
    end

    %% Model Definitions
    subgraph "Model Definitions"
        modelDual["Model: DualNet_SS.py"]:::modelLayer
        modelRes["Model: Res50.py"]:::modelLayer
    end

    %% Apex Integration
    subgraph "Apex Integration"
        apexIntegration["Apex Modules: apex/"]:::apexLayer
    end

    %% Evaluation & Post-Processing
    subgraph "Evaluation"
        eval["Evaluator: eval.py"]:::evalLayer
        evalShell["Eval Script: eval.sh"]:::evalLayer
        postproc["Post Processing: postprocess.py"]:::evalLayer
    end

    %% Connections for Data Flow
    datalistCSV --> dataLoader
    utilsCT --> dataLoader
    utilsLogger --> dataLoader

    dataLoader --> engine
    engine --> train
    train --> runScript

    %% Training Engine uses Model Definitions and Apex
    engine --> modelDual
    engine --> modelRes
    engine --> apexIntegration

    %% Transition to Evaluation Phase
    runScript --> eval
    eval --> evalShell
    evalShell --> postproc

    %% Click Events
    click datalistCSV "https://github.com/billhhh/shaspec/tree/main/datalist/"
    click utilsCT "https://github.com/billhhh/shaspec/blob/main/utils/custom_transforms.py"
    click utilsLogger "https://github.com/billhhh/shaspec/blob/main/utils/logger.py"
    click dataLoader "https://github.com/billhhh/shaspec/blob/main/BraTSDataSet.py"
    click engine "https://github.com/billhhh/shaspec/blob/main/engine.py"
    click train "https://github.com/billhhh/shaspec/blob/main/train_SS.py"
    click runScript "https://github.com/billhhh/shaspec/blob/main/run.sh"
    click modelDual "https://github.com/billhhh/shaspec/blob/main/DualNet_SS.py"
    click modelRes "https://github.com/billhhh/shaspec/blob/main/Res50.py"
    click apexIntegration "https://github.com/billhhh/shaspec/tree/main/apex/"
    click eval "https://github.com/billhhh/shaspec/blob/main/eval.py"
    click evalShell "https://github.com/billhhh/shaspec/blob/main/eval.sh"
    click postproc "https://github.com/billhhh/shaspec/blob/main/postprocess.py"

    %% Styles
    classDef dataLayer fill:#ffe6e6,stroke:#333,stroke-width:2px;
    classDef trainingLayer fill:#e6ffe6,stroke:#333,stroke-width:2px;
    classDef modelLayer fill:#e6f7ff,stroke:#333,stroke-width:2px;
    classDef apexLayer fill:#e6f9ff,stroke:#333,stroke-width:2px;
    classDef evalLayer fill:#f9e6ff,stroke:#333,stroke-width:2px;
```
