# kimyeonghyeon/metalearning-echocardiogram architecture

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

- Interactive diagram: https://gitdiagram.com/kimyeonghyeon/metalearning-echocardiogram
- Repository: https://github.com/kimyeonghyeon/metalearning-echocardiogram

## Overview

##### Project type and purpose
- This is an academic/ML research codebase implementing a few‐shot echocardiogram segmentation pipeline using model-agnostic meta‐learning (MAML, MetaSGD, MetaCurvature).
- The primary workflows are meta-training (train.py), meta-testing (test.py), and inference (inference.py), using PyTorch, learn2learn, segmentation-models-pytorch, and timm.

##### File structure
- Top-level scripts:
- train.py – launches the meta‐training loop
- test.py – runs evaluation on held-out tasks
- inference.py – performs prediction on new images
- configs/ – YAML files defining hyperparameters, data paths, shot/target settings
- meta_learning/ – older or notebook‐based meta‐learning implementations
- utils/ – shared modules: DataModule, dataset loaders, model definitions, optimizers, loss functions, training/evaluation routines

##### README insights
- Describes CLI arguments, output folder conventions (outputs-MAML…-lightning_logs), external model/data download links
- Specifies environment and dependency versions

##### Main components
a. Data Source
- Raw echocardiogram images (downloaded from Google Drive)
- Meta-train / meta-test splits
b. Configuration Manager
- YAML loader (configs/main.yaml)
- CLI argument parser (hydra/argparse)
c. DataModule & Dataset Loaders
- utils/DataModule.py orchestrates PyTorch DataLoaders
- utils/dataset*.py define per-view datasets, tasks sampling (few-shot episodes)
d. Model Zoo
- UNet and DeepLabV3Plus architectures (via segmentation-models-pytorch, timm)
- Wrapped in meta_learning/model.py or utils/model.py
e. Meta-Learning Engine
- learn2learn algorithm wrappers (MAML, MetaSGD, MetaCurvature) – meta_learning/utils/optimizer.py
- Inner-loop adaptation and outer-loop update logic (utils/train_metalearning.py)
f. Training & Evaluation Routines
- utils/train.py, utils/train_heatmap.py for standard training
- utils/train_metalearning.py for meta loops
- utils/evaluation.py for computing segmentation metrics, heatmap errors
g. Inference Pipeline
- inference.py calls DataModule → loads checkpoint → runs forward pass → utils/heatmaps.py to generate output
h. Logging & Outputs
- PyTorch Lightning logs under outputs-…-lightning_logs
- Model checkpoints saved for each version

##### Relationships and data flows
- Data Source → DataModule (batch/task generation)
- DataModule → Meta-Learning Engine ↔ Model Zoo
- Meta-Learning Engine → Loss & Optimizer → Model parameters
- Model outputs → Evaluation → Metrics → Logger
- Inference: DataModule → Model checkpoint → Output heatmaps

##### Architectural patterns & design principles
- Modular separation of concerns: data loading, model definitions, training loops, evaluation
- Plugin‐style config (YAML) decouples hyperparameters from code
- Meta-learning pattern: nested loops (inner adaptation vs. outer meta‐update)

