Initial commit

README.md

@@ -0,0 +1,76 @@
+# ECGSynKit
+
+Swift Package for generating synthetic ECG signals. Includes implementation of ECGSYN [[1]](#1).
+
+# Notes
+
+Implementation roughly corresponds with MATLAB/Java implementation of ECGSYN [[2]](#2) with a few
+implementation differences to improve performance. The library is also structured so that expensive
+computations can be reused for multiple signals and a single RR series can be reused to generate multi-lead
+ECGs.
+
+This implementation generalizes the attractor array to arbitrary size to allow modeling R′ and S′ morphologies.
+
+# Usage
+
+Initialize `TimeParameters` and `RRParameters`:
+```swift
+import ECGSynKit
+
+let timeParameters = TimeParameters(
+    numBeats: 500,
+    srInternal: 10, // internal generator sampling rate
+    decimateFactor: 2, // decimation factor (output signal sample rate will be `srInternal / decimateFactor`)
+    hrMean: 60, // mean heart rate in BPM
+    hrStd: 1, // heart rate standard deviation
+    seed: 1) // rng seed value
+    
+let rrParameters = RRParameters(
+    flo: 0.1, // low frequency oscillation (Mayer wave) in Hz
+    flostd: 0.01, // low frequency oscillation standard deviation
+    fhi: 0.25, // high frequency oscillation (respiration) in Hz
+    fhistd: 0.01, // high frequency oscillation standard deviation
+    lfhfratio: 0.5) // low frequency to high frequency power ratio
+```
+
+Initialize an RR Series generator. This will prepare an FFT setup for the required signal size.
+Afterwards generate the RR Series:
+
+``` swift
+let rrGenerator = ECGSynRRGenerator(params: timeParameters)
+let rrSeries = rrGenerator.generateSeries(params: rrParameters)
+```
+
+The `rrSeries` can be used multiple times such as to generate multilead ECG signals.
+
+
+The `attractors` parameter specify the morphology of the exponential extrema of the ECG. For a normal
+ECG there are 5 attractors corresponding to PQRST. The parameters `θ`, `a`, `b` are as described in the paper
+and are angular position around the signal limit circle, amplitude, and width. The `θrf` parameter is optional
+and is a generalization of the stretching factors for `θ`. Each `θ` will be adjusted by `θ * pow(hrMean / 60.0, θrf)`.
+
+``` swift
+let params = ECGSyn.Parameters(
+    range: (-0.4, 1.2) // the voltage range to scale the signal in mV
+    noiseAmplitude: 0.01, // the amplitude of the additive uniform noise
+    attractors: [
+    // θ, a, b, θrf
+        .make(deg: -70, 1.2, 0.25, 0.25),
+        .make(deg: -15, -5.0, 0.1, 0.5),
+        .make(deg: 0, 30, 0.1),
+        .make(deg: 15, -7.5, 0.1, 0.5),
+        .make(deg: 100, 0.75, 0.4, 0.25),
+    ]
+)
+
+let signal = ECGSyn.generate(params: timeParameters) // signal is [Double]
+```
+
+
+# References
+
+<a id="1">[1]</a>
+McSharry PE, Clifford GD, Tarassenko L, Smith L. A dynamical model for generating synthetic electrocardiogram signals. IEEE Transactions on Biomedical Engineering 50(3): 289-294; March 2003.
+
+<a id="2">[2]</a>
+Goldberger, A., Amaral, L., Glass, L., Hausdorff, J., Ivanov, P. C., Mark, R., ... & Stanley, H. E. (2000). PhysioBank, PhysioToolkit, and PhysioNet: Components of a new research resource for complex physiologic signals. Circulation [Online]. 101 (23), pp. e215–e220.