# bowang-lab/ecg-fm architecture

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

- Interactive diagram: https://gitdiagram.com/bowang-lab/ecg-fm
- Repository: https://github.com/bowang-lab/ecg-fm

## Overview

1. **Repository role**
   - This repo is primarily a **research landing/experiment repo** for ECG-FM, not the full model implementation.
   - The actual deep learning training and inference stack lives in the external **fairseq_signals** framework; this repo provides **project-specific data, label handling, notebooks, and analysis scripts** around it.

2. **Main system boundary**
   - The architectural boundary is between:
     - **data preparation / annotation / analysis** in this repo, and
     - **model execution** in `fairseq_signals`.
   - This repo mostly orchestrates how ECG data is turned into manifests, labels, and checkpoints that `fairseq_signals` can consume.

3. **Data layer**
   - `data/` contains example datasets and intermediate artifacts.
   - For `code_15`, the flow is visible end-to-end:
     - `org/` = original `.mat` ECG records
     - `preprocessed/` = cleaned/normalized `.mat` files
     - `segmented/` = shorter segmented ECG windows as `.mat`
     - `labels/` = label definition and label arrays (`label_def.csv`, `labels.csv`, `y.npy`)
     - `meta.csv`, `meta_split.csv`, `segmented.csv`, `segmented_split_incomplete.csv` = metadata and split bookkeeping
   - `data/mimic_iv_ecg/` contains the labeler assets used for free-text ECG report processing.

4. **Preprocessing and dataset shaping**
   - The repo represents a multi-stage ECG pipeline: raw signals are standardized, segmented, and then referenced via metadata tables.
   - The resulting artifacts are designed to become **dataset manifests** for training/validation splits.
   - `splits/` stores split definitions for supported corpora, including MIMIC-IV-ECG and PhysioNet.

5. **Labeling subsystem**
   - `labeler/` is a self-contained text-to-label utility layer.
   - It implements **pattern-based medical text labeling** and label normalization using:
     - JSON pattern/template files
     - string utilities and preprocessing helpers
     - conversion helpers to/from JSON
     - matcher and rule logic
   - This is a separate subsystem from ECG signal modeling: it operates on text/report content to produce structured labels.

6. **Labeler assets and semantics**
   - `data/mimic_iv_ecg/labeler/` holds the rule and ontology files used by the labeler.
   - The JSON files encode entities, descriptors, temporal patterns, connectives, uncertainty mapping, and compound expressions.
   - Architecturally, this is a **rule-engine / ontology-driven labeling layer** feeding downstream classification tasks.

7. **Model checkpoints and experiment artifacts**
   - `ckpts/` and `outputs/` are empty placeholders in the repo, indicating where training outputs and experiment results are expected to land.
   - The actual published model weights are **externalized to HuggingFace**, not committed here.
   - This separation keeps the repo focused on reproducible tooling rather than storing large binary model assets.

8. **Training and inference entry points**
   - The repo does not contain the core trainer; instead, it documents how to invoke `fairseq-hydra-train` with ECG-FM configs.
   - The README shows two main model workflows:
     - **pretraining** on MIMIC-IV-ECG + PhysioNet 2021
     - **finetuning** on MIMIC-IV-ECG diagnosis labels
   - These jobs depend on manifests, label files, pretrained checkpoints, and Hydra config overrides.

9. **Analysis / downstream utility scripts**
   - `scripts/embs.py` likely extracts embeddings for downstream use.
   - `scripts/linear.py` supports **linear probing** experiments, using frozen or pretrained representations.
   - `scripts/saliency.py` supports **attribution/saliency visualization**, matching the saliency figure shown in the README.
   - These scripts sit downstream of the pretrained model and help evaluate representation quality and interpretability.

10. **Notebook-based workflows**
   - `notebooks/` contains the user-facing workflows:
     - `infer_quickstart.ipynb` for inference and visualization
     - `infer_cli.ipynb` for command-line result extraction/post-processing
     - `labeler.ipynb` for the pattern labeler demo
   - These notebooks are the practical interface for engineers and researchers interacting with the repo.

11. **External dependencies and infrastructure**
   - The important external dependencies affecting architecture are:
     - **fairseq_signals** for training/inference
     - **Hydra** for config-driven execution
     - **PyTorch checkpoints** for saved model weights
     - external datasets: **MIMIC-IV-ECG** and **PhysioNet Challenge 2021**
   - The repo is therefore best understood as a **data + configuration + analysis layer** around an external ECG model framework.

