# him013/heart-rhythm-classification-from-raw-ecg-signals architecture

> Architecture diagram of the GitHub repository him013/heart-rhythm-classification-from-raw-ecg-signals, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/him013/heart-rhythm-classification-from-raw-ecg-signals
- Repository: https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals

## Overview

##### Project type and purpose
- This is a data-science / machine-learning pipeline for classifying heart rhythms from raw ECG signals.
- It processes CSV files of time-series ECG data, extracts features, trains a classifier, evaluates performance, and produces a submission file for Kaggle.

##### File structure
- Top-level scripts:
– inspect_data.py: initial data exploration (distributions, NaNs, sample signals)
– feature_extraction.py: uses biosppy & SciPy to detect heartbeats, compute intervals, amplitudes, time/frequency features
– main.py: orchestrates end-to-end pipeline (load data, call feature_extraction, train model, predict, write submission.csv)
- Supporting files:
– sample_submission.csv: submission template
– model_log.txt: stored training logs and metrics
– various PDF plots: EDA artifacts (distributions, confusion matrix, etc.)
- No frontend/backend split – purely a single-process ML workflow in Python.

##### README for additional insights
- Dependencies: Python, NumPy, Pandas, biosppy, SciPy, scikit-learn, Matplotlib/Seaborn.
- Workflow: data → segment heartbeat templates → extract features → train classifier → evaluate (F1) → produce predictions.
- Future: deep learning on raw ECGs, real-time system, wearable integration.

a. Main components:
1. Data Sources
- train.csv, test.csv
- sample_submission.csv
2. Data Exploration & Validation
- inspect_data.py
- EDA outputs (signal_length_distribution, class_distribution, sample_signals)
3. Preprocessing & Feature Extraction
- feature_extraction.py
- External library: biosppy (ECG segmentation), SciPy signal processing
- Outputs: feature matrix (RR intervals, amplitudes, slopes, freq features)
4. Model Training & Evaluation
- main.py module “train” stage
- scikit-learn classifier (e.g., RandomForest/SVM)
- model_log.txt, confusion_matrix.pdf
5. Prediction & Submission
- main.py module “predict” stage
- Output: submission.csv
6. Visualization & Logging
- Matplotlib/Seaborn plots
- model performance logs

b. Relationships and interactions:
– Exploration → Preprocessing
– Preprocessing → Feature Store → Model Training
– Model Training ↔ Evaluation
– Model Training → Prediction
– Prediction → Submission
– All stages write logs/plots to disk

c. Architectural patterns and design principles:
- Layered pipeline: distinct stages for EDA, preprocessing, training, prediction
- Modular scripts with single responsibility (inspect_data.py vs feature_extraction.py vs main.py)
- Reusable feature-extraction component
- Configurable parameters (e.g., sample rate, padding handling)

d. Key technologies/frameworks:
- Python for orchestration
- biosppy for ECG segmentation
- NumPy/Pandas for data handling
- SciPy for signal processing
- scikit-learn for classical ML
- Matplotlib/Seaborn for visualization

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Data Sources"
        DS1["train.csv"]:::data
        DS2["test.csv"]:::data
        DS3["sample_submission.csv"]:::data
    end

    subgraph "Data Exploration & Validation"
        INS["inspect_data.py"]:::process
        PDF1["signal_length_distribution.pdf"]:::output
        PDF2["full_dataset_class_distribution.pdf"]:::output
        PDF3["sample_signals.pdf"]:::output
    end

    subgraph "Preprocessing & Feature Extraction"
        FE["feature_extraction.py"]:::process
        PDF4["ecg_template_analysis.pdf"]:::output
    end

    subgraph "Model Training & Evaluation"
        TRAIN["main.py - train stage"]:::ml
        LOG["model_log.txt"]:::output
        PDF5["confusion_matrix.pdf"]:::output
        PDF6["predicted_class_distribution.pdf"]:::output
    end

    subgraph "Prediction & Submission"
        PRED["main.py - predict stage"]:::ml
        SUBM["submission.csv"]:::output
    end

    DS1 --> INS
    DS2 --> INS
    DS3 --> INS

    INS --> PDF1
    INS --> PDF2
    INS --> PDF3

    INS --> FE
    FE --> PDF4

    FE --> TRAIN
    TRAIN --> LOG
    TRAIN --> PDF5
    TRAIN --> PDF6

    TRAIN --> PRED
    PRED --> SUBM

    click DS3 "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/sample_submission.csv"
    click INS "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/inspect_data.py"
    click PDF1 "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/signal_length_distribution.pdf"
    click PDF2 "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/full_dataset_class_distribution.pdf"
    click PDF3 "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/sample_signals.pdf"
    click FE "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/feature_extraction.py"
    click PDF4 "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/ecg_template_analysis.pdf"
    click TRAIN "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/main.py"
    click LOG "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/model_log.txt"
    click PDF5 "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/confusion_matrix.pdf"
    click PDF6 "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/predicted_class_distribution.pdf"
    click PRED "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/main.py"
    click SUBM "https://github.com/him013/heart-rhythm-classification-from-raw-ecg-signals/blob/main/submission.csv"

    classDef data fill:#D0E6FF,stroke:#002D72,stroke-width:1px;
    classDef process fill:#DFFFE0,stroke:#006400,stroke-width:1px;
    classDef ml fill:#FFE5CC,stroke:#CC5500,stroke-width:1px;
    classDef output fill:#F0DAFF,stroke:#660066,stroke-width:1px;
```
