add docstring

Author: cx1111

README.rst

@@ -1,4 +1,5 @@
-from .basic import resample_ann, resample_sig, resample_singlechan, resample_multichan, normalize
+from .basic import (resample_ann, resample_sig, resample_singlechan,
+    resample_multichan, normalize)
 from .gqrs import gqrs_detect
 from .hr import compute_hr
 from .peaks import find_peaks, correct_peaks

wfdb/processing/__init__.py

@@ -4,27 +4,38 @@
 from wfdb import Annotation
 
 
-def resample_ann(tt, sample):
-    # tt: numpy.array as returned by signal.resample
-    # sample: numpy.array containing indices of annotations (Annotation.sample)
-
-    # Compute the new annotation indices
-
-    tmp = numpy.zeros(len(tt), dtype='int16')
+def resample_ann(resampled_t, ann_sample):
+    """
+    Compute the new annotation indices
+    
+    Parameters
+    ----------
+    resampled_t : numpy array
+        Array of signal locations as returned by scipy.signal.resample
+    ann_sample : numpy array
+        Array of annotation locations
+    
+    Returns
+    -------
+    resampled_ann_sample : numpy array
+        Array of resampled annotation locations
+
+    """
+    tmp = numpy.zeros(len(resampled_t), dtype='int16')
     j = 0
-    tprec = tt[j]
-    for i, v in enumerate(sample):
+    tprec = resampled_t[j]
+    for i, v in enumerate(ann_sample):
         while True:
             d = False
             if v < tprec:
                 j -= 1
-                tprec = tt[j]
+                tprec = resampled_t[j]
 
-            if j+1 == len(tt):
+            if j+1 == len(resampled_t):
                 tmp[j] += 1
                 break
 
-            tnow = tt[j+1]
+            tnow = resampled_t[j+1]
             if tprec <= v and v <= tnow:
                 if v-tprec < tnow-v:
                     tmp[j] += 1
@@ -41,77 +52,144 @@ def resample_ann(tt, sample):
     for i in idx:
         for j in range(tmp[i]):
             res.append(i)
-    assert len(res) == len(sample)
+    assert len(res) == len(ann_sample)
+
     return numpy.asarray(res, dtype='int64')
 
 
 def resample_sig(x, fs, fs_target):
-    # x: a numpy.array containing the signal
-    # fs: the current frequency
-    # fs_target: the target frequency
-
-    # Resample a signal
+    """
+    Resample a signal to a different frequency.
+    
+    Parameters
+    ----------
+    x : numpy array
+        Array containing the signal
+    fs : int, or float
+        The original sampling frequency
+    fs_target : int, or float
+        The target frequency
+    
+    Returns
+    -------
+    resampled_x : numpy array
+        Array of the resampled signal values
+    resampled_t : numpy array
+        Array of the resampled signal locations
+
+    """
 
     t = numpy.arange(x.shape[0]).astype('float64')
 
     if fs == fs_target:
         return x, t
 
     new_length = int(x.shape[0]*fs_target/fs)
-    xx, tt = signal.resample(x, num=new_length, t=t)
-    assert xx.shape == tt.shape and xx.shape[0] == new_length
-    assert numpy.all(numpy.diff(tt) > 0)
-    return xx, tt
+    resampled_x, resampled_t = signal.resample(x, num=new_length, t=t)
+    assert resampled_x.shape == resampled_t.shape and resampled_x.shape[0] == new_length
+    assert numpy.all(numpy.diff(resampled_t) > 0)
+    
+    return resampled_x, resampled_t
 
 
 def resample_singlechan(x, ann, fs, fs_target):