12. **End-to-end data flow**
   - The architecture flow is:
     - raw ECG records and report text
     - preprocessing / segmentation / labeling
     - manifest and split generation
     - model pretraining or finetuning in `fairseq_signals`
     - checkpoint output to `ckpts/` or `outputs/`
     - inference, embedding extraction, probing, and saliency analysis
   - The labeler can optionally sit upstream of finetuning, converting report text into structured targets.

Main entry points: [`labeler/pattern_labeler.py`](https://github.com/bowang-lab/ecg-fm/blob/main/labeler/pattern_labeler.py) (Pattern labeler), [`README.md`](https://github.com/bowang-lab/ecg-fm/blob/main/README.md) (README), [`data/code_15/meta.csv`](https://github.com/bowang-lab/ecg-fm/blob/main/data/code_15/meta.csv) (Metadata), [`data/code_15/org`](https://github.com/bowang-lab/ecg-fm/tree/main/data/code_15/org) (Raw ECG)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_data["Data layer"]
  node_n_data_code15_org[("Raw ECG<br/>signal source")]
  node_n_data_code15_pre[("Preprocessed ECG<br/>signal prep")]
  node_n_data_code15_seg[("Segments<br/>signal windows")]
  node_n_data_code15_meta["Metadata<br/>manifest tables<br/>[meta.csv]"]
  node_n_data_code15_labels["Labels<br/>targets<br/>[labels.csv]"]
  node_n_data_code15_labeldef["Label defs<br/>ontology table<br/>[label_def.csv]"]
  node_n_data_code15_y["Target array<br/>numpy targets<br/>[y.npy]"]
  node_n_data_mimic_labeler[("MIMIC labeler<br/>label assets")]
  node_n_splits["Split defs<br/>split tables"]
end

subgraph group_g_labeler["Labeler"]
  node_n_labeler_core["Pattern labeler<br/>rule engine<br/>[pattern_labeler.py]"]
  node_n_labeler_match["Matcher rules<br/>matching logic<br/>[pattern_matcher.py]"]
  node_n_labeler_utils["Preprocess utils<br/>text utils<br/>[preprocess.py]"]
  node_n_labeler_io["JSON I/O<br/>serialization<br/>[from_json.py]"]
end

subgraph group_g_analysis["Analysis & workflows"]
  node_n_notebooks[("Notebooks<br/>workflow demos")]
  node_n_scripts_embs["Embeddings<br/>analysis script<br/>[embs.py]"]
  node_n_scripts_linear["Linear probe<br/>analysis script<br/>[linear.py]"]
  node_n_scripts_saliency["Saliency<br/>analysis script<br/>[saliency.py]"]
end

subgraph group_g_external["External stack"]
  node_n_fairseq["fairseq_signals<br/>external trainer"]
  node_n_checkpoints[("Checkpoints<br/>artifact sink")]
  node_n_outputs[("Outputs<br/>artifact sink")]
end

node_n_readme["README<br/>project guide<br/>[README.md]"]

node_n_readme -->|"documents"| node_n_data_code15_org
node_n_readme -->|"documents"| node_n_labeler_core
node_n_readme -->|"depends on"| node_n_fairseq
node_n_data_code15_org -->|"preprocess"| node_n_data_code15_pre
node_n_data_code15_pre -->|"segment"| node_n_data_code15_seg
node_n_data_code15_seg -->|"index"| node_n_data_code15_meta
node_n_data_code15_meta -->|"join"| node_n_data_code15_labels
node_n_data_code15_labels -->|"materialize"| node_n_data_code15_y
node_n_data_mimic_labeler -->|"feeds"| node_n_labeler_core
node_n_labeler_utils -->|"supports"| node_n_labeler_core
node_n_labeler_match -->|"implements"| node_n_labeler_core
node_n_labeler_io -->|"serializes"| node_n_labeler_core
node_n_splits -->|"configures"| node_n_fairseq
node_n_fairseq -->|"writes"| node_n_checkpoints
node_n_fairseq -->|"writes"| node_n_outputs
node_n_notebooks -->|"orchestrates"| node_n_fairseq
node_n_scripts_embs -->|"consumes"| node_n_fairseq
node_n_scripts_linear -->|"consumes"| node_n_fairseq
node_n_scripts_saliency -->|"consumes"| node_n_fairseq
node_n_labeler_core -.->|"can supply labels"| node_n_scripts_linear
node_n_data_code15_meta -->|"manifests"| node_n_fairseq

click node_n_readme "https://github.com/bowang-lab/ecg-fm/blob/main/README.md"
click node_n_data_code15_org "https://github.com/bowang-lab/ecg-fm/tree/main/data/code_15/org"
click node_n_data_code15_pre "https://github.com/bowang-lab/ecg-fm/tree/main/data/code_15/preprocessed"
click node_n_data_code15_seg "https://github.com/bowang-lab/ecg-fm/tree/main/data/code_15/segmented"
click node_n_data_code15_meta "https://github.com/bowang-lab/ecg-fm/blob/main/data/code_15/meta.csv"
click node_n_data_code15_labels "https://github.com/bowang-lab/ecg-fm/blob/main/data/code_15/labels/labels.csv"
click node_n_data_code15_labeldef "https://github.com/bowang-lab/ecg-fm/blob/main/data/code_15/labels/label_def.csv"
click node_n_data_code15_y "https://github.com/bowang-lab/ecg-fm/blob/main/data/code_15/labels/y.npy"
click node_n_data_mimic_labeler "https://github.com/bowang-lab/ecg-fm/tree/main/data/mimic_iv_ecg/labeler"
click node_n_splits "https://github.com/bowang-lab/ecg-fm/tree/main/splits"
click node_n_labeler_core "https://github.com/bowang-lab/ecg-fm/blob/main/labeler/pattern_labeler.py"
click node_n_labeler_match "https://github.com/bowang-lab/ecg-fm/blob/main/labeler/pattern_matcher.py"
click node_n_labeler_utils "https://github.com/bowang-lab/ecg-fm/blob/main/labeler/preprocess.py"
click node_n_labeler_io "https://github.com/bowang-lab/ecg-fm/blob/main/labeler/from_json.py"
click node_n_notebooks "https://github.com/bowang-lab/ecg-fm/tree/main/notebooks"
click node_n_scripts_embs "https://github.com/bowang-lab/ecg-fm/blob/main/scripts/embs.py"
click node_n_scripts_linear "https://github.com/bowang-lab/ecg-fm/blob/main/scripts/linear.py"
click node_n_scripts_saliency "https://github.com/bowang-lab/ecg-fm/blob/main/scripts/saliency.py"
click node_n_checkpoints "https://github.com/bowang-lab/ecg-fm/tree/main/ckpts"
click node_n_outputs "https://github.com/bowang-lab/ecg-fm/tree/main/outputs"

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_n_data_code15_org,node_n_data_code15_pre,node_n_data_code15_seg,node_n_data_code15_meta,node_n_data_code15_labels,node_n_data_code15_labeldef,node_n_data_code15_y,node_n_data_mimic_labeler,node_n_splits toneBlue
class node_n_labeler_core,node_n_labeler_match,node_n_labeler_utils,node_n_labeler_io toneAmber
class node_n_notebooks,node_n_scripts_embs,node_n_scripts_linear,node_n_scripts_saliency toneMint
class node_n_fairseq,node_n_checkpoints,node_n_outputs toneRose
class node_n_readme toneNeutral
```

## Components

### Data layer

ECG datasets, intermediate artifacts, manifests, and split tables.

- [Raw ECG](https://github.com/bowang-lab/ecg-fm/tree/main/data/code_15/org): signal source · Original .mat ECG records for the code_15 example dataset. · `data/code_15/org`
- [Preprocessed ECG](https://github.com/bowang-lab/ecg-fm/tree/main/data/code_15/preprocessed): signal prep · Cleaned and normalized ECG .mat files. · `data/code_15/preprocessed`
- [Segments](https://github.com/bowang-lab/ecg-fm/tree/main/data/code_15/segmented): signal windows · Short segmented ECG windows generated from preprocessed records. · `data/code_15/segmented`
- [Metadata](https://github.com/bowang-lab/ecg-fm/blob/main/data/code_15/meta.csv): manifest tables · Metadata and bookkeeping tables for code_15. · `data/code_15/meta.csv`
- [Labels](https://github.com/bowang-lab/ecg-fm/blob/main/data/code_15/labels/labels.csv): targets · Label definitions and target arrays for code_15. · `data/code_15/labels/labels.csv`
- [Label defs](https://github.com/bowang-lab/ecg-fm/blob/main/data/code_15/labels/label_def.csv): ontology table · Label vocabulary and definitions used for the code_15 task. · `data/code_15/labels/label_def.csv`
- [Target array](https://github.com/bowang-lab/ecg-fm/blob/main/data/code_15/labels/y.npy): numpy targets · Binary or multi-label target matrix for code_15. · `data/code_15/labels/y.npy`
- [MIMIC labeler](https://github.com/bowang-lab/ecg-fm/tree/main/data/mimic_iv_ecg/labeler): label assets · Pattern and ontology files used to label MIMIC-IV-ECG report text. · `data/mimic_iv_ecg/labeler`
- [Split defs](https://github.com/bowang-lab/ecg-fm/tree/main/splits): split tables · Dataset split definitions for MIMIC-IV-ECG and PhysioNet corpora. · `splits`

### Labeler

Rule-based text-to-label normalization for ECG report content.

- [Pattern labeler](https://github.com/bowang-lab/ecg-fm/blob/main/labeler/pattern_labeler.py): rule engine · Main text-to-label matching and normalization engine. · `labeler/pattern_labeler.py`
- [Matcher rules](https://github.com/bowang-lab/ecg-fm/blob/main/labeler/pattern_matcher.py): matching logic · Entity, descriptor, uncertainty, connective, and compound matching logic. · `labeler/pattern_matcher.py`
- [Preprocess utils](https://github.com/bowang-lab/ecg-fm/blob/main/labeler/preprocess.py): text utils · String cleanup, preprocessing, and labeler helper utilities. · `labeler/preprocess.py`
- [JSON I/O](https://github.com/bowang-lab/ecg-fm/blob/main/labeler/from_json.py): serialization · Conversion helpers to and from JSON pattern files. · `labeler/from_json.py`

### Analysis & workflows

Notebooks and scripts for inference, probing, embeddings, and saliency.

- [Notebooks](https://github.com/bowang-lab/ecg-fm/tree/main/notebooks): workflow demos · Interactive workflows for inference, CLI post-processing, and labeler demos. · `notebooks`
- [Embeddings](https://github.com/bowang-lab/ecg-fm/blob/main/scripts/embs.py): analysis script · Extracts embeddings for downstream use. · `scripts/embs.py`
- [Linear probe](https://github.com/bowang-lab/ecg-fm/blob/main/scripts/linear.py): analysis script · Runs linear probing experiments on frozen or pretrained representations. · `scripts/linear.py`
- [Saliency](https://github.com/bowang-lab/ecg-fm/blob/main/scripts/saliency.py): analysis script · Generates attribution and saliency visualizations. · `scripts/saliency.py`

### External stack

Model execution and pretrained assets live outside this repo.

- **fairseq_signals**: external trainer · External framework that performs pretraining and finetuning.
- [Checkpoints](https://github.com/bowang-lab/ecg-fm/tree/main/ckpts): artifact sink · Expected location for model checkpoints and experiment outputs in this repo. · `ckpts`
- [Outputs](https://github.com/bowang-lab/ecg-fm/tree/main/outputs): artifact sink · Expected location for generated results and experiment artifacts. · `outputs`

### Other components

- [README](https://github.com/bowang-lab/ecg-fm/blob/main/README.md): project guide · Explains workflows, datasets, and how this repo connects to the external model stack. · `README.md`

## Connections

- README → Raw ECG: documents · Describes the end-to-end ECG dataset flow.
- README → Pattern labeler: documents · Explains the text labeling subsystem.
- README → fairseq_signals: depends on · Training and inference are delegated to the external framework.
- Raw ECG → Preprocessed ECG: preprocess · Raw ECG records are cleaned and normalized.
- Preprocessed ECG → Segments: segment · Preprocessed signals are split into shorter windows.
- Segments → Metadata: index · Segmented signals are referenced by metadata tables.
- Metadata → Labels: join · Metadata is paired with label tables for training.
- Labels → Target array: materialize · Labels are converted to target arrays.
- MIMIC labeler → Pattern labeler: feeds · Pattern and ontology files drive the labeler.
- Preprocess utils → Pattern labeler: supports · Preprocessing utilities normalize report text before matching.
- Matcher rules → Pattern labeler: implements · Matcher logic underpins the labeler engine.
- JSON I/O → Pattern labeler: serializes · JSON conversion supports pattern/template loading and export.
- Split defs → fairseq_signals: configures · Split definitions shape training and validation runs.
- fairseq_signals → Checkpoints: writes · Training produces checkpoints and saved model weights.
- fairseq_signals → Outputs: writes · Inference and experiments generate outputs here.
- Notebooks → fairseq_signals: orchestrates · Notebooks invoke inference and post-processing workflows.
- Embeddings → fairseq_signals: consumes · Embedding extraction uses trained representations.
- Linear probe → fairseq_signals: consumes · Linear probing runs on pretrained or frozen models.
- Saliency → fairseq_signals: consumes · Saliency analysis requires model predictions and gradients.
- Pattern labeler → Linear probe: can supply labels · Structured labels can feed downstream probing tasks.
- Metadata → fairseq_signals: manifests · Metadata tables are shaped into training manifests.
