cardiopy 1.0.0
Analysis package for single-lead clinical EKG data
Requires Python: >=3.6

# Cardiopy

A flexibile package for R-peak detection and heart rate variability analysis of single-lead EKG data. <br>
    <img src="https://github.com/CardioPy/CardioPy/blob/master/example_run/advice_images/example_detections.png">

Full documentation is available [here](https://www.biorxiv.org/content/10.1101/2020.10.06.328856v1). If you use CardioPy or a derivative in your work, please cite: <br>
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:<br>
   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 <br>
   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__<br>
   * Load single-lead EKG data<br>
   * 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<br>
		- Option to filter especially noisy data prior to peak detection<br>
   * Built-in detection visualization methods<br>
   * Simple artifact removal methods for manual inspection of detected peaks<br>

__2. Export methods for cleaned peak detections__<br>
   * Compatible with commonly used software such as Kubios HRV and Artiifact<br>

__3. HRV analysis methods__<br>
   * Standard time-domain statistics<br>
   * Standard frequency domain statistics<br>
		- Option for Multitaper or Welch power spectral estimates<br>

__4. HRV statistics export__<br>
   * Single-file report exports in json format<br>
   * Multi-file exports into .csv spreadsheets for group statistics<br>

## Installation
Use the package manager [pip](https://pip.pypa.io/en/stable/) to install CardioPy.

```bash
pip install cardiopy
```

## Usage
Best when run with jupyter notebook. For detailed instructions download the [example jupyter notebook file](https://github.com/CardioPy/CardioPy/blob/master/example_run/CardioPy_Example_Analysis.ipynb) and the [example jupyter notebook file for manual cleaning](https://github.com/CardioPy/CardioPy/blob/master/example_run/CardioPy_Example_Analysis_Manual.ipynb), as well as the [de-identified data segment](https://github.com/CardioPy/CardioPy/blob/master/example_run/HCXXX_2001-01-01_awake_cycle1_epoch1_222000.csv) from [github](https://github.com/CardioPy/CardioPy/blob/master/example_run) <br>
	*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<br>
        <img src="https://github.com/CardioPy/CardioPy/blob/master/example_run/advice_images/EKG_paramshift.png">

## 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