PeakSwift

PeakSwift is a Swift package designed for accurate and real-time R-peak detection in single-lead Electrocardiogram (ECG) data, tailored for the iOS environment. PeakSwift provides also functionality for context-aware R-Peak detection and ECG signal quality evaluation.

• Features
• Requirements
• Installation
• Usage
  • Setup Electrocardiogram
  • R-Peak detection
  • Context-aware R-Peak detection
  • ECG signal quality evaluation
• Test suite
• Dependencies
• Contributing
• PeakWatch - Demo app
• License

Features

• [x] 9 R-Peak detectors (Christov, nabian2018, Hamilton, TwoAverage, NeuroKit, Pan & Tompkins, UNSW, Engzee, Kalidas)
• [x] 2 Signal quality evaluators (Zhao2018 Simple, Zhao2018 Fuzzy)
• [x] Context-aware R-Peak detection

Requirements

| Platform | Minimum Swift Version | Installation | Status | | --- | --- | --- | --- | | iOS 13.0+ / macOS 10.15+ | 5.3 | Swift Package Manager| Fully Tested |

Installation

Swift Package Manager

To install PeakSwift using Swift Package Manager you can follow the tutorial published by Apple using the URL for the PeakSwift repo on the main branch:

1. In Xcode, select “File” → “Add Packages...”
2. Enter https://github.com/CardioKit/PeakSwift

or you can add the following dependency to your Package.swift:

dependencies: [
    .package(url: "https://github.com/CardioKit/PeakSwift.git", branch: "main")
]

You need to restrict the package version to:

platforms: [
    .macOS(.v10_15),
    .iOS(.v13)
]

And add PeakSwift to your target library.

targets: [
    .target(
        name: "<YourLibrary>",
        dependencies: ["PeakSwift"])
]

Usage

Setup Electrocardiogram

First of all, configure the ECG, you would like to analyze.

let ecg: [Double] = /* put your ECG here*/
let samplingRate: Double = /* put your SamplinRate here*/

let electrocardiogram = Electrocardiogram(ecg: ecg, samplingRate: samplingRate)

R-Peak detection

PeakSwift provides a R-Peak detection feature as follows:

let qrsDetector = QRSDetector()
    
// A default algorithm will be selected
qrsDetector.detectPeaks(electrocardiogram: electrocardiogram)

// Alternative: An algorithm may be specified
let qrsResult = qrsDetector.detectPeaks(electrocardiogram: electrocardiogram, algorithm: .neurokit)

// Extract results
let rPeaks = qrsResult.rPeaks
let cleanedSignal = qrsResult.cleanedElectrocardiogram

Context-aware R-Peak detection

You can pass the ECG signal context to PeakSwift and let PeakSwift decide on the most suitable algorithm.

let qrsDetector = QRSDetector()
    
// The most suitable algorithm for signal with Atrial Firbrillation will be selcted
qrsDetector.detectPeaks(electrocardiogram: electrocardiogram) { config in
        config.setClassification(.atrialFibrillation)
}

You can also directly specify the context provided by HealthKit:

import HealthKit

let qrsDetector = QRSDetector()
 
qrsDetector.detectPeaks(electrocardiogram: electrocardiogram) { config in
        config.setClassification(fromHealthKit: .sinusRhythm)
}

ECG signal quality evaluation

PeakSwift support signal quality evaluations:

let signalQualityEvaluator = ECGQualityEvaluator()
        
let signalQuality = signalQualityEvaluator.evaluateECGQuality(
    electrocardiogram: electrocardiogram,
    algorithm: .zhao2018(.fuzzy))

// signalQuality has to be unacceptable, barelyAcceptable or excellent

Test suite

The python-based library NeuroKit is used to generate the test data.

Firstly, install the necessary dependencies. We recommend to use the virtual environment manager (venv) for isolating the dependencies.

pip3 install -r requirements.txt

To generate the test data & run the test suite use following commands:

# Generate test data
cd TestDataGenerator
python3 main.py

# Run swift based test suite
cd .. 
swift build
swift test

Dependencies

PeakSwift relies on the following libraries:

• DSP IIR Realtime C++ filter library
• wavelib
• Surge
• NeuroKit (Test suite only)

Contributing

We welcome contributions to enhance PeakSwift:

1. Fork the repository.
2. Create a new branch: git checkout -b feature/your-feature-name
3. Commit your changes: git commit -am 'feat(Scope): Add some feature'
4. Push to the branch: git push origin feature/your-feature-name
5. Create a pull request.

PeakWatch - Demo app

To illustrate and analyze the functionalities of PeakSwift, a dedicated demo app is developed. It integrates R-Peak detection and signal quality analysis of PeakSwift and can be evaluated with an external analysis tool.

You can explore PeakWatch here: PeakWatch.

Warning

This software is for research purposes only.

How to cite?

If you are using parts of this work or build your experiments up on this repository please cite the following article:

@article{kapsecker2024peakswift,
    title = {PeakSwift: Mobile Detection of R-peaks in Single Lead Electrocardiograms},
    journal = {SoftwareX},
    volume = {25},
    pages = {101608},
    year = {2024},
    issn = {2352-7110},
    doi = {https://doi.org/10.1016/j.softx.2023.101608},
    url = {https://www.sciencedirect.com/science/article/pii/S2352711023003047},
    author = {Maximilian Kapsecker and Nikita Charushnikov and Leon Nissen and Stephan M. Jonas},
    keywords = {Electrocardiogram, R-peak detection, Swift, Benchmark}
}

License

PeakSwift is released under Apache License 2.0. See LICENSE for details.