-    # x: a numpy.array containing the signal
-    # ann: an Annotation object
-    # fs: the current frequency
-    # fs_target: the target frequency
-
-    # Resample a single-channel signal with its annotations
-
-    xx, tt = resample_sig(x, fs, fs_target)
-
-    new_sample = resample_ann(tt, ann.sample)
+    """
+    Resample a single-channel signal with its annotations
+    
+    Parameters
+    ----------
+    x: numpy array
+        The signal array
+    ann : wfdb Annotation
+        The wfdb annotation object
+    fs : int, or float
+        The original frequency
+    fs_target : int, or float
+        The target frequency
+
+    Returns
+    -------
+    resampled_x : numpy array
+        Array of the resampled signal values
+    resampled_ann : wfdb Annotation
+        Annotation containing resampled annotation locations
+
+    """
+
+    resampled_x, resampled_t = resample_sig(x, fs, fs_target)
+
+    new_sample = resample_ann(resampled_t, ann.sample)
     assert ann.sample.shape == new_sample.shape
 
-    new_ann = Annotation(ann.record_name, ann.extension, new_sample, ann.symbol, ann.num, ann.subtype, ann.chan, ann.aux_note, ann.fs)
-    return xx, new_ann
-
+    resampled_ann = Annotation(ann.record_name, ann.extension, new_sample,
+        ann.symbol, ann.num, ann.subtype, ann.chan, ann.aux_note, ann.fs)
 
-def resample_multichan(xs, ann, fs, fs_target, resamp_ann_chan=0):
-    # xs: a numpy.ndarray containing the signals as returned by wfdb.srdsamp
-    # ann: an Annotation object
-    # fs: the current frequency
-    # fs_target: the target frequency
-    # resample_ann_channel: the signal channel that is used to compute new annotation indices
+    return resampled_x, resampled_ann
 
-    # Resample multiple channels with their annotations
 
+def resample_multichan(xs, ann, fs, fs_target, resamp_ann_chan=0):
+    """
+    Resample multiple channels with their annotations
+
+    Parameters
+    ----------
+    xs: numpy array
+        The signal array
+    ann : wfdb Annotation
+        The wfdb annotation object
+    fs : int, or float
+        The original frequency
+    fs_target : int, or float
+        The target frequency
+    resample_ann_channel : int, optional
+        The signal channel used to compute new annotation indices
+    
+    Returns
+    -------
+    resampled_xs : numpy array
+        Array of the resampled signal values
+    resampled_ann : wfdb Annotation
+        Annotation containing resampled annotation locations
+
+    """
     assert resamp_ann_chan < xs.shape[1]
 
     lx = []
     lt = None
     for chan in range(xs.shape[1]):
-        xx, tt = resample_sig(xs[:, chan], fs, fs_target)
-        lx.append(xx)
+        resampled_x, resampled_t = resample_sig(xs[:, chan], fs, fs_target)
+        lx.append(resampled_x)
         if chan == resamp_ann_chan:
-            lt = tt
+            lt = resampled_t
 
     new_sample = resample_ann(lt, ann.sample)
     assert ann.sample.shape == new_sample.shape
 
-    new_ann = Annotation(ann.record_name, ann.extension, new_sample, ann.symbol, ann.num, ann.subtype, ann.chan, ann.aux_note, ann.fs)
-    return numpy.column_stack(lx), new_ann
+    resampled_ann = Annotation(ann.record_name, ann.extension, new_sample, ann.symbol,
+        ann.num, ann.subtype, ann.chan, ann.aux_note, ann.fs)
 
+    return numpy.column_stack(lx), resampled_ann
 
-def normalize(x, lb=0, ub=1):
-    # lb: Lower bound
-    # ub: Upper bound
 
-    # Resizes a signal between the lower and upper bound
+def normalize(x, lb=0, ub=1):
+    """
+    Normalize a signal between the lower and upper bound
+    
+    Parameters
+    ----------
+    x : numpy array
+        Original signal to be normalized
+    lb : int, or float
+        Lower bound
+    ub : int, or float
+        Upper bound
+
+    Returns
+    -------
+    x_normalized : numpy array
+        Normalized signal
+    
+    """
 
     mid = ub - (ub - lb) / 2
     min_v = numpy.min(x)

wfdb/processing/basic.py

