How lxdv/ecg-classification works
Project type and purpose
• This is a research-oriented, config-driven, full-stack Python/PyTorch pipeline for training, validating, and running inference on CNN models (1D and 2D) for ECG arrhythmia classification.
• It supports three modes: Training (train.py), Validation/Inference (inference.py), and End-to-End Pipeline (pipeline.py), all driven by JSON configs.
Main components
a. Data Sources
• MIT-BIH raw ECG files (mit-bih/*.dat,*.hea,*.atr)
• Pre-generated experiment datasets (experiments/...)
b. Data Preparation
• Scripts (scripts/)
– dataset-generation-pool.py,
– annotation-generation-1d.py,
– annotation-generation-2d.py
• Outputs intermediate data artifacts (e.g., .npy, .png for 2D)
c. Configuration Layer
• JSON configs under configs/training/, configs/inference/, configs/pipelines/
• Single config.json format for each mode
d. Core Libraries
• Dataloaders (dataloaders/dataset1d.py, dataset2d.py): load data into PyTorch Datasets/DataLoaders
• Models (models/models1d.py, models/models2d.py): instantiate CNN architectures (ResNet34, EfficientNet, etc.)
• Trainers (trainers/): BaseTrainer and concrete trainers to drive forward/backward loops
• Runners (runners/): BaseRunner and inference runners that wrap a model+loader to produce outputs
e. Entry-point Scripts
• train.py – loads config → builds Trainer → kicks off training → saves checkpoints and logs
• inference.py – loads config → builds Runner → runs validation/inference → outputs metrics
• pipeline.py – loads config → builds Pipeline → runs full workflow → saves HTML results
f. Utilities & Notebooks
• utils/network_utils.py for model utilities
• Jupyter Notebooks (notebooks/) for EDA, confusion matrices
g. CI/CD
• GitHub Actions workflows under .github/workflows/ automatically install, train, and badge models
Relationships & Data Flow
• Start: Raw ECG data → *scripts* → generated dataset files
• Config JSON → passed to Entry script (train.py/inference.py/pipeline.py)
• Script reads config → instantiates Dataloader ←→ Model ←→ Trainer/Runner/Pipeline
• Trainer writes: checkpoints, logs, metrics
• Runner/Pipeline writes: predictions, visualizations, HTML reports
• CI workflows trigger scripts per commit/PR
Architectural Patterns & Principles
• “Config-principle”: all params and paths driven by JSON, no hard-coding
• Modular design: clear separation of concerns (data, models, training, pipelines)
• Base classes + inheritance (e.g., BaseTrainer, BaseRunner, BasePipeline)
• Reusable components: the same dataloaders/models are used across training and inference