# stefan-gustafsson-work/omi architecture

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

- Interactive diagram: https://gitdiagram.com/stefan-gustafsson-work/omi
- Repository: https://github.com/stefan-gustafsson-work/omi

## Overview

This repository implements an OMI ECG prediction research workflow: prepare cohort labels and ECG inputs, train/validate a ResNet model, evaluate external and held-out sets, then generate results tables and figures. The README documents SwED/PTB-XL preparation, Brazil prediction evaluation and reporting capabilities; these script-level branches are shown at directory or exact script paths where available. Source excerpts establish Python data conversion and model interactions; unsampled R and shell implementations are not inferred beyond the documented workflow.

Main entry points: [`model/main.py`](https://github.com/stefan-gustafsson-work/omi/blob/main/model/main.py) (Training orchestration), [`model/model.py`](https://github.com/stefan-gustafsson-work/omi/blob/main/model/model.py) (ECG model), [`generate_hdf5.py`](https://github.com/stefan-gustafsson-work/omi/blob/main/generate_hdf5.py) (ECG HDF5 builder), [`02.02-build-omi-hdf5.sh`](https://github.com/stefan-gustafsson-work/omi/blob/main/02.02-build-omi-hdf5.sh) (SwED HDF5 prep)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["Study preparation"]
  node_popdef["Study population"]
  node_ecgprep["ECG normalization<br/>[ecg_processing.py]"]
  node_hdfbuild["ECG HDF5 builder<br/>[generate_hdf5.py]"]
  node_hdfscript["SwED HDF5 prep"]
end

subgraph group_modeling["Modeling"]
  node_training["Training orchestration<br/>[main.py]"]
  node_dataset["OMI dataset loader<br/>[dataloader.py]"]
  node_ecgmodel["ECG model<br/>[model.py]"]
  node_resnet["Residual network<br/>[resnet.py]"]
  node_agesex["Age-sex encoding"]
  node_predictor["Prediction stage"]
  node_trainruns["Train and validate<br/>[03.01-train.sh]"]
  node_hpsearch["Hyperparameter search"]
  node_seedruns["Seed sensitivity"]
end

subgraph group_evaluation["Evaluation"]
  node_metrics["Discrimination metrics<br/>[metrics.py]"]
  node_swedtest["SwED test evaluation"]
  node_addvars["Additional variables"]
  node_brazil["Brazil prediction"]
  node_evalbrazil["Brazil evaluation"]
  node_evaltest["Test evaluation"]
end

subgraph group_reporting["Reporting"]
  node_tables["Results tables"]
  node_figures["Additional figures"]
  node_heatmap["Coronary heatmap"]
end

node_researcher(("Researcher"))

node_researcher -->|"defines cohort"| node_popdef
node_researcher -->|"prepares ECGs"| node_hdfscript
node_hdfscript -.->|"builds HDF5"| node_hdfbuild
node_hdfbuild -->|"normalizes traces"| node_ecgprep
node_researcher -->|"starts training"| node_trainruns
node_trainruns -.->|"invokes model"| node_training
node_training -->|"loads batches"| node_dataset
node_training -->|"trains and tests"| node_ecgmodel
node_training -->|"computes metrics"| node_metrics
node_ecgmodel -->|"encodes ECG"| node_resnet
node_ecgmodel -->|"encodes demographics"| node_agesex
node_ecgmodel -->|"produces logits"| node_predictor
node_researcher -->|"tunes model"| node_hpsearch
node_researcher -->|"repeats training"| node_seedruns
node_researcher -->|"tests model"| node_swedtest
node_swedtest -.->|"runs evaluation"| node_training
node_researcher -->|"predicts externally"| node_brazil
node_brazil -->|"evaluates predictions"| node_evalbrazil
node_researcher -->|"adds covariates"| node_addvars
node_researcher -->|"evaluates test set"| node_evaltest
node_evaltest -.->|"summarizes results"| node_tables
node_researcher -->|"creates tables"| node_tables
node_researcher -->|"creates figures"| node_figures
node_researcher -->|"maps coronary sites"| node_heatmap

click node_popdef "https://github.com/stefan-gustafsson-work/omi/blob/main/02.01-define-study-pop.R"
click node_ecgprep "https://github.com/stefan-gustafsson-work/omi/blob/main/ecg_processing.py"
click node_hdfbuild "https://github.com/stefan-gustafsson-work/omi/blob/main/generate_hdf5.py"
click node_hdfscript "https://github.com/stefan-gustafsson-work/omi/blob/main/02.02-build-omi-hdf5.sh"
click node_training "https://github.com/stefan-gustafsson-work/omi/blob/main/model/main.py"
click node_dataset "https://github.com/stefan-gustafsson-work/omi/blob/main/model/dataloader.py"
click node_ecgmodel "https://github.com/stefan-gustafsson-work/omi/blob/main/model/model.py"
click node_resnet "https://github.com/stefan-gustafsson-work/omi/blob/main/model/resnet.py"
click node_agesex "https://github.com/stefan-gustafsson-work/omi/blob/main/model/age_sex_encoding.py"
click node_predictor "https://github.com/stefan-gustafsson-work/omi/blob/main/model/prediction_stage.py"
click node_trainruns "https://github.com/stefan-gustafsson-work/omi/blob/main/03.01-train.sh"
click node_hpsearch "https://github.com/stefan-gustafsson-work/omi/blob/main/03.02-hp-search-validation.sh"
click node_seedruns "https://github.com/stefan-gustafsson-work/omi/blob/main/03.04-train-with-different-seeds.sh"
click node_metrics "https://github.com/stefan-gustafsson-work/omi/blob/main/model/metrics.py"
click node_swedtest "https://github.com/stefan-gustafsson-work/omi/blob/main/04.01-test-model-swed.sh"
click node_addvars "https://github.com/stefan-gustafsson-work/omi/blob/main/04.02-add-additional-variables.R"
click node_brazil "https://github.com/stefan-gustafsson-work/omi/blob/main/01.01-predict-from-brazil-model.sh"
click node_evalbrazil "https://github.com/stefan-gustafsson-work/omi/blob/main/01.02-eval-prediction-results-brazil-model.R"
click node_evaltest "https://github.com/stefan-gustafsson-work/omi/blob/main/04.03-eval-test-swed.R"
click node_tables "https://github.com/stefan-gustafsson-work/omi/blob/main/05.01-numbers-and-tables.R"
click node_figures "https://github.com/stefan-gustafsson-work/omi/blob/main/05.02-additional-figures.R"
click node_heatmap "https://github.com/stefan-gustafsson-work/omi/blob/main/05.03-coronary-heatmap.R"

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_popdef,node_ecgprep,node_hdfbuild,node_hdfscript toneBlue
class node_training,node_dataset,node_ecgmodel,node_resnet,node_agesex,node_predictor,node_trainruns,node_hpsearch,node_seedruns toneAmber
class node_metrics,node_swedtest,node_addvars,node_brazil,node_evalbrazil,node_evaltest toneMint
class node_tables,node_figures,node_heatmap toneRose
class node_researcher toneIndigo
```

## Components

### Study preparation

- [Study population](https://github.com/stefan-gustafsson-work/omi/blob/main/02.01-define-study-pop.R): `02.01-define-study-pop.R`
- [ECG normalization](https://github.com/stefan-gustafsson-work/omi/blob/main/ecg_processing.py): `ecg_processing.py`
- [ECG HDF5 builder](https://github.com/stefan-gustafsson-work/omi/blob/main/generate_hdf5.py): `generate_hdf5.py`
- [SwED HDF5 prep](https://github.com/stefan-gustafsson-work/omi/blob/main/02.02-build-omi-hdf5.sh): `02.02-build-omi-hdf5.sh`

### Modeling

- [Training orchestration](https://github.com/stefan-gustafsson-work/omi/blob/main/model/main.py): `model/main.py`
- [OMI dataset loader](https://github.com/stefan-gustafsson-work/omi/blob/main/model/dataloader.py): `model/dataloader.py`
- [ECG model](https://github.com/stefan-gustafsson-work/omi/blob/main/model/model.py): `model/model.py`
- [Residual network](https://github.com/stefan-gustafsson-work/omi/blob/main/model/resnet.py): `model/resnet.py`
- [Age-sex encoding](https://github.com/stefan-gustafsson-work/omi/blob/main/model/age_sex_encoding.py): `model/age_sex_encoding.py`
- [Prediction stage](https://github.com/stefan-gustafsson-work/omi/blob/main/model/prediction_stage.py): `model/prediction_stage.py`
- [Train and validate](https://github.com/stefan-gustafsson-work/omi/blob/main/03.01-train.sh): `03.01-train.sh`
- [Hyperparameter search](https://github.com/stefan-gustafsson-work/omi/blob/main/03.02-hp-search-validation.sh): `03.02-hp-search-validation.sh`
- [Seed sensitivity](https://github.com/stefan-gustafsson-work/omi/blob/main/03.04-train-with-different-seeds.sh): `03.04-train-with-different-seeds.sh`

### Evaluation

- [Discrimination metrics](https://github.com/stefan-gustafsson-work/omi/blob/main/model/metrics.py): `model/metrics.py`
- [SwED test evaluation](https://github.com/stefan-gustafsson-work/omi/blob/main/04.01-test-model-swed.sh): `04.01-test-model-swed.sh`
- [Additional variables](https://github.com/stefan-gustafsson-work/omi/blob/main/04.02-add-additional-variables.R): `04.02-add-additional-variables.R`
- [Brazil prediction](https://github.com/stefan-gustafsson-work/omi/blob/main/01.01-predict-from-brazil-model.sh): `01.01-predict-from-brazil-model.sh`
- [Brazil evaluation](https://github.com/stefan-gustafsson-work/omi/blob/main/01.02-eval-prediction-results-brazil-model.R): `01.02-eval-prediction-results-brazil-model.R`
- [Test evaluation](https://github.com/stefan-gustafsson-work/omi/blob/main/04.03-eval-test-swed.R): `04.03-eval-test-swed.R`

### Reporting

- [Results tables](https://github.com/stefan-gustafsson-work/omi/blob/main/05.01-numbers-and-tables.R): `05.01-numbers-and-tables.R`
- [Additional figures](https://github.com/stefan-gustafsson-work/omi/blob/main/05.02-additional-figures.R): `05.02-additional-figures.R`
- [Coronary heatmap](https://github.com/stefan-gustafsson-work/omi/blob/main/05.03-coronary-heatmap.R): `05.03-coronary-heatmap.R`

### Other components

- **Researcher**

## Connections

- Researcher → Study population: defines cohort (evidence: `README.md`)
- Researcher → SwED HDF5 prep: prepares ECGs (evidence: `README.md`)
- SwED HDF5 prep → ECG HDF5 builder: builds HDF5
- ECG HDF5 builder → ECG normalization: normalizes traces (evidence: `generate_hdf5.py`)
- Researcher → Train and validate: starts training (evidence: `README.md`)
- Train and validate → Training orchestration: invokes model
- Training orchestration → OMI dataset loader: loads batches (evidence: `model/main.py`)
- Training orchestration → ECG model: trains and tests (evidence: `model/main.py`)
- Training orchestration → Discrimination metrics: computes metrics (evidence: `model/main.py`)
- ECG model → Residual network: encodes ECG (evidence: `model/model.py`)
- ECG model → Age-sex encoding: encodes demographics (evidence: `model/model.py`)
- ECG model → Prediction stage: produces logits (evidence: `model/model.py`)
- Researcher → Hyperparameter search: tunes model (evidence: `README.md`)
- Researcher → Seed sensitivity: repeats training (evidence: `README.md`)
- Researcher → SwED test evaluation: tests model (evidence: `README.md`)
- SwED test evaluation → Training orchestration: runs evaluation
- Researcher → Brazil prediction: predicts externally (evidence: `README.md`)
- Brazil prediction → Brazil evaluation: evaluates predictions (evidence: `README.md`)
- Researcher → Additional variables: adds covariates (evidence: `README.md`)
- Researcher → Test evaluation: evaluates test set (evidence: `README.md`)
- Test evaluation → Results tables: summarizes results
- Researcher → Results tables: creates tables (evidence: `README.md`)
- Researcher → Additional figures: creates figures (evidence: `README.md`)
- Researcher → Coronary heatmap: maps coronary sites (evidence: `README.md`)
