# imedslab/adatriplet architecture

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

- Interactive diagram: https://gitdiagram.com/imedslab/adatriplet
- Repository: https://github.com/imedslab/adatriplet

## Overview

##### Project type and purpose
- AdaTriplet is a Python-based metric-learning library focused on learning embeddings from medical images using Triplet/AdaTriplet losses.
- It provides command-line scripts (`train.py`, `test.py`, `eval_ablation.py`) to run experiments on X-ray data (OAI, ChestX-ray14).

##### File structure
- Top-level scripts:
- `train.py`, `test.py`, `eval_ablation.py` – CLI entry points (Controller layer)
- `networks.py` – model definitions (Feature extraction networks)
- `config.yml`, `environment.yml` – configuration & dependency management
- Library code under `common/`:
- data handling (`data_loader.py`, `prepare_dataframe.py`, `split_train_test_data.py`, `parse_metadata.py`)
- image transforms (`image_transformation.py`)
- metric-learning core (`methods.py`, `main_loop.py`)
- losses (`losses/losses.py`)
- miners (hard/auto-margin sampling in `common/miners/`)
- distance metrics (`dist_metric.py`)
- evaluation (`evaluation_metrics/`, `evaluators.py`)
- utilities (`utilities/meters.py`, `utils.py`)
- Packaging: `setup.py` declares this as an installable package.

##### Extract Insights from the README
- Workflow: create conda env, `pip install -e .`, prepare datasets, then `python train.py …` or `python test.py …`.
- Eight methods are supported (AdaTriplet, Triplet, ArcFace, etc.).
- Outputs include performance tables and figures under `images/`.

##### Core Components & Their Interactions
a. Controller / CLI Layer
- Scripts parse command-line args and load `config.yml`
- Invoke the MainLoop from `common/main_loop.py`
b. Data Layer
- Raw Images + Metadata + DataFrame → DataLoader
- ImageTransformations apply cropping, resizing, augmentation
- `split_train_test_data.py` handles dataset partitioning
c. Model & Sampling Layer
- `networks.py` defines backbone CNNs or embedding networks
- Samplers (“miners”) select triplets (hard, auto-margin)
d. Loss & Metric Learning Layer
- Loss functions computed in `common/losses/losses.py`
- Methods (e.g., AdaTriplet) encapsulate loss + mining strategy
e. Training/Evaluation Loop
- `main_loop.py` orchestrates epochs: forward pass → compute loss → backward → update
- `evaluators.py` and `evaluation_metrics/` compute classification/ranking metrics
f. Visualization & Reporting
- Final tables and figures saved in `images/`

##### Architectural Patterns & Design Principles
- Modular pipeline: each concern (data, model, loss, evaluation) lives in its own namespace.
- Dependency Injection via the CLI + YAML config
- Plugin-style methods: new metric-learning methods can be registered via `common/methods.py`.
- Separation of concerns: miners, losses, metrics, and network architectures are decoupled.

