From aa2f5a6addd7e79fc13cb7239d3b9ea4b89e7110 Mon Sep 17 00:00:00 2001
From: Ross Markello <rossmarkello@gmail.com>
Date: Sun, 16 Sep 2018 22:46:41 -0400
Subject: [PATCH] [DOC] Beefs up module doc-strings

---
 peakdet/__init__.py   |  3 ++-
 peakdet/analytics.py  | 26 +++++++++++++++++++
 peakdet/editor.py     |  3 +++
 peakdet/external.py   |  7 +++--
 peakdet/io.py         | 28 +++++++++++++++++---
 peakdet/operations.py | 59 ++++++++++++++++++++++++++++++-------------
 peakdet/physio.py     | 19 +++++++++++++-
 peakdet/utils.py      |  4 +++
 8 files changed, 124 insertions(+), 25 deletions(-)

diff --git a/peakdet/__init__.py b/peakdet/__init__.py
index 0391842..cea6447 100644
--- a/peakdet/__init__.py
+++ b/peakdet/__init__.py
@@ -1,7 +1,7 @@
 __all__ = [
     'edit_physio', 'filter_physio', 'interpolate_physio', 'peakfind_physio',
     'plot_physio', 'load_physio', 'save_physio', 'load_history',
-    'save_history', 'load_rtpeaks', '__version__'
+    'save_history', 'load_rtpeaks', 'Physio', '__version__'
 ]
 
 from peakdet.info import (__version__)
@@ -9,3 +9,4 @@
                                 peakfind_physio, plot_physio)
 from peakdet.io import (load_physio, save_physio, load_history, save_history)
 from peakdet.external import (load_rtpeaks)
+from peakdet.physio import (Physio)
diff --git a/peakdet/analytics.py b/peakdet/analytics.py
index 400d56b..406f10c 100644
--- a/peakdet/analytics.py
+++ b/peakdet/analytics.py
@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+Functions and classes for generating analytics on physiological data
+"""
 
 import numpy as np
 from scipy.signal import welch
@@ -12,6 +15,29 @@ class HRV():
     Parameters
     ----------
     data : Physio_like
+        Physiological data object with previously detected peaks and troughs
+
+    Attributes
+    ----------
+    rrtime : :obj:`numpy.ndarray`
+    rrint : :obj:`numpy.ndarray`
+    avgnn : float
+    sdnn : float
+    rmssd : float
+    sdsd : float
+    nn50 : float
+    pnn50 : float
+    nn20 : float
+    pnn20 : float
+    hf : float
+    hf_log : float
+    lf : float
+    lf_log : float
+    vlf : float
+    vlf_log : float
+    lftohf : float
+    hf_peak : float
+    lf_peak : float
 
     Notes
     -----
diff --git a/peakdet/editor.py b/peakdet/editor.py
index 2baf0e7..f199736 100644
--- a/peakdet/editor.py
+++ b/peakdet/editor.py
@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+Functions and class for performing interactive editing of physiological data
+"""
 
 import itertools
 import numpy as np
diff --git a/peakdet/external.py b/peakdet/external.py
index 70dda70..1d0b660 100644
--- a/peakdet/external.py
+++ b/peakdet/external.py
@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+Functions for interacting with physiological data acquired by external packages
+"""
 
 import warnings
 import numpy as np
@@ -7,7 +10,7 @@
 
 def load_rtpeaks(fname, channel, fs):
     """
-    Loads data file as obtained from the `rtpeaks` Python module
+    Loads data file as obtained from the ``rtpeaks`` Python module
 
     Data file `fname` should have a single, comma-delimited header of format:
 
@@ -29,7 +32,7 @@ def load_rtpeaks(fname, channel, fs):
 
     Returns
     -------
