# yongkyung-oh/taod-net architecture

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

- Interactive diagram: https://gitdiagram.com/yongkyung-oh/taod-net
- Repository: https://github.com/yongkyung-oh/taod-net

## Overview

##### Project type and purpose
- This is an ML research codebase (PyTorch) for TAOD-Net, a transformer-based multi-label image classification system that detects key inflammatory signs of Thyroid-Associated Orbitopathy (TAO) in facial imagery.
- It leverages domain-knowledge cropping, a two-stage training strategy (pretraining + fine-tuning), and custom loss functions to standardize TAO diagnosis.

##### File structure
- Top level:
- assets/     – static images (e.g., “overview_new.png”) for documentation
- experiments/– CLI entrypoints for experiments
– binary.py       (baseline multi-label classification)
– pretraining.py  (pretraining phase)
– model_run.py    (combined, multi, and binary training & evaluation)
- src/         – core library modules
– utils.py   (data I/O, preprocessing, cropping)
– model.py   (TAOD-Net architecture based on ViT)
– losses.py  (custom multi-label loss definitions)
- Configuration and metadata: .gitignore, LICENSE, README.md

##### README for additional insights
- Confirms two-stage training and domain-knowledge cropping
- Specifies that the core model is a Vision Transformer (ViT) backbone with custom heads
- Describes data (2,040 anonymized images) and evaluation modalities

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data Tier
    subgraph "Data Tier"
        direction TB
        RawImages["Raw Facial Images Storage"]:::data
    end

    %% Preprocessing Tier
    subgraph "Preprocessing Tier"
        direction TB
        Preprocessing["Cropper (utils.py)"]:::preprocess
        Dataloader["DataLoader"]:::preprocess
    end

    %% Model & Loss Tier
    subgraph "Model & Loss Tier"
        direction TB
        Model["TAOD-Net (model.py)"]:::model
        Loss["Custom Losses (losses.py)"]:::loss
        Backprop["Backpropagation"]:::model
    end

    %% Orchestration Tier
    subgraph "Orchestration Tier"
        direction TB
        BinaryScript["Baseline Binary Experiment (binary.py)"]:::orchestrator
        PretrainScript["Pretraining Script (pretraining.py)"]:::orchestrator
        ModelRunScript["Combined Training & Eval (model_run.py)"]:::orchestrator
    end

    %% Output Tier
    subgraph "Output Tier"
        direction TB
        Checkpoints["Model Checkpoints"]:::output
        Metrics["Metrics & Plots"]:::output
    end

    %% Metadata & Docs
    subgraph "Metadata & Documentation"
        direction TB
        Assets["Static Assets (assets/)"]:::docs
        READMEnode["README.md"]:::docs
        LICENSEnode["LICENSE"]:::docs
        Gitignore[".gitignore"]:::docs
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        PyTorch["PyTorch & torchvision"]:::external
        Transformers["Hugging Face ViT"]:::external
        SciStack["numpy, pandas"]:::external
    end

    %% Connections
    RawImages --> Preprocessing
    Preprocessing --> Dataloader
    Dataloader --> Model
    Model --> Loss
    Loss --> Backprop
    Backprop -.-> Model
    Model --> Checkpoints
    Model --> Metrics

    BinaryScript -->|"loads data"| Dataloader
    BinaryScript -->|"instantiates model"| Model
    BinaryScript -->|"applies loss"| Loss
    BinaryScript -->|"saves checkpoint"| Checkpoints
    BinaryScript -->|"generates metrics"| Metrics

    PretrainScript -->|"loads data"| Dataloader
    PretrainScript -->|"instantiates model"| Model
    PretrainScript -->|"applies loss"| Loss
    PretrainScript -->|"saves checkpoint"| Checkpoints
    PretrainScript -->|"generates metrics"| Metrics

    ModelRunScript -->|"loads data"| Dataloader
    ModelRunScript -->|"instantiates model"| Model
    ModelRunScript -->|"applies loss"| Loss
    ModelRunScript -->|"saves checkpoint"| Checkpoints
    ModelRunScript -->|"generates metrics"| Metrics

    BinaryScript --> PyTorch
    PretrainScript --> PyTorch
    ModelRunScript --> PyTorch
    Model --> Transformers
    Preprocessing --> SciStack

    %% Click Events
    click Preprocessing "https://github.com/yongkyung-oh/taod-net/blob/main/src/utils.py"
    click Model "https://github.com/yongkyung-oh/taod-net/blob/main/src/model.py"
    click Loss "https://github.com/yongkyung-oh/taod-net/blob/main/src/losses.py"
    click BinaryScript "https://github.com/yongkyung-oh/taod-net/blob/main/experiments/binary.py"
    click PretrainScript "https://github.com/yongkyung-oh/taod-net/blob/main/experiments/pretraining.py"
    click ModelRunScript "https://github.com/yongkyung-oh/taod-net/blob/main/experiments/model_run.py"
    click Assets "https://github.com/yongkyung-oh/taod-net/tree/main/assets/"
    click READMEnode "https://github.com/yongkyung-oh/taod-net/blob/main/README.md"
    click LICENSEnode "https://github.com/yongkyung-oh/taod-net/tree/main/LICENSE"
    click Gitignore "https://github.com/yongkyung-oh/taod-net/blob/main/.gitignore"

    %% Styles
    classDef data fill:#B3E5FC,stroke:#0277BD,color:#000
    classDef preprocess fill:#C8E6C9,stroke:#2E7D32,color:#000
    classDef model fill:#D1C4E9,stroke:#6A1B9A,color:#000
    classDef loss fill:#F8BBD0,stroke:#AD1457,color:#000
    classDef orchestrator fill:#FFE0B2,stroke:#EF6C00,color:#000
    classDef output fill:#FFCCBC,stroke:#BF360C,color:#000
    classDef docs fill:#E0E0E0,stroke:#424242,color:#000
    classDef external fill:#FFF9C4,stroke:#F9A825,color:#000
```
