DOCSEARCHbyAlgolia
Submit Docs

IntroECG: Deep Learning for 12-Lead ECGs

repository·master·Indexed 41 days ago

https://github.com/pierreelias/introecg

A comprehensive library for the deep learning lifecycle of 12-lead electrocardiograms. It includes tools for waveform extraction from GE Muse XML and PDF files, synthetic data generation via a 3D trajectory model, and preprocessing workflows such as baseline wander removal and per-lead normalization. The library provides implementations for 2D CNN, autoECG (binary classification), and CRNN models, including support for transfer learning and specific input shaping for PyTorch and TensorFlow/Keras.

Tokens
14.6K
Snippets
41
Records
62
Agent score
51%

What's inside IntroECG

  1. Overview of IntroECG library capabilities

    master

    IntroECG is a full-process library designed for deep learning workflows using 12-lead electrocardiograms (ECGs). It provides a complete pipeline including:

    • Waveform Extraction: Tools and tutorials for extracting raw ECG waveforms from GE Muse systems or PDF files, including visualization tools.
    • Synthetic Data Generation: Capabilities to generate synthetic ECGs with adjustable waveform parameters for hypothesis testing.
    • Preprocessing: Methods for cleaning and normalizing ECG data.
    • Model Architectures: Example models implemented in both PyTorch and TensorFlow/Keras.
    • Training Framework: An experimentation framework built on PyTorch Ignite and Optuna, featuring Tensorboard integration for result visualization.
    • Inference & Practical Applications: Implementation details for specific models like ValveNet (for valvular heart disease) and EchoNext-Mini (for structural heart disease).

  2. Understand the structure of the Ignite and Optuna training module

    master

    The training module is organized into several key files that facilitate hyperparameter optimization:

    • constants.py: Contains all tuneable parameters and their current values.
    • paths.py: Defines paths to data files on the remote server.
    • tuningfunctions.py: Contains the functions used within the example.ipynb notebook.
    • models.py: Contains the model class definitions. To tune a model, place tuneable parameters in constants.py and call them using trial.suggest within the model initialization.
    • example.ipynb: A Jupyter Notebook providing a complete workflow for optimizing hyperparameters using Ignite and Optuna, covering data loading, objective definition, running trials, and viewing logs.

  3. Understand the CRNN Model architecture

    master

    The Convolutional Recurrent Neural Network (CRNN) model is designed for processing raw 12-lead ECG data. It uses Convolutional Neural Networks (CNNs) to extract local features and Recurrent Neural Networks (RNNs) to extract temporal features from those features.

    Input Shape: The model expects an input tensor of shape (<batch_size>, 1, 2500, 12), representing a batch of ECG signals with 2500 time steps across 12 leads.

  4. Use the autoECG model for binary ECG classification

    master

    The autoECG model is a modified version of the architecture described in Ribeiro et al. (2020). While the original model performs multi-label classification for six different abnormalities, this implementation is modified for binary classification (Normal vs. Abnormal).

    Key Modifications:

    • Output Layer: The final dense layer has been changed from six units to one unit.
    • Activation: Uses sigmoid activation to produce a single probability.
    • Loss Function: Uses binary_crossentropy.
    • Hyperparameter Tuning: Uses the keras_tuner package to optimize the model.

    Implementation Note: When using the provided autoecg_model_gpu.py file, you must update the hardcoded data path (defaulting to /data/Xtrain.npy) to point to your local dataset.

  5. Configure 2D CNN training hyperparameters

    master

    To train or evaluate the model, execute all cells in 2D_CNN.ipynb starting from cell 6.

    Hyperparameters such as the learning rate and regularization factor are configured in block 21 where optimizer_ft is defined. The model uses a learning rate scheduler; if you wish to change the decay rate, adjust the gamma rate within the scheduler configuration in that same block.

  8. Extract waveform data from GE Muse XML files

    master

    To extract ECG waveform data from GE Muse software, you must first print the ECGs as .xml files from within the GE Muse program. The resulting XML files store the raw waveform data as base-64 encoded strings within a nested dictionary structure.

    You can use the provided muse_xml_to_array.py script to automate the extraction process for batches of ECGs. For a step-by-step manual walkthrough, refer to the GE_Muse_Waveform_Extraction_Tutorial.ipynb notebook.

    # Refer to the tutorial notebook for detailed steps:
# https://github.com/perottelab/IntroECG/blob/main/1-Waveform%20Extraction/GE_Muse_Waveform_Extraction_Tutorial.ipynb

  10. Core preprocessing steps for ECG data

    master

    Effective training and testing of ML models for 12-lead ECGs requires specific preprocessing steps to handle outliers and signal noise. The primary and most essential workflow involves:

    1. Truncation: Adjusting the signal length.
    2. Baseline Wander Removal: Removing low-frequency noise/drift.
    3. Per-Lead Normalization: Scaling each lead individually.

    While other techniques like rolling average denoising and flatline removal are available, they are considered non-essential and are primarily beneficial for specific use cases.

  11. Prepare input data for EchoNext inference

    master

    To use the EchoNext model, you must provide ECG data in XML format and a corresponding labels.csv file.

    Requirements:

    • All XML files must be in a single flat directory.
    • The XML filenames (without extension) serve as the ecg_id.
    • A labels.csv file must be present in the same directory with a header and an ecg_id column.
    • The CSV must include 12 binary labels:
      • lvef_lte_45
      • lvwt_gte_13
      • aortic_stenosis_moderate_severe
      • aortic_regurgitation_moderate_severe
      • mitral_regurgitation_moderate_severe
      • tricuspid_regurgitation_moderate_severe
      • pulmonary_regurgitation_moderate_severe
      • rv_systolic_dysfunction_moderate_severe
      • pericardial_effusion_moderate_large
      • pasp_gte_45
      • tr_max_gte_32
      • shd (composite structural heart disease label)

    Note: If your data is already preprocessed into numpy waveform and feature arrays (e.g., from the PhysioNet EchoNext dataset), you can skip XML parsing and preprocessing and go directly to the Inference step.

  12. Access Tensorboard logs for training experiments

    master

    To visualize training and validation stages across experiments, use Tensorboard. Follow these steps:

    1. Install Tensorboard: If using a Conda environment, run:

      conda install -c conda-forge tensorboard

    2. Start Tensorboard: Run the following command, replacing <LOCATION OF TENSORBOARD DIRECTORY> with your actual log directory:

      tensorboard --logdir <LOCATION OF TENSORBOARD DIRECTORY>

      You should see a message indicating Tensorboard is running at http://youraddress:6006/.

    3. Port Forwarding: If working on a remote server, open a new terminal on your local machine and establish an SSH tunnel to forward the port:

      ssh youruserID@youraddress -- -NfL 6006:localhost:6006

    4. View Logs: Open your local web browser and navigate to localhost:6006.

    # Install
conda install -c conda-forge tensorboard

# Run server
tensorboard --logdir <LOCATION OF TENSORBOARD DIRECTORY>

# SSH Tunnel (run in new terminal)
ssh youruserID@youraddress -- -NfL 6006:localhost:6006