# imoonlab/dhgformer architecture

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

- Interactive diagram: https://gitdiagram.com/imoonlab/dhgformer
- Repository: https://github.com/imoonlab/dhgformer

## Overview

DHGFormer is a brain-disorder diagnosis research application. Its documented run loads prepared ABIDE data, builds a dynamic hierarchical graph-transformer, and trains and evaluates it; the repository also includes ABIDE preprocessing and graph-data utilities. The graph follows only relationships visible in the excerpts, SOURCE INDEX, or README. Several model and preprocessing details are unsampled, so their internal relationships are omitted where not evidenced.

Main entry points: [`train.py`](https://github.com/imoonlab/dhgformer/blob/main/train.py) (Train and evaluate), [`main.py`](https://github.com/imoonlab/dhgformer/blob/main/main.py) (Run configuration), [`model/DHGFormer.py`](https://github.com/imoonlab/dhgformer/blob/main/model/DHGFormer.py) (DHGFormer), [`util/abide/01-fetch_data.py`](https://github.com/imoonlab/dhgformer/blob/main/util/abide/01-fetch_data.py) (Fetch ABIDE)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["ABIDE data"]
  node_abide_fetch["Fetch ABIDE<br/>[01-fetch_data.py]"]
  node_abide_process["Process ABIDE<br/>[02-process_data.py]"]
  node_abide_generate["Generate dataset"]
  node_preprocess["Connectivity preprocessing<br/>[preprocess_data.py]"]
  node_abide_dataset["ABIDE dataset reader<br/>[ABIDEDataset.py]"]
  node_parallel_reader["Parallel graph reader"]
  node_gdc["Graph diffusion<br/>[gdc.py]"]
end

subgraph group_runtime["Training runtime"]
  node_loader["Data loader<br/>[dataloader.py]"]
  node_entry["Run configuration<br/>[main.py]"]
  node_trainer["Train and evaluate<br/>[train.py]"]
end

subgraph group_modeling["Graph model"]
  node_model["DHGFormer<br/>[DHGFormer.py]"]
  node_encoder["FC transformer encoder<br/>[Encoder.py]"]
  node_graph_generator["Learnable graph generator<br/>[DHGFormer.py]"]
  node_hierarchy["Hierarchical prediction<br/>[DHGFormer.py]"]
end

subgraph group_support["Training support"]
  node_mixup["Mixup preprocessing<br/>[prepossess.py]"]
  node_loss["Training losses<br/>[loss.py]"]
  node_metrics["Metrics and meters<br/>[meter.py]"]
  node_logger["Logging<br/>[logger.py]"]
end

node_researcher(("Researcher"))
node_dataset_source(("ABIDE download"))

node_dataset_source -->|"provides data"| node_abide_fetch
node_abide_fetch -.->|"prepares files"| node_abide_process
node_abide_process -.->|"builds dataset"| node_abide_generate
node_abide_fetch -->|"uses preprocessing"| node_preprocess
node_abide_process -->|"uses preprocessing"| node_preprocess
node_abide_dataset -->|"reads graph data"| node_parallel_reader
node_parallel_reader -->|"applies diffusion"| node_gdc
node_researcher -->|"starts training"| node_entry
node_entry -->|"initializes data"| node_loader
node_entry -->|"constructs model"| node_model
node_entry -->|"starts training"| node_trainer
node_loader -->|"supplies batches"| node_trainer
node_trainer -->|"runs forward pass"| node_model
node_model -->|"encodes time series"| node_encoder
node_model -.->|"generates graph"| node_graph_generator
node_model -.->|"predicts from graph"| node_hierarchy
node_trainer -->|"mixes training batches"| node_mixup
node_trainer -->|"computes auxiliary loss"| node_loss
node_trainer -->|"updates metrics"| node_metrics
node_trainer -->|"logs progress"| node_logger
node_entry -->|"logs run"| node_logger

click node_abide_fetch "https://github.com/imoonlab/dhgformer/blob/main/util/abide/01-fetch_data.py"
click node_abide_process "https://github.com/imoonlab/dhgformer/blob/main/util/abide/02-process_data.py"
click node_abide_generate "https://github.com/imoonlab/dhgformer/blob/main/util/abide/03-generate_abide_dataset.py"
click node_preprocess "https://github.com/imoonlab/dhgformer/blob/main/imports/preprocess_data.py"
click node_abide_dataset "https://github.com/imoonlab/dhgformer/blob/main/imports/ABIDEDataset.py"
click node_parallel_reader "https://github.com/imoonlab/dhgformer/blob/main/imports/read_abide_stats_parall.py"
click node_gdc "https://github.com/imoonlab/dhgformer/blob/main/imports/gdc.py"
click node_loader "https://github.com/imoonlab/dhgformer/blob/main/dataloader.py"
click node_entry "https://github.com/imoonlab/dhgformer/blob/main/main.py"
click node_trainer "https://github.com/imoonlab/dhgformer/blob/main/train.py"
click node_model "https://github.com/imoonlab/dhgformer/blob/main/model/DHGFormer.py"
click node_encoder "https://github.com/imoonlab/dhgformer/blob/main/model/Encoder.py"
click node_graph_generator "https://github.com/imoonlab/dhgformer/blob/main/model/DHGFormer.py"
click node_hierarchy "https://github.com/imoonlab/dhgformer/blob/main/model/DHGFormer.py"
click node_mixup "https://github.com/imoonlab/dhgformer/blob/main/util/prepossess.py"
click node_loss "https://github.com/imoonlab/dhgformer/blob/main/util/loss.py"
click node_metrics "https://github.com/imoonlab/dhgformer/blob/main/util/meter.py"
click node_logger "https://github.com/imoonlab/dhgformer/blob/main/util/logger.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_abide_fetch,node_abide_process,node_abide_generate,node_preprocess,node_abide_dataset,node_parallel_reader,node_gdc toneBlue
class node_loader,node_entry,node_trainer toneAmber
class node_model,node_encoder,node_graph_generator,node_hierarchy toneMint
class node_mixup,node_loss,node_metrics,node_logger toneRose
class node_researcher,node_dataset_source toneIndigo
```

## Components

### ABIDE data

- [Fetch ABIDE](https://github.com/imoonlab/dhgformer/blob/main/util/abide/01-fetch_data.py): `util/abide/01-fetch_data.py`
- [Process ABIDE](https://github.com/imoonlab/dhgformer/blob/main/util/abide/02-process_data.py): `util/abide/02-process_data.py`
- [Generate dataset](https://github.com/imoonlab/dhgformer/blob/main/util/abide/03-generate_abide_dataset.py): `util/abide/03-generate_abide_dataset.py`
- [Connectivity preprocessing](https://github.com/imoonlab/dhgformer/blob/main/imports/preprocess_data.py): `imports/preprocess_data.py`
- [ABIDE dataset reader](https://github.com/imoonlab/dhgformer/blob/main/imports/ABIDEDataset.py): `imports/ABIDEDataset.py`
- [Parallel graph reader](https://github.com/imoonlab/dhgformer/blob/main/imports/read_abide_stats_parall.py): `imports/read_abide_stats_parall.py`
- [Graph diffusion](https://github.com/imoonlab/dhgformer/blob/main/imports/gdc.py): `imports/gdc.py`

### Training runtime

- [Data loader](https://github.com/imoonlab/dhgformer/blob/main/dataloader.py): `dataloader.py`
- [Run configuration](https://github.com/imoonlab/dhgformer/blob/main/main.py): `main.py`
- [Train and evaluate](https://github.com/imoonlab/dhgformer/blob/main/train.py): `train.py`

### Graph model

- [DHGFormer](https://github.com/imoonlab/dhgformer/blob/main/model/DHGFormer.py): `model/DHGFormer.py`
- [FC transformer encoder](https://github.com/imoonlab/dhgformer/blob/main/model/Encoder.py): `model/Encoder.py`
- [Learnable graph generator](https://github.com/imoonlab/dhgformer/blob/main/model/DHGFormer.py): `model/DHGFormer.py`
- [Hierarchical prediction](https://github.com/imoonlab/dhgformer/blob/main/model/DHGFormer.py): `model/DHGFormer.py`

### Training support

- [Mixup preprocessing](https://github.com/imoonlab/dhgformer/blob/main/util/prepossess.py): `util/prepossess.py`
- [Training losses](https://github.com/imoonlab/dhgformer/blob/main/util/loss.py): `util/loss.py`
- [Metrics and meters](https://github.com/imoonlab/dhgformer/blob/main/util/meter.py): `util/meter.py`
- [Logging](https://github.com/imoonlab/dhgformer/blob/main/util/logger.py): `util/logger.py`

### Other components

- **Researcher**
- **ABIDE download**

## Connections

- ABIDE download → Fetch ABIDE: provides data (evidence: `README.md`)
- Fetch ABIDE → Process ABIDE: prepares files
- Process ABIDE → Generate dataset: builds dataset
- Fetch ABIDE → Connectivity preprocessing: uses preprocessing (evidence: `util/abide/01-fetch_data.py`)
- Process ABIDE → Connectivity preprocessing: uses preprocessing (evidence: `util/abide/02-process_data.py`)
- ABIDE dataset reader → Parallel graph reader: reads graph data (evidence: `imports/ABIDEDataset.py`)
- Parallel graph reader → Graph diffusion: applies diffusion (evidence: `imports/read_abide_stats_parall.py`)
- Researcher → Run configuration: starts training (evidence: `README.md`)
- Run configuration → Data loader: initializes data (evidence: `main.py`)
- Run configuration → DHGFormer: constructs model (evidence: `main.py`)
- Run configuration → Train and evaluate: starts training (evidence: `main.py`)
- Data loader → Train and evaluate: supplies batches (evidence: `main.py`)
- Train and evaluate → DHGFormer: runs forward pass (evidence: `train.py`)
- DHGFormer → FC transformer encoder: encodes time series (evidence: `model/DHGFormer.py`)
- DHGFormer → Learnable graph generator: generates graph (evidence: `model/DHGFormer.py`)
- DHGFormer → Hierarchical prediction: predicts from graph (evidence: `model/DHGFormer.py`)
- Train and evaluate → Mixup preprocessing: mixes training batches (evidence: `train.py`)
- Train and evaluate → Training losses: computes auxiliary loss (evidence: `train.py`)
- Train and evaluate → Metrics and meters: updates metrics
- Train and evaluate → Logging: logs progress
- Run configuration → Logging: logs run (evidence: `main.py`)