-    data : Physio_like
+    data : :class:`peakdet.Physio`
         Loaded physiological data
     """
 
diff --git a/peakdet/io.py b/peakdet/io.py
index 737970d..a3bb64b 100644
--- a/peakdet/io.py
+++ b/peakdet/io.py
@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+Functions for loading and saving data and analyses
+"""
 
 import json
 import warnings
@@ -18,11 +21,13 @@ def load_physio(data, *, fs=None, dtype=None, history=None):
         Sampling rate of `data`. Default: None
     dtype : data_type, optional
         Data type to convert `data` to, if conversion needed. Default: None
+    history : list of tuples, optional
+        Functions that have been performed on `data`. Default: None
 
     Returns
     -------
-    data: peakdet.Physio
-        Loaded physio object
+    data: :class:`peakdet.Physio`
+        Loaded physiological data
 
     Raises
     ------
@@ -76,10 +81,15 @@ def save_physio(file, data):
 
     Parameters
     ----------
-    fname : str
+    file : str
         Path to output file; .phys will be appended if necessary
     data : Physio_like
         Data to be saved to file
+
+    Returns
+    -------
+    file : str
+        Full filepath to saved output
     """
 
     from peakdet.utils import check_physio
@@ -104,6 +114,11 @@ def load_history(file, verbose=False):
         Path to input JSON file
     verbose : bool, optional
         Whether to print messages as history is being replayed. Default: False
+
+    Returns
+    -------
+    file : str
+        Full filepath to saved output
     """
 
     # import inside function for safety!
@@ -140,10 +155,15 @@ def save_history(file, data):
 
     Parameters
     ----------
-    fname : str
+    file : str
         Path to output file; .json will be appended if necessary
     data : Physio_like
         Data with history to be saved to file
+
+    Returns
+    -------
+    file : str
+        Full filepath to saved output
     """
 
     from peakdet.utils import check_physio
diff --git a/peakdet/operations.py b/peakdet/operations.py
index 5f9abbd..b363ee3 100644
--- a/peakdet/operations.py
+++ b/peakdet/operations.py
@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+Functions for processing and interpreting physiological data
+"""
 
 import matplotlib.pyplot as plt
 import numpy as np
@@ -14,21 +17,21 @@ def filter_physio(data, cutoffs, method, order=3):
     Parameters
     ----------
     data : Physio_like
-        Input data to be filtered
+        Input physiological data to be filtered
     cutoffs : int or list
         If `method` is 'lowpass' or 'highpass', an integer specifying the lower
         or upper bound of the filter (in Hz). If method is 'bandpass' or
-        'bandstop', a list specifying the lower _and_ upper bound of the filter
+        'bandstop', a list specifying the lower and upper bound of the filter
         (in Hz).
     method : {'lowpass', 'highpass', 'bandpass', 'bandstop'}
-        The type of filter to apply to `data`.
+        The type of filter to apply to `data`
     order : int, optional
         Order of filter to be applied. Default: 3
 
     Returns
     -------
-    filtered : peakdet.Physio
-        Filtered input data
+    filtered : :class:`peakdet.Physio`
+        Filtered input `data`
     """
 
     _valid_methods = ['lowpass', 'highpass', 'bandpass', 'bandstop']
@@ -68,14 +71,14 @@ def interpolate_physio(data, target_fs):
     Parameters
     ----------
     data : Physio_like
-        Input data to be interpolated
+        Input physiological data to be interpolated
     target_fs : float
         Desired sampling rate for `data`
 
     Returns
     -------
-    interp : peakdet.Physio
-        Interpolated input data
+    interp : :class:`peakdet.Physio`
+        Interpolated input `data`
     """
 
     data = utils.check_physio(data, ensure_fs=True)
