jag2037 / cardiopy

Heart rate variability analysis toolkit for single-lead EKG

Cardiopy

A flexibile package for R-peak detection and heart rate variability analysis of single-lead EKG data.

Full documentation is available here. If you use CardioPy or a derivative in your work, please cite:
Gottshall, J. L., Recoder, N., Schiff, N. D. (2020). CardioPy: An open-source heart rate variability analysis toolkit for single-lead EKG. boiRxv. doi: 10.1101/2020.10.06.328856

How to use Cardiopy

Cardiopy can be used in two ways:

1. As a preprocessing module for the import and cleaning of clinical EKG data in conjuction with HRV analyses by standard software packages. For this use, run through feature sets 1 and 2 (listed below). The exported '_nn.txt' file is compatible with all major HRV software packages
   
2. As a stand-alone HRV analysis toolkit. For this use, continue through the workflow from feature set 1 through 4 (listed below). To ensure analytic reproducibilty, we highly recommend exporting cleaned nn detections at feature set 2.

Features

1. Data preprocessing and cleaning

• Load single-lead EKG data
  
• Detect R-peaks using the Pan Tompkins method
  • Option to detect R-peaks with flexible thresholding parameters for adjustment to noisy data and varying amplitudes
    
    • Option to filter especially noisy data prior to peak detection
      
• Built-in detection visualization methods
  
• Simple artifact removal methods for manual inspection of detected peaks
  

2. Export methods for cleaned peak detections

• Compatible with commonly used software such as Kubios HRV and Artiifact
  

3. HRV analysis methods

• Standard time-domain statistics
  
• Standard frequency domain statistics
  
  • Option for Multitaper or Welch power spectral estimates
    

4. HRV statistics export

• Single-file report exports in json format
  
• Multi-file exports into .csv spreadsheets for group statistics
  

Installation

Use the package manager pip to install CardioPy.

pip install cardiopy

Usage

Best when run with jupyter notebook. For detailed instructions download the example jupyter notebook file and the example jupyter notebook file for manual cleaning, as well as the de-identified data segment from github
For optimal performance, close figure interactions ('off' button on the top right corner) when finished with each window.

Parameter Optimization & Cleaning Tips

• Remove false interbeat intervals LAST, after all cleaning (addition/removal of peaks) has been done.

• To maintain integrity of the artifact logs:

  • Only remove incorrectly added peaks with EKG.undo_add_peak NOT with EKG.rm_peak.
  • Only re-add incorrectly removed peaks with EKG.undo_rm_peak NOT with EKG.add_peak.

• If R peak detections are not accurate, try:

  1. changing the moving window size
  2. changing the upshift percentage
  3. both
     

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

License

BSD 3-Clause

Roadmap

The authors plan for future versions of CardioPy to include:

• Support for additional commonly used data formats
• A graphical user interface