# cardio-ai/fedkd-for-cardiac-ct architecture

> Architecture diagram of the GitHub repository cardio-ai/fedkd-for-cardiac-ct, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-01-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cardio-ai/fedkd-for-cardiac-ct
- Repository: https://github.com/cardio-ai/fedkd-for-cardiac-ct

## Overview

Key Components to Include:

##### Data Flow and Processing Layer
- Input Layer
- Local CT scan data storage
- Partial label annotations per hospital

##### Federated Learning Architecture
- Local Training Components
- CNN Models (Task-specific)
- Knowledge Distillation Pipeline
- Local Data Preprocessing (reference src/data/transforms.py)

- Global Aggregation Layer
- Model Parameter Aggregation
- Federation Coordinator
- Global Model Updates

##### Model Architecture
- Primary Components
- SWIN-UNETR Transformer (src/models/multihead_swinunetr.py)
- UNet Implementation (src/models/nnunet.py)
- Multi-head Architecture for Different Tasks
- Hinge Points Detection
- Coronary Ostias Detection
- Membranous Septum Detection
- Calcification Detection

##### Training Pipeline
- Knowledge Distillation Flow
- Task-specific CNN Training
- Transformer Learning from CNN Predictions
- Semi-supervised Learning Component
- Model Conditioning Options (segmentation-based)

Important Elements to Highlight:

##### Two-Step Semi-Supervised Strategy
- Clear separation between CNN prediction phase
- Knowledge distillation to transformer phase

##### Multi-Task Learning
- How different tasks are handled by separate heads
- Connection to partial labels from different hospitals

##### Privacy Preservation
- Model parameter sharing instead of raw data
- Local computation boundaries

##### Evaluation Flow
- Testing paths for both global and local updates
- Validation pipeline

- Brief descriptions of key components
- Important file references

Additional Notes:
- Keep the federation topology clear and central
- Knowledge distillation pipeline
- Clear boundaries between local and global operations
- Reference to key configuration files (env.yml)
- Integration points for physiological constraints (src/physiological_constraints)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Legend
        direction TB
        L_Data[Data Storage]:::data
        L_Process[Processing Component]:::process
        L_Model[Model Component]:::model
        L_Fed[Federation Component]:::federation
        L_Infra[Infrastructure]:::infra
    end

    subgraph "Hospital Federation"
        direction TB
        subgraph "Hospital 1"
            H1_Data[(Local CT Scans)]:::data
            H1_Labels[(Partial Labels)]:::data
            H1_CNN[Local CNN Model]:::model
            H1_Process["Local Processing"]:::process
            click H1_Process "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/src/data/transforms.py"
        end

        subgraph "Hospital N"
            HN_Data[(Local CT Scans)]:::data
            HN_Labels[(Partial Labels)]:::data
            HN_CNN[Local CNN Model]:::model
            HN_Process["Local Processing"]:::process
        end
    end

    subgraph "Federated Learning Core"
        direction TB
        FedCoord{{"Federation Coordinator"}}:::federation
        click FedCoord "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/federated.py"
        ModelAgg{{"Model Aggregation"}}:::federation
        click ModelAgg "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/train_federated.py"
        GlobalEval["Global Evaluation"]:::process
        click GlobalEval "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/notebooks/eval_federated.ipynb"
    end

    subgraph "Model Architecture"
        direction TB
        SWIN["SWIN-UNETR Transformer"]:::model
        click SWIN "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/src/models/multihead_swinunetr.py"
        UNET["UNet Implementation"]:::model
        click UNET "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/src/models/nnunet.py"
        
        subgraph "Multi-head Tasks"
            direction TB
            Head1["Hinge Points"]:::model
            Head2["Coronary Ostias"]:::model
            Head3["Membranous Septum"]:::model
            Head4["Calcification"]:::model
        end
    end

    subgraph "Processing Pipeline"
        direction TB
        DataPrep["Data Preprocessing"]:::process
        click DataPrep "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/preprocess_federated_heart_ts.py"
        Transform["Data Transforms"]:::process
        click Transform "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/src/data/transforms.py"
        PhysConstraints["Physiological Constraints"]:::process
        click PhysConstraints "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/src/physiological_constraints/slicer_centerline_extraction.py"
        TAVIPredict["TAVI Predictor"]:::process
        click TAVIPredict "https://github.com/Cardio-AI/FedKD-for-Cardiac-CT/blob/main/tavi_predictor.py"
    end

    %% Connections
    H1_Data --> H1_Process
    H1_Labels --> H1_Process
    H1_Process --> H1_CNN
    HN_Data --> HN_Process
    HN_Labels --> HN_Process
    HN_Process --> HN_CNN

    H1_CNN -.-> ModelAgg
    HN_CNN -.-> ModelAgg
    ModelAgg --> FedCoord
    FedCoord --> GlobalEval

    FedCoord --> SWIN
    FedCoord --> UNET
    
    SWIN --> Head1
    SWIN --> Head2
    SWIN --> Head3
    SWIN --> Head4

    DataPrep --> Transform
    Transform --> H1_Process
    Transform --> HN_Process
    PhysConstraints --> TAVIPredict

    %% Styles
    classDef data fill:#3498db,stroke:#2980b9,color:white
    classDef process fill:#2ecc71,stroke:#27ae60,color:white
    classDef model fill:#e67e22,stroke:#d35400,color:white
    classDef federation fill:#9b59b6,stroke:#8e44ad,color:white
    classDef infra fill:#95a5a6,stroke:#7f8c8d,color:white
```