@@ -97,18 +100,23 @@ def interpolate_physio(data, target_fs):
 
 def peakfind_physio(data, *, thresh=0.2, dist=None):
     """
-    Finds peaks in `data`
+    Performs peak and trough detection on `data`
 
     Parameters
     ----------
     data : Physio_like
         Input data in which to find peaks
     thresh : float [0,1], optional
-        Relative height threshold data must surpass to be classified as a
-        peak. Default: 0.2
+        Relative height threshold a data point must surpass to be classified as
+        a peak. Default: 0.2
     dist : int, optional
-        Distance (in indices) that peaks must be separated by. If not
-        specified, this is estimated from data.
+        Distance in indices that peaks must be separated by in `data`. If None,
+        this is estimated. Default: None
+
+    Returns
+    -------
+    peaks : :class:`peakdet.Physio`
+        Input `data` with detected peaks and troughs
     """
 
     ensure_fs = True if dist is None else False
@@ -130,12 +138,23 @@ def peakfind_physio(data, *, thresh=0.2, dist=None):
 
 def edit_physio(data, *, delete=None, reject=None):
     """
-    Returns interactive physio editor for `data`
+    Opens interactive plot with `data` to permit manual editing of time series
 
     Parameters
     ----------
     data : Physio_like
         Physiological data to be edited
+    delete : array_like, optional
+        List or array of indices to delete from peaks associated with `data`.
+        Default: None
+    reject : array_like, optional
+        List or array of indices to reject from peaks associated with `data`.
+        Default: None
+
+    Returns
+    -------
+    edited : :class:`peakdet.Physio`
+        Input `data` with manual (or specified) edits
     """
 
     # check if we need fs info
@@ -167,14 +186,20 @@ def edit_physio(data, *, delete=None, reject=None):
 
 def plot_physio(data, *, ax=None):
     """
-    Small utility for plotting `data` with any detected peaks / troughs
+    Plots `data` and associated peaks / troughs
 
     Parameters
     ----------
     data : Physio_like
         Physiological data to plot
-    ax : matplotlib.axes.Axis, optional
-        Axis to plot `data` on. Default: None
+    ax : :class:`matplotlib.axes.Axes`, optional
+        Axis on which to plot `data`. If None, a new axis is created. Default:
+        None
+
+    Returns
+    -------
+    ax : :class:`matplotlib.axes.Axes`
+        Axis with plotted `data`
     """
 
     # generate x-axis time series
diff --git a/peakdet/physio.py b/peakdet/physio.py
index 4af4387..a3d0bca 100644
--- a/peakdet/physio.py
+++ b/peakdet/physio.py
@@ -1,4 +1,7 @@
 # -*- coding: utf-8 -*-
+"""
+Helper class for holding physiological data and associated metadata inforamtion
+"""
 
 import numpy as np
 from sklearn.utils import Bunch
@@ -6,7 +9,7 @@
 
 class Physio():
     """
-    Helper class to hold physiological data and associated metadata
+    Class to hold physiological data and relevant information
 
     Parameters
     ----------
@@ -18,6 +21,20 @@ class Physio():
         Functions performed on `data`. Default: None
     metadata : dict, optional
         Metadata associated with `data`. Default: None
+
+    Attributes
+    ----------
+    data : :obj:`numpy.ndarray`
+        Physiological waveform
+    fs : float
+        Sampling rate of `data` in Hz
+    history : list of tuples
+        History of functions that have been performed on `data`, with relevant
+        parameters provided to functions.
+    peaks : :obj:`numpy.ndarray`
+        Indices of peaks in `data`
+    troughs : :obj:`numpy.ndarray`
+        Indices of troughs in `data`
     """
 
     def __init__(self, data, fs=None, history=None, metadata=None):
diff --git a/peakdet/utils.py b/peakdet/utils.py
index 8be2e48..8487a63 100644
--- a/peakdet/utils.py
+++ b/peakdet/utils.py
@@ -1,4 +1,8 @@
 # -*- coding: utf-8 -*-
+"""
+Various utilities for processing physiological data. These should not be called
+directly but should support wrapper functions stored in `peakdet.operations`.
+"""
 
 import inspect
 import numpy as np