- Add examples in detection docs

- Clean PPG signal data import (only keep one version)

Author: Nicolas Legrand

MANIFEST.in

@@ -4,10 +4,7 @@ include LICENSE
 include requirements.txt
 
 # Add datasets files
-include systole/datasets/ppg1.npy
-include systole/datasets/ppg2.npy
-include systole/datasets/ppg3.npy
-include systole/datasets/ppgNoisy1.npy
+include systole/datasets/ppg.npy
 include systole/datasets/rr.txt
 include systole/datasets/Task1_ECG.npy
 include systole/datasets/Task1_EDA.npy

systole/datasets/5minRest.npy

@@ -11,13 +11,13 @@
 # Simulate serial inputs from ppg recording
 # =========================================
 class serialSim():
-    """Simulate online data cquisition using pre recorded signal and realistic
-    recording duration.
+    """Simulate online data acquisition using pre recorded signal and realistic
+    sampling rate (75 Hz).
     """
 
     def __init__(self, id='1'):
         self.sfreq = 75
-        self.ppg = import_ppg()[0]
+        self.ppg = import_ppg().ppg.to_numpy()
         self.start = time.time()
 
     def inWaiting(self):
@@ -32,7 +32,7 @@ def inWaiting(self):
     def read(self, length):
 
         if len(self.ppg) == 0:
-            self.ppg = import_ppg()[0]
+            self.ppg = import_ppg().ppg.to_numpy()
 
         # Read 1rst item of ppg signal
         rec = self.ppg[:1]
@@ -48,30 +48,26 @@ def reset_input_buffer(self):
         print('Reset input buffer')
 
 
-def import_ppg(id='1'):
-    """Import PPG recording.
-
-    Parameters
-    ----------
-    id : int
-        Signal number (1 or 2).
+def import_ppg():
+    """Import a 5 minutes long PPG recording.
 
     Returns
     -------
-    signal : array
-        1d array containing the PPG signal.
+    df : :py:class:`pandas.DataFrame`
+        Dataframe containing the PPG signale.
     """
-    signal = np.load(op.join(ddir, 'ppg' + id + '.npy'))
+    df = pd.DataFrame({'ppg': np.load(op.join(ddir, 'ppg.npy'))})
+    df['time'] = np.arange(0, len(df))/75
 
-    return signal
+    return df
 
 
 def import_rr():
     """Import PPG recording.
 
     Returns
     -------
-    rr : pandas DataFrame
+    rr : :py:class:`pandas.DataFrame`
         Dataframe containing the RR time-serie.
     """
     rr = pd.read_csv(op.join(ddir, 'rr.txt'))
@@ -84,7 +80,7 @@ def import_dataset():
 
     Returns
     -------
-    df : pandas DataFrame
+    df : :py:class:`pandas.DataFrame`
         Dataframe containing the RR time-serie.
 
     Notes

systole/datasets/__init__.py

@@ -42,6 +42,14 @@ def oxi_peaks(x, sfreq=75, win=1, new_sfreq=1000, clipping=True,
 
     .. warning :: This function will resample the signal to 1000 Hz.
 
+    Examples
+    --------
+    >>> from systole import import_ppg
+    >>> from systole.detection import oxi_peaks
+    >>> df = import_ppg()  # Import PPG recording
+    >>> signal, peaks = oxi_peaks(df.ppg.to_numpy())
+    >>> print(f'{sum(peaks)} peaks detected.')
+
     References
     ----------
     Some of the processing steps were adapted from the HeartPy toolbox [1]:
@@ -133,6 +141,15 @@ def ecg_peaks(x, sfreq=1000, new_sfreq=1000, method='pan-tompkins',
 
     .. warning :: This function will resample the signal to 1000 Hz.
 
+    Examples
+    --------
+    >>> from systole import import_dataset
+    >>> from systole.detection import ecg_peaks
+    >>> signal_df = import_dataset()[:20*2000]
+    >>> signal, peaks = ecg_peaks(signal_df.ecg.to_numpy(), method='hamilton',
+    >>>                           sfreq=2000, find_local=True)
+    >>> print(f'{sum(peaks)} peaks detected.')
+
     References
     ----------
     Some of the processing steps were adapted from the HeartPy toolbox [1]:
@@ -233,6 +250,14 @@ def rr_artefacts(rr, c1=0.13, c2=0.17, alpha=5.2):
     This function will use the method proposed by Lipponen & Tarvainen (2019)
     to detect ectopic beats, long, shorts, missed and extra RR intervals.
 
+    Examples
+    --------
+    >>> from systole import simulate_rr
+    >>> from systole.detection import rr_artefacts
+    >>> rr = simulate_rr()  # Simulate RR time series
+    >>> artefacts = rr_artefacts(rr)
+    >>> print(artefacts.keys())
+
     References
     ----------
     .. [1] Lipponen, J. A., & Tarvainen, M. P. (2019). A robust algorithm for
@@ -358,6 +383,21 @@ def interpolate_clipping(signal, threshold=255):
     clean_signal : 1d array-like
         Interpolated signal.
 
+    Examples
+    --------
+    .. plot::
+       >>> import matplotlib.pyplot as plt
+       >>> from systole import import_ppg
+       >>> from systole.detection import interpolate_clipping
+       >>> df = import_ppg()
+       >>> clean_signal = interpolate_clipping(df.ppg.to_numpy(),
+       >>>                                     threshold=255)
+       >>> plt.plot(df.time, clean_signal, color='#F15854')
+       >>> plt.plot(df.time, ppg, color='#5DA5DA')
+       >>> plt.axhline(y=255, linestyle='--', color='k')
+       >>> plt.xlabel('Time (s)')
+       >>> plt.ylabel('PPG level (a.u)')
+
     Notes
     -----
     Correct signal segment reaching recording threshold (default is 255)

systole/datasets/ppg.npy

@@ -104,7 +104,7 @@ def time_domain(x):
 
     Returns
     -------
-    stats : Pandas DataFrame
+    stats : :py:class:`pandas.DataFrame`
         Time domain summary statistics:
 
         'Mean RR' : Mean of R-R intervals.
@@ -192,7 +192,7 @@ def frequency_domain(x, sfreq=5, method='welch', fbands=None):
 
     Returns
     -------
-    stats : pandas DataFrame
+    stats : :py:class:`pandas.DataFrame`
         DataFrame of HRV parameters (frequency domain)
     """
     # Interpolate R-R interval
@@ -271,7 +271,7 @@ def nonlinear(x):
 
     Returns
     -------
-    stats : pandas DataFrame
+    stats : :py:class:`pandas.DataFrame`
         DataFrame of HRV parameters (frequency domain)
     """