How weston100/ai-ecg works
Project type and purpose
• This is a Python-based open-source tool/framework for training, evaluating, and running deep‐learning models on ECG waveforms (the SEER risk model).
• There is no client/server GUI or web front end—this is a command-line ML pipeline.
File structure
Top-level modules:
• config.py — central configuration (hyperparameters, file paths, task specs)
• dataset.py — data loading & preprocessing (normalization, filtering)
• ecg.py — orchestrator; the entry point for both train/eval modes
• model_specs.py — network architecture definitions
• model.py — training loop, loss, optimizer, checkpoint logic
• train.py — script wrapper or legacy training entry (may call ecg.py)
• requirements.txt, LICENSE.txt, README.md
README for additional insights
• The README describes two main modes: “train” and “eval.”
• It explains how config.py drives task definitions, data paths, transforms, and save locations.
a. Main components:
1) CLI / Python entry (ecg.py/train.py)
2) Configuration manager (config.py)
3) Data pipeline (dataset.py)
4) Model builder (model_specs.py)
5) Trainer/Evaluator (model.py)
6) Persistence layer (filesystem for checkpoints, CSV outputs)
7) External dependencies (PyTorch, numpy, pandas)
b. Relationships & interactions:
• User invokes: “python3 -c ‘import ecg; ecg.ecg(mode,task)’” or train.py
→ ecg.py reads config.py (task_cfg, paths, hparams)
→ dataset.py builds DataLoader with transforms
→ model_specs.py constructs the neural net
→ model.py runs training loop or evaluation loop
→ outputs written to disk (checkpoints, .csv predictions)
c. Architectural patterns / design principles:
– Modular separation: config vs data vs model vs orchestration
– Single process pipeline; no microservices
– Clear layering: “Orchestrator → Data → Model → Persistence”
– Config-driven, pluggable tasks
d. Key technologies:
– Python 3
– PyTorch (training / inference)
– pandas / numpy (data handling, CSV I/O)
– SciPy or custom filters (notch, baseline) in dataset.py
Detail without overthinking
• Python module as a separate component
• Both training and evaluation flows
• Notes on where to update hyperparameters or task definitions