# arianabdollahi83/qrs-annotation architecture

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

- Interactive diagram: https://gitdiagram.com/arianabdollahi83/qrs-annotation
- Repository: https://github.com/arianabdollahi83/qrs-annotation

## Overview

This repository combines ECG beat classification and evaluation with a separate beat-clustering toolkit, alongside patient ECG exports and example clustering results. The classifier workflow detects R-peaks, extracts beat and rhythm features, trains a hierarchical model, then predicts and evaluates arrhythmia labels and thresholds. Clustering accepts ECG signals and R-peaks independently and saves cluster artifacts. The README is empty; relationships below are limited to the sampled source excerpts and SOURCE INDEX references.

Main entry points: [`train.py`](https://github.com/arianabdollahi83/qrs-annotation/blob/main/train.py) (Model Training), [`evaluate_thresholds.py`](https://github.com/arianabdollahi83/qrs-annotation/blob/main/evaluate_thresholds.py) (Threshold Evaluation), [`hierarchical_qrs_classifier.py`](https://github.com/arianabdollahi83/qrs-annotation/blob/main/hierarchical_qrs_classifier.py) (QRS Classifier), [`functions.py`](https://github.com/arianabdollahi83/qrs-annotation/blob/main/functions.py) (R-Peak Detector)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_prep["ECG Preparation"]
  node_detector["R-Peak Detector<br/>[functions.py]"]
  node_feature_engineering["Beat Features<br/>[features.py]"]
end

subgraph group_classify["Classification"]
  node_training["Model Training<br/>[train.py]"]
  node_inference["QRS Classifier"]
  node_evaluation["Threshold Evaluation"]
end

subgraph group_cluster["Beat Clustering"]
  node_clustering["Clustering Methods"]
end

subgraph group_data["Data Artifacts"]
  node_patient_data[("Patient ECG Exports")]
  node_model["Trained Model"]
  node_thresholds["Threshold Config"]
  node_cluster_results[("Cluster Artifacts")]
end

node_operator(("ECG Analyst"))

node_patient_data -->|"reads signal"| node_detector
node_operator -.->|"runs training"| node_training
node_training -->|"detects peaks"| node_detector
node_training -->|"extracts features"| node_feature_engineering
node_training -->|"saves model"| node_model
node_operator -.->|"requests predictions"| node_inference
node_inference -->|"extracts features"| node_feature_engineering
node_inference -->|"loads model"| node_model
node_operator -->|"runs evaluation"| node_evaluation
node_evaluation -->|"evaluates predictions"| node_inference
node_evaluation -->|"detects peaks"| node_detector
node_evaluation -->|"writes threshold"| node_thresholds
node_operator -.->|"runs clustering"| node_clustering
node_clustering -->|"saves clusters"| node_cluster_results

click node_patient_data "https://github.com/arianabdollahi83/qrs-annotation/tree/main/Pats"
click node_detector "https://github.com/arianabdollahi83/qrs-annotation/blob/main/functions.py"
click node_feature_engineering "https://github.com/arianabdollahi83/qrs-annotation/blob/main/features.py"
click node_training "https://github.com/arianabdollahi83/qrs-annotation/blob/main/train.py"
click node_model "https://github.com/arianabdollahi83/qrs-annotation/blob/main/ecg_hierarchical_v4.keras"
click node_inference "https://github.com/arianabdollahi83/qrs-annotation/blob/main/hierarchical_qrs_classifier.py"
click node_evaluation "https://github.com/arianabdollahi83/qrs-annotation/blob/main/evaluate_thresholds.py"
click node_thresholds "https://github.com/arianabdollahi83/qrs-annotation/blob/main/ecg_hierarchical_v4_threshold.json"
click node_clustering "https://github.com/arianabdollahi83/qrs-annotation/blob/main/ecg_cluster_toolkit.py"
click node_cluster_results "https://github.com/arianabdollahi83/qrs-annotation/tree/main/results"

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_detector,node_feature_engineering toneBlue
class node_training,node_inference,node_evaluation toneAmber
class node_clustering toneMint
class node_patient_data,node_model,node_thresholds,node_cluster_results toneRose
class node_operator toneIndigo
```

## Components

### ECG Preparation

- [R-Peak Detector](https://github.com/arianabdollahi83/qrs-annotation/blob/main/functions.py): `functions.py`
- [Beat Features](https://github.com/arianabdollahi83/qrs-annotation/blob/main/features.py): `features.py`

### Classification

- [Model Training](https://github.com/arianabdollahi83/qrs-annotation/blob/main/train.py): `train.py`
- [QRS Classifier](https://github.com/arianabdollahi83/qrs-annotation/blob/main/hierarchical_qrs_classifier.py): `hierarchical_qrs_classifier.py`
- [Threshold Evaluation](https://github.com/arianabdollahi83/qrs-annotation/blob/main/evaluate_thresholds.py): `evaluate_thresholds.py`

### Beat Clustering

- [Clustering Methods](https://github.com/arianabdollahi83/qrs-annotation/blob/main/ecg_cluster_toolkit.py): `ecg_cluster_toolkit.py`

### Data Artifacts

- [Patient ECG Exports](https://github.com/arianabdollahi83/qrs-annotation/tree/main/Pats): `Pats`
- [Trained Model](https://github.com/arianabdollahi83/qrs-annotation/blob/main/ecg_hierarchical_v4.keras): `ecg_hierarchical_v4.keras`
- [Threshold Config](https://github.com/arianabdollahi83/qrs-annotation/blob/main/ecg_hierarchical_v4_threshold.json): `ecg_hierarchical_v4_threshold.json`
- [Cluster Artifacts](https://github.com/arianabdollahi83/qrs-annotation/tree/main/results): `results`

### Other components

- **ECG Analyst**

## Connections

- Patient ECG Exports → R-Peak Detector: reads signal (evidence: `functions.py`)
- ECG Analyst → Model Training: runs training
- Model Training → R-Peak Detector: detects peaks (evidence: `train.py`)
- Model Training → Beat Features: extracts features (evidence: `train.py`)
- Model Training → Trained Model: saves model (evidence: `train.py`)
- ECG Analyst → QRS Classifier: requests predictions
- QRS Classifier → Beat Features: extracts features (evidence: `hierarchical_qrs_classifier.py`)
- QRS Classifier → Trained Model: loads model (evidence: `hierarchical_qrs_classifier.py`)
- ECG Analyst → Threshold Evaluation: runs evaluation (evidence: `evaluate_thresholds.py`)
- Threshold Evaluation → QRS Classifier: evaluates predictions (evidence: `evaluate_thresholds.py`)
- Threshold Evaluation → R-Peak Detector: detects peaks (evidence: `evaluate_thresholds.py`)
- Threshold Evaluation → Threshold Config: writes threshold (evidence: `evaluate_thresholds.py`)
- ECG Analyst → Clustering Methods: runs clustering
- Clustering Methods → Cluster Artifacts: saves clusters (evidence: `ecg_cluster_toolkit.py`)