@@ -463,7 +463,8 @@ def gqrs_detect(x, fs, adcgain, adczero, threshold=1.0,
     Functionally, a direct port of the gqrs algorithm from the original
     wfdb package. Therefore written to accept wfdb record fields.
     
-    Input arguments:
+    Parameters
+    ----------
     - x (required): The digital signal as a numpy array
     - fs (required): The sampling frequency of the signal
     - adcgain: The gain of the signal (the number of adus (q.v.) per physical unit)
@@ -481,7 +482,10 @@ def gqrs_detect(x, fs, adcgain, adczero, threshold=1.0,
     - QRSa (default=750): Typical QRS peak-to-peak amplitude, in microvolts
     - QRSamin (default=130): Minimum QRS peak-to-peak amplitude, in microvolts
 
-    Note: This function should not be used for signals with fs <= 50Hz
+    Notes
+    -----
+    This function should not be used for signals with fs <= 50Hz
+    
     """
     conf = Conf(freq=fs, gain=adcgain, hr=hr,
                 RRdelta=RRdelta, RRmin=RRmin, RRmax=RRmax,

wfdb/processing/gqrs.py

@@ -1,23 +1,28 @@
 import numpy as np
 
 
-def compute_hr(siglen, peak_indices, fs):
+def compute_hr(sig_len, peak_indices, fs):
     """
     Compute instantaneous heart rate from peak indices.
 
-    Usage: 
-    heart_rate = compute_hr(siglen, peak_indices, fs)
+    Parameters
+    ----------
+    sig_len : int
+        The length of the corresponding signal
+    peak_indices : numpy array
+        The peak index locations
+    fs : int, or float
+        The corresponding signal's sampling frequency.
+
+    Returns
+    -------
+    heart_rate : numpy array
+        An array of the instantaneous heart rate, with the length of the
+        corresponding signal. Contains numpy.nan where heart rate could not be
+        computed.
 
-    Input argumnets:
-    - siglen (required): The length of the corresponding signal
-    - peak_indices (required): The peak indices.
-    - fs (required): The corresponding signal's sampling frequency.
-
-    Output arguments:
-    - heart_rate: A numpy array of the instantaneous heart rate, with the length
-      of the corresponding signal. Contains numpy.nan where heart rate could not be computed.
     """
-    heart_rate = np.full(siglen, np.nan, dtype='float32')
+    heart_rate = np.full(sig_len, np.nan, dtype='float32')
 
     if len(peak_indices) < 2:
         return heart_rate

wfdb/processing/hr.py

@@ -1,17 +1,30 @@
 import copy
 import numpy
-from .gqrs import time_to_sample_number, Conf, Peak, Annotation
-from .basic import smooth
 
-def find_peaks(x):
-    # Definitions:
-    # * Hard peak: a peak that is either /\ or \/
-    # * Soft peak: a peak that is either /-*\ or \-*/ (In that cas we define the middle of it as the peak)
+from .basic import smooth
+from .gqrs import time_to_sample_number, Conf, Peak, Annotation
 
-    # Returns two numpy arrays:
-    # * hard_peaks contains the indices of the Hard peaks
-    # * soft_peaks contains the indices of the Soft peaks
 
+def find_peaks(x):
+    """
+    Find hard peaks and soft peaks in a signal, defined as follows:
+    - Hard peak: a peak that is either /\ or \/
+    - Soft peak: a peak that is either /-*\ or \-*/ (In that case we define the
+      middle of it as the peak)
+    
+    Parameters
+    ----------
+    x : numpy array
+        The signal array
+
+    Returns
+    -------
+    hard_peaks : numpy array
+        Array containing the indices of the hard peaks: 
+    soft_peaks : numpy array
+        Array containing the indices of the soft peaks
+    
+    """
     if len(x) == 0:
         return numpy.empty([0]), numpy.empty([0])
 
@@ -41,6 +54,8 @@ def find_peaks(x):
 
 
 def correct_peaks(x, peak_indices, min_gap, max_gap, smooth_window):
+    """
+    """
     N = x.shape[0]
 
     rpeaks = numpy.zeros(N)

wfdb/processing/peaks.py

@@ -1 +1 @@
-__version__ = '1.3.9'
+__version__ = '2.0.0'