Feature/readme (#36)

* docs: Update readme

* fix: Readme anchors

* Update README.md

* fix(Readme.md): Table of contents

* docs(Readme): Final touches

* fix(Readme): typos

* fix(Readme): typos

* docs(Readme): Add test suite

* docs: Update table of contents readme

README.md

@@ -1,3 +1,188 @@
 # PeakSwift
 
-A description of this package.
+[![Swift](https://img.shields.io/badge/Swift-5.3_5.4_5.5_5.6_5.7_5.8-orange?style=flat-square)](https://img.shields.io/badge/Swift-5.3_5.4_5.5_5.6_5.7_5.8-orange?style=flat-square)
+[![Platforms](https://img.shields.io/badge/Platforms-macOS_iOS-yellowgreen?style=flat-square)](https://img.shields.io/badge/Platforms-macOS_iOS-Green?style=flat-square)
+[![Swift Package Manager](https://img.shields.io/badge/Swift_Package_Manager-compatible-blue?style=flat-square)](https://img.shields.io/badge/Swift_Package_Manager-compatible-blue?style=flat-square)
+
+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](#features)
+- [Requirements](#requirements)
+- [Installation](#installation)
+- [Usage](#usage)
+    - [Setup Electrocardiogram](#setup-electrocardiogram)
+    - [R-Peak detection](#r-peak-detection)
+    - [Context-aware R-Peak detection](#context-aware-r-peak-detection)
+    - [ECG signal quality evaluation](#ecg-signal-quality-evaluation)
+- [Test suite](#test-suite)
+- [Dependencies](#dependencies)
+- [Contributing](#contributing)
+- [PeakWatch - Demo app](#peakwatch---demo-app)
+- [License](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](#swift-package-manager)| Fully Tested |
+
+## Installation
+
+### Swift Package Manager
+
+To install PeakSwift using [Swift Package Manager](https://github.com/apple/swift-package-manager) you can follow the [tutorial published by Apple](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app) using the URL for the PeakSwift repo on the main branch:
+
+1. In Xcode, select “File” → “Add Packages...”
+1. Enter https://github.com/CardioKit/PeakSwift
+
+or you can add the following dependency to your `Package.swift`:
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/CardioKit/PeakSwift.git", branch: "main")
+]
+```
+
+You need to restrict the package version to: 
+```swift
+platforms: [
+    .macOS(.v10_15),
+    .iOS(.v13)
+]
+```
+
+And add PeakSwift to your target library.
+
+```swift
+targets: [
+    .target(
+        name: "<YourLibrary>",
+        dependencies: ["PeakSwift"])
+]
+```
+
+## Usage
+
+### Setup Electrocardiogram
+First of all, configure the ECG, you would like to analyze. 
+
+```swift
+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:
+
+```swift
+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.
+
+
+```swift
+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:
+```swift
+import HealthKit
+
+let qrsDetector = QRSDetector()
+
+qrsDetector.detectPeaks(electrocardiogram: electrocardiogram) { config in
+        config.setClassification(fromHealthKit: .sinusRhythm)
+}
+```  
+
+### ECG signal quality evaluation
+PeakSwift support signal quality evaluations:
+
+```swift
+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](https://github.com/neuropsychology/NeuroKit) is used to generate the test data.
+
+Firstly, install the necessary dependencies. We recommend to use the [virtual environment manager (venv)](https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/) for isolating the dependencies. 
+
+```properties
+pip3 install -r requirements.txt
+```
+
+
+ To generate the test data & run the test suite use following commands:
+
+```properties
+# 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](https://github.com/berndporr/iir1)
+- [wavelib](https://github.com/rafat/wavelib)
+- [Surge](https://github.com/Jounce/Surge)
+- [NeuroKit (Test suite only)](https://github.com/neuropsychology/NeuroKit)
+
+## 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](https://github.com/CardioKit/PeakWatch).
+
+## License
+
+PeakSwift is released under Apache License 2.0. [See LICENSE](https://github.com/CardioKit/PeakSwift/blob/main/LICENSE) for details.

TestDataGenerator/requirements.txt

@@ -0,0 +1,3 @@
+neurokit2==0.2.4
+numpy==1.25.2
+pywavelets==1.4.1