# khao0/hida-baa architecture

> Architecture diagram of the GitHub repository khao0/hida-baa, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/khao0/hida-baa
- Repository: https://github.com/khao0/hida-baa

## Overview

HiDA-BAA adapts a provided source model to a researcher’s preprocessed target-domain hand X-rays, then predicts continuous bone age using image and sex inputs. Training reads annotations, creates age-and-sex-stratified folds, warms up the regression head, fine-tunes the backbone, evaluates folds, and saves adapted models and metrics. Separate documented workflows support single-image inference and test-folder re-evaluation. Preprocessing is external; the re-evaluation implementation was not sampled, so its internal wiring is omitted.

Main entry points: [`hida_baa/trainers/train.py`](https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/train.py) (Fold Trainer), [`hida_baa/models/load_source_model.py`](https://github.com/khao0/hida-baa/blob/main/hida_baa/models/load_source_model.py) (Source Model Loader), [`scripts/inference.py`](https://github.com/khao0/hida-baa/blob/main/scripts/inference.py) (Inference CLI), [`hida_baa/predict.py`](https://github.com/khao0/hida-baa/blob/main/hida_baa/predict.py) (Prediction Functions)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_adaptation["Target Adaptation"]
  node_train_cli["Training CLI<br/>[train.py]"]
  node_trainer["Fold Trainer<br/>[train.py]"]
  node_warmup["Head Warm-up<br/>[train.py]"]
  node_finetune["Backbone Fine-tuning<br/>[train.py]"]
  node_source_loader["Source Model Loader"]
  node_source_checkpoint["Source Checkpoint"]
  node_adapted_checkpoint["Adapted Models"]
  node_training_outputs["Training Metrics<br/>[utils.py]"]
end

subgraph group_data["Dataset Handling"]
  node_dataset["Dataset Loader"]
  node_annotations["Train and Test CSVs"]
end

subgraph group_prediction["Prediction and Evaluation"]
  node_inference_cli["Inference CLI<br/>[inference.py]"]
  node_predict["Prediction Functions<br/>[predict.py]"]
  node_reevaluate_cli["Re-evaluation CLI<br/>[test.py]"]
  node_evaluation["Training Evaluation<br/>[utils.py]"]
  node_prediction_result["Bone Age Prediction"]
end

subgraph group_integrations["External Inputs"]
  node_hf["Hugging Face"]
  node_xray_data["Preprocessed X-rays"]
  node_preprocessing["Hand X-ray Preprocessing"]
end

node_researcher(("Researcher"))

node_researcher -->|"starts training"| node_train_cli
node_train_cli -->|"runs"| node_trainer
node_trainer -->|"loads and splits"| node_dataset
node_annotations -->|"provides metadata"| node_dataset
node_xray_data -->|"provides images"| node_dataset
node_researcher -.->|"prepares images"| node_preprocessing
node_preprocessing -.->|"produces 600x600"| node_xray_data
node_trainer -->|"loads each fold"| node_source_loader
node_source_loader -->|"checks local"| node_source_checkpoint
node_source_loader -.->|"downloads if absent"| node_hf
node_trainer -->|"trains frozen backbone"| node_warmup
node_trainer -->|"fine-tunes upper layers"| node_finetune
node_trainer -->|"saves fold models"| node_adapted_checkpoint
node_trainer -->|"evaluates test folds"| node_evaluation
node_evaluation -->|"writes metrics"| node_training_outputs
node_researcher -->|"requests prediction"| node_inference_cli
node_inference_cli -->|"calls"| node_predict
node_inference_cli -->|"selects model"| node_adapted_checkpoint
node_predict -->|"reads image"| node_xray_data
node_predict -->|"returns age"| node_prediction_result
node_researcher -->|"requests re-evaluation"| node_reevaluate_cli
node_reevaluate_cli -->|"uses test metadata"| node_annotations
node_reevaluate_cli -->|"selects model"| node_adapted_checkpoint

click node_train_cli "https://github.com/khao0/hida-baa/blob/main/scripts/train.py"
click node_trainer "https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/train.py"
click node_warmup "https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/train.py"
click node_finetune "https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/train.py"
click node_source_loader "https://github.com/khao0/hida-baa/blob/main/hida_baa/models/load_source_model.py"
click node_source_checkpoint "https://github.com/khao0/hida-baa/tree/main/checkpoints/SourceModel"
click node_adapted_checkpoint "https://github.com/khao0/hida-baa/tree/main/checkpoints/AdaptedModel"
click node_training_outputs "https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/utils.py"
click node_dataset "https://github.com/khao0/hida-baa/blob/main/hida_baa/datasets/bone_age_dataset.py"
click node_annotations "https://github.com/khao0/hida-baa/tree/main/data"
click node_inference_cli "https://github.com/khao0/hida-baa/blob/main/scripts/inference.py"
click node_predict "https://github.com/khao0/hida-baa/blob/main/hida_baa/predict.py"
click node_reevaluate_cli "https://github.com/khao0/hida-baa/blob/main/scripts/test.py"
click node_evaluation "https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/utils.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_train_cli,node_trainer,node_warmup,node_finetune,node_source_loader,node_source_checkpoint,node_adapted_checkpoint,node_training_outputs toneBlue
class node_dataset,node_annotations toneAmber
class node_inference_cli,node_predict,node_reevaluate_cli,node_evaluation,node_prediction_result toneMint
class node_hf,node_xray_data,node_preprocessing toneRose
class node_researcher toneIndigo
```

## Components

### Target Adaptation

- [Training CLI](https://github.com/khao0/hida-baa/blob/main/scripts/train.py): `scripts/train.py`
- [Fold Trainer](https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/train.py): `hida_baa/trainers/train.py`
- [Head Warm-up](https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/train.py): `hida_baa/trainers/train.py`
- [Backbone Fine-tuning](https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/train.py): `hida_baa/trainers/train.py`
- [Source Model Loader](https://github.com/khao0/hida-baa/blob/main/hida_baa/models/load_source_model.py): `hida_baa/models/load_source_model.py`
- [Source Checkpoint](https://github.com/khao0/hida-baa/tree/main/checkpoints/SourceModel): `checkpoints/SourceModel`
- [Adapted Models](https://github.com/khao0/hida-baa/tree/main/checkpoints/AdaptedModel): `checkpoints/AdaptedModel`
- [Training Metrics](https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/utils.py): `hida_baa/trainers/utils.py`

### Dataset Handling

- [Dataset Loader](https://github.com/khao0/hida-baa/blob/main/hida_baa/datasets/bone_age_dataset.py): `hida_baa/datasets/bone_age_dataset.py`
- [Train and Test CSVs](https://github.com/khao0/hida-baa/tree/main/data): `data`

### Prediction and Evaluation

- [Inference CLI](https://github.com/khao0/hida-baa/blob/main/scripts/inference.py): `scripts/inference.py`
- [Prediction Functions](https://github.com/khao0/hida-baa/blob/main/hida_baa/predict.py): `hida_baa/predict.py`
- [Re-evaluation CLI](https://github.com/khao0/hida-baa/blob/main/scripts/test.py): `scripts/test.py`
- [Training Evaluation](https://github.com/khao0/hida-baa/blob/main/hida_baa/trainers/utils.py): `hida_baa/trainers/utils.py`
- **Bone Age Prediction**

### External Inputs

- **Hugging Face**
- **Preprocessed X-rays**
- **Hand X-ray Preprocessing**

### Other components

- **Researcher**

## Connections

- Researcher → Training CLI: starts training
- Training CLI → Fold Trainer: runs
- Fold Trainer → Dataset Loader: loads and splits
- Train and Test CSVs → Dataset Loader: provides metadata
- Preprocessed X-rays → Dataset Loader: provides images
- Researcher → Hand X-ray Preprocessing: prepares images
- Hand X-ray Preprocessing → Preprocessed X-rays: produces 600x600
- Fold Trainer → Source Model Loader: loads each fold
- Source Model Loader → Source Checkpoint: checks local
- Source Model Loader → Hugging Face: downloads if absent
- Fold Trainer → Head Warm-up: trains frozen backbone
- Fold Trainer → Backbone Fine-tuning: fine-tunes upper layers
- Fold Trainer → Adapted Models: saves fold models
- Fold Trainer → Training Evaluation: evaluates test folds
- Training Evaluation → Training Metrics: writes metrics
- Researcher → Inference CLI: requests prediction
- Inference CLI → Prediction Functions: calls
- Inference CLI → Adapted Models: selects model
- Prediction Functions → Preprocessed X-rays: reads image
- Prediction Functions → Bone Age Prediction: returns age
- Researcher → Re-evaluation CLI: requests re-evaluation
- Re-evaluation CLI → Train and Test CSVs: uses test metadata
- Re-evaluation CLI → Adapted Models: selects model