##### Detailed elements
- Labels: “Meta-Training Script (train.py)”, “DataModule (utils/DataModule.py)”, “UNet/DeepLab Model”
- Config block pointing to configs/*.yaml, showing injection into scripts

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration Manager
    subgraph "Configuration Manager"
        Config["configs/*.yaml"]:::config
    end

    %% Scripts
    subgraph "Scripts"
        Train["Meta-Training Script (train.py)"]:::script
        Test["Meta-Testing Script (test.py)"]:::script
        Infer["Inference Script (inference.py)"]:::script
    end

    %% Data Source
    subgraph "Data Source"
        RawData["Raw Echocardiogram Images"]:::data
        Splits["Meta-Train/Test Splits"]:::data
    end

    %% Utilities
    subgraph "Utilities"
        DataModule["DataModule (utils/DataModule.py)"]:::module
        DS1["dataset.py"]:::module
        DS2["dataset_new.py"]:::module
        MLDS1["meta_learning/utils/dataset.py"]:::module
        MLDS2["meta_learning/utils/dataset_new.py"]:::module
        MLDS3["meta_learning/utils/meta_dataset.py"]:::module
    end

    %% Model Zoo
    subgraph "Model Zoo"
        ModelCore["utils/model.py"]:::module
        ModelBK["utils/model_bk.py"]:::module
        MLModel["meta_learning/model.py"]:::module
    end

    %% Meta-Learning Engine
    subgraph "Meta-Learning Engine"
        OptML["meta_learning/utils/optimizer.py"]:::module
        TrainML["utils/train_metalearning.py"]:::module
        MLETrain["meta_learning/utils/train.py"]:::module
        MLUtils["meta_learning/utils/utils.py"]:::module
    end

    %% Training & Evaluation Routines
    subgraph "Training & Evaluation"
        TrainStd["utils/train.py"]:::module
        TrainHeat["utils/train_heatmap.py"]:::module
        EvalStd["utils/evaluation.py"]:::module
        MLTrainHeat["meta_learning/utils/train_heatmap.py"]:::module
        MLEval["meta_learning/utils/evaluation.py"]:::module
        LossStd["utils/loss.py"]:::module
        MLLoss["meta_learning/utils/loss.py"]:::module
    end

    %% Inference Helpers
    subgraph "Inference Helpers"
        HeatStd["utils/heatmaps.py"]:::module
        MLHeat["meta_learning/utils/heatmaps.py"]:::module
    end

    %% External Frameworks
    subgraph "External Frameworks"
        PyTorch["PyTorch"]:::external
        L2L["learn2learn"]:::external
        SMP["segmentation-models-pytorch"]:::external
        TIMM["timm"]:::external
    end

    %% Logger & Outputs
    Logger["Logger/Outputs"]:::logs

    %% Data & Config Flow
    Config -->|loads| Train
    Config -->|loads| Test
    Config -->|loads| Infer

    Train --> DataModule
    Test --> DataModule
    Infer --> DataModule

    DataModule --> RawData
    DataModule --> Splits
    DataModule --> DS1
    DataModule --> DS2
    DataModule --> MLDS1
    DataModule --> MLDS2
    DataModule --> MLDS3

    %% Meta-Learning Flow
    DataModule --> TrainML
    TrainML --> OptML
    OptML --> MLETrain
    MLETrain --> MLUtils
    MLETrain --> ModelCore
    MLETrain --> MLModel
    MLETrain --> |"inner adaptation"| ModelCore
    MLETrain --> |"outer meta-update"| ModelCore
    L2L --> OptML

    %% Training & Evaluation Flow
    DataModule --> TrainStd
    DataModule --> TrainHeat
    DataModule --> EvalStd
    DataModule --> MLTrainHeat
    DataModule --> MLEval
    TrainStd --> LossStd
    TrainHeat --> LossStd
    MLEval --> MLLoss
    MLTrainHeat --> MLLoss
    ModelCore --> TrainStd
    ModelCore --> TrainHeat
    ModelCore --> EvalStd
    MLModel --> MLEval
    SMP --> ModelCore
    TIMM --> ModelCore

    %% Inference Flow
    Infer --> ModelCore
    Infer --> MLModel
    Infer --> HeatStd
    Infer --> MLHeat
    ModelCore --> HeatStd
    ModelCore --> MLHeat
    HeatStd --> Logger
    MLHeat --> Logger

    %% Logging
    TrainStd --> Logger
    TrainML --> Logger
    Test --> Logger

    %% External Frameworks to Model Zoo
    PyTorch --> ModelCore
    PyTorch --> MLModel

    %% Click Events
    click Train "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/train.py"
    click Test "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/test.py"
    click Infer "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/inference.py"
    click Config "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/configs/main.yaml"
    click Config "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/configs/main_bk.yaml"
    click Config "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/configs/scratch_config.yaml"
    click DataModule "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/DataModule.py"
    click DS1 "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/dataset.py"
    click DS2 "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/dataset_new.py"
    click MLDS1 "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/dataset.py"
    click MLDS2 "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/dataset_new.py"
    click MLDS3 "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/meta_dataset.py"
    click ModelCore "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/model.py"
    click ModelBK "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/model_bk.py"
    click MLModel "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/model.py"
    click OptML "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/optimizer.py"
    click TrainML "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/train_metalearning.py"
    click MLETrain "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/train.py"
    click MLUtils "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/utils.py"
    click TrainStd "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/train.py"
    click TrainHeat "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/train_heatmap.py"
    click EvalStd "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/evaluation.py"
    click MLTrainHeat "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/train_heatmap.py"
    click MLEval "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/evaluation.py"
    click LossStd "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/loss.py"
    click MLLoss "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/loss.py"
    click HeatStd "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/utils/heatmaps.py"
    click MLHeat "https://github.com/kimyeonghyeon/metalearning-echocardiogram/blob/main/meta_learning/utils/heatmaps.py"

    %% Styles
    classDef config fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef script fill:#1f77b4,stroke:#333,stroke-width:1px;
    classDef data fill:#2ca02c,stroke:#333,stroke-width:1px,shape:cylinder;
    classDef module fill:#aec7e8,stroke:#333,stroke-width:1px;
    classDef external fill:#9467bd,stroke:#333,stroke-width:1px,shape:cloud;
    classDef logs fill:#8c564b,stroke:#333,stroke-width:1px,shape:cylinder;
```