##### Detailed Steps for the Engineer
1. Sketch a high-level pipeline: start from “User runs `train.py`” and end at “Results stored in images/”.
– From raw data store to DataLoader
– From DataLoader to Model + Miner + Loss
– From Loss back to Training Loop (optimizer)
– From Model outputs to Evaluator
– From Evaluator to Reporting/Visualization
– Rectangles for modules/packages
– Clouds for external systems
8. Every component from the file tree is represented or grouped logically.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Systems
    RawData(("Raw Images")):::db
    Metadata(("Metadata Store")):::db
    CondaEnv{{"Conda Env"}}:::external

    %% Controller / CLI Layer
    subgraph "Controller / CLI Layer"
        direction TB
        Train["train.py"]:::controller
        Test["test.py"]:::controller
        EvalAb["eval_ablation.py"]:::controller
        Config["config.yml"]:::config
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        ParseMeta["parse_metadata.py"]:::data
        PrepDF["prepare_dataframe.py"]:::data
        Split["split_train_test_data.py"]:::data
        Loader["data_loader.py"]:::data
        ImgTrans["image_transformation.py"]:::data
    end

    %% Model Layer
    subgraph "Model Layer"
        direction TB
        Nets["networks.py"]:::model
    end

    %% Loss & Sampling Layer
    subgraph "Loss & Sampling Layer"
        direction TB
        Losses["losses.py"]:::loss
        BaseMiner["base_miner.py"]:::loss
        TripletMiner["triplet_margin_miner.py"]:::loss
        AutoMarginMiner["triplet_automargin_miner.py"]:::loss
        Methods["methods.py"]:::loss
    end

    %% Distance Metrics
    Dist["dist_metric.py"]:::loss

    %% Training / Evaluation Loop
    subgraph "Training Loop"
        direction TB
        MainLoop["main_loop.py"]:::training
        EvaluatorMain["evaluators.py"]:::training
    end

    %% Evaluation Metrics
    subgraph "Evaluation Metrics"
        direction TB
        ClassEval["classification.py"]:::evaluation
        RankEval["ranking.py"]:::evaluation
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Meters["meters.py"]:::utility
        Utils["utils.py"]:::utility
    end

    %% Visualization & Reporting
    subgraph "Visualization / Reporting"
        direction TB
        Viz2D["loss_2Dsurface.py"]:::viz
        Images(("images/")):::db
    end

    %% Packaging
    subgraph "Packaging"
        direction TB
        Setup["setup.py"]:::pack
        EnvYml["environment.yml"]:::pack
    end

    %% Flow arrows
    CondaEnv -->|installs| Setup
    CondaEnv -->|env info| EnvYml
    Setup -->|package| Train
    Setup -->|package| Test
    Setup -->|package| EvalAb

    Train -->|loads config| Config
    Test -->|loads config| Config
    EvalAb -->|loads config| Config
    Config -->|injects into| MainLoop

    RawData --> ParseMeta
    Metadata --> ParseMeta
    ParseMeta --> PrepDF
    PrepDF --> Split
    Split --> Loader
    Loader --> ImgTrans
    ImgTrans --> Nets

    Nets --> Losses
    Nets --> BaseMiner
    Nets --> TripletMiner
    Nets --> AutoMarginMiner
    Losses --> Methods
    BaseMiner --> Methods
    TripletMiner --> Methods
    AutoMarginMiner --> Methods
    Dist --> Methods

    Nets --> MainLoop
    Methods --> MainLoop
    Dist --> MainLoop

    MainLoop --> EvaluatorMain
    EvaluatorMain --> ClassEval
    EvaluatorMain --> RankEval

    ClassEval --> Viz2D
    RankEval --> Viz2D
    Viz2D --> Images

    %% Utilities connections
    Meters --> MainLoop
    Utils --> MainLoop
    Utils --> EvaluatorMain
    Utils --> Loader
    Utils --> Methods

    %% Click Events
    click Train "https://github.com/imedslab/adatriplet/blob/main/train.py"
    click Test "https://github.com/imedslab/adatriplet/blob/main/test.py"
    click EvalAb "https://github.com/imedslab/adatriplet/blob/main/eval_ablation.py"
    click Config "https://github.com/imedslab/adatriplet/blob/main/config.yml"
    click ParseMeta "https://github.com/imedslab/adatriplet/blob/main/common/parse_metadata.py"
    click PrepDF "https://github.com/imedslab/adatriplet/blob/main/common/prepare_dataframe.py"
    click Split "https://github.com/imedslab/adatriplet/blob/main/common/split_train_test_data.py"
    click Loader "https://github.com/imedslab/adatriplet/blob/main/common/data_loader.py"
    click ImgTrans "https://github.com/imedslab/adatriplet/blob/main/common/image_transformation.py"
    click Nets "https://github.com/imedslab/adatriplet/blob/main/networks.py"
    click Losses "https://github.com/imedslab/adatriplet/blob/main/common/losses/losses.py"
    click BaseMiner "https://github.com/imedslab/adatriplet/blob/main/common/miners/base_miner.py"
    click TripletMiner "https://github.com/imedslab/adatriplet/blob/main/common/miners/triplet_margin_miner.py"
    click AutoMarginMiner "https://github.com/imedslab/adatriplet/blob/main/common/miners/triplet_automargin_miner.py"
    click Methods "https://github.com/imedslab/adatriplet/blob/main/common/methods.py"
    click Dist "https://github.com/imedslab/adatriplet/blob/main/common/dist_metric.py"
    click MainLoop "https://github.com/imedslab/adatriplet/blob/main/common/main_loop.py"
    click EvaluatorMain "https://github.com/imedslab/adatriplet/blob/main/common/evaluators.py"
    click ClassEval "https://github.com/imedslab/adatriplet/blob/main/common/evaluation_metrics/classification.py"
    click RankEval "https://github.com/imedslab/adatriplet/blob/main/common/evaluation_metrics/ranking.py"
    click Meters "https://github.com/imedslab/adatriplet/blob/main/common/utilities/meters.py"
    click Utils "https://github.com/imedslab/adatriplet/blob/main/common/utils.py"
    click Viz2D "https://github.com/imedslab/adatriplet/blob/main/visualize/loss_2Dsurface.py"
    click Images "https://github.com/imedslab/adatriplet/tree/main/images/"
    click Setup "https://github.com/imedslab/adatriplet/blob/main/setup.py"
    click EnvYml "https://github.com/imedslab/adatriplet/blob/main/environment.yml"

    %% Styles
    classDef external fill:#f9f,stroke:#333,stroke-width:1px
    classDef db fill:#ccf,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef controller fill:#ffeb99,stroke:#333,stroke-width:1px
    classDef config fill:#fff5b1,stroke:#333,stroke-width:1px
    classDef data fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef model fill:#d4edda,stroke:#333,stroke-width:1px
    classDef loss fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef training fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef evaluation fill:#f8d7da,stroke:#333,stroke-width:1px
    classDef utility fill:#eeeeee,stroke:#333,stroke-width:1px
    classDef viz fill:#f5c6cb,stroke:#333,stroke-width:1px
    classDef pack fill:#d6d8db,stroke:#333,stroke-width:1px
```
