Improve documentation

docs/conf.py

@@ -65,7 +65,7 @@ def __getattr__(cls, name):
 master_doc = 'index'
 
 # General information about the project.
-project = 'sensormotion'
+project = 'Sensor Motion'
 copyright = '2018, Simon Ho'
 author = 'Simon Ho'
 
@@ -96,6 +96,12 @@ def __getattr__(cls, name):
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
+# If true, the current module name will be prepended to all description
+# unit titles (such as .. function::).
+add_module_names = False
+
+add_function_parentheses = True
+
 
 # -- Options for HTML output ----------------------------------------------
 

docs/index.rst

@@ -4,7 +4,7 @@
    contain the root `toctree` directive.
 
 Sensor Motion
-=============
+-------------
 
 .. toctree::
    :maxdepth: 2
@@ -13,8 +13,8 @@ Sensor Motion
 .. include:: ../README.rst
    :start-after: inclusion-marker-main-readme
 
-Indices and tables
-==================
+Index & Modules
+---------------
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/source/sensormotion.rst

@@ -1,16 +1,10 @@
-sensormotion package
-====================
-
-Module contents
----------------
-
 .. automodule:: sensormotion
     :members:
     :undoc-members:
     :show-inheritance:
 
-Submodules
-----------
+Module Reference
+================
 
 sensormotion\.gait module
 -------------------------

sensormotion/__init__.py

@@ -1,6 +1,6 @@
 """
-sensormotion
-============
+Sensor Motion
+=============
 
 Provides tools for analyzing sensor-collected human motion data. This
 includes, for example, estimation of gait dynamics from accelerometer data,
@@ -11,8 +11,8 @@
 This package was primarily developed for use on Android sensor data collected
 at the Attentional Neuroscience Lab (University of British Columbia).
 
-Documentation
--------------
+Accessing Documentation
+-----------------------
 Documentation is available via docstrings provided with the code, and an
 online API reference found at
 `ReadTheDocs <http://sensormotion.readthedocs.io>`_.
@@ -29,19 +29,19 @@
 
   >>> help(sm.peak.find_peaks)
 
-Modules
--------
-gait
+Package Overview
+----------------
+gait module
     Calculate various types of gait dynamics (cadence, symmetry etc.)
-pa
+pa module
     Calculate physical activity (PA) levels with conversion to activity counts
-peak
+peak module
     Detect peaks and valleys in a signal
-plot
+plot module
     Wrapper functions for creating simple graphs
-signal
+signal module
     Signal processing tools such as filtering and cross-correlation
-utils
+utils module
     General utility functions used throughout the package
 """
 

sensormotion/gait.py

@@ -29,8 +29,8 @@ def cadence(time, peak_times, time_units='ms'):
         Time vector of the original acceleration signal. Used to calculate
         duration of the input signal.
     peak_times : ndarray
-        Time of each peak, returned by :func:`peak.find_peaks`. This provides
-        the number of steps within the timeframe of the signal.
+        Time of each peak, returned by :func:`sensormotion.peak.find_peaks`.
+        This provides the number of steps within the timeframe of the signal.
     time_units : {'ms', 's'}, optional
         Units of the time signal.
 
@@ -62,7 +62,7 @@ def step_count(peak_times):
     Parameters
     ----------
     peak_times : ndarray
-        Times of the peaks detected by :func:`peak.find_peaks`.
+        Times of the peaks detected by :func:`sensormotion.peak.find_peaks`.
 
     Returns
     -------
@@ -85,38 +85,41 @@ def step_regularity(autocorr_peak_values):
     If calculating regularity from acceleration in the vertical axis, this
     function receives the detected peaks from the vertical axis
     autocorrelation.
+
     However, if calculating regularity from lateral axis
     acceleration, you should pass in *both* peaks and valleys from the
     autocorrelation of the lateral axis.
 
-    Step regularity:
+    **Step regularity:**
+
+    Perfect step regularity will be 1.0 for vertical axis autocorrelation
+    (the larger the better, capped at 1.0).
 
-    Perfect step regularity will be `1.0` for vertical axis autocorrelation
-    (the larger the better, capped at `1.0`).
-    For the lateral axis, perfect regularity is `-1.0` (the smaller the
-    better, capped at `-1.0`).
+    For the lateral axis, perfect regularity is -1.0 (the smaller the
+    better, capped at -1.0).
 
-    Stride regularity:
+    **Stride regularity:**
 
-    Perfect stride regularity will be `1.0` for vertical axis autocorrelation
+    Perfect stride regularity will be 1.0 for vertical axis autocorrelation
     (the larger the better, capped at 1.0).
+
     Lateral axis sign and interpretation are the same as the vertical axis.
 
     Parameters
     ----------
     autocorr_peak_values : ndarray
         Values of the autocorrelation peaks/valleys detected by
-        :func:`peak.find_peaks`. This should contain only peak values when
-        looking at the vertical axis, and both peak and valley values when
-        looking at the lateral axis.
+        :func:`sensormotion.peak.find_peaks`. This should contain only peak
+        values when looking at the vertical axis, and both peak and valley
+        values when looking at the lateral axis.
 
     Returns
     -------
     step_reg : float
-        Step regularity. Value is capped at `1.0` or `-1.0` depending on the
+        Step regularity. Value is capped at 1.0 or -1.0 depending on the
         axis of interest.
     stride_reg : float
-        Stride regularity. Capped at `1.0` for both vertical and lateral axes.
+        Stride regularity. Capped at 1.0 for both vertical and lateral axes.
     """
 
     peaks_half = autocorr_peak_values[autocorr_peak_values.size//2:]
@@ -141,27 +144,29 @@ def step_symmetry(autocorr_peak_values):
     If calculating symmetry from acceleration in the vertical axis, this
     function receives the detected peaks from the vertical axis
     autocorrelation.
+
     However, if calculating symmetry from lateral axis
     acceleration, you should pass in *both* peaks and valleys from the
     autocorrelation of the lateral axis.
 
-    Perfect step symmetry is `1.0` for the vertical axis - larger values are
-    more symmetric, capped at `1.0`.
-    Perfect step symmetry is `-1.0` for the lateral axis - smaller values are
-    more symmetric, capped at `-1.0`.
+    Perfect step symmetry is 1.0 for the vertical axis - larger values are
+    more symmetric, capped at 1.0.
+
+    Perfect step symmetry is -1.0 for the lateral axis - smaller values are
+    more symmetric, capped at -1.0.
 
     Parameters
     ----------
     autocorr_peak_values : ndarray
         Values of the autocorrelation peaks/valleys detected by
-        :func:`peak.find_peaks`. This should contain only peak values when
-        looking at the vertical axis, and both peak and valley values when
-        looking at the lateral axis.
+        :func:`sensormotion.peak.find_peaks`. This should contain only peak
+        values when looking at the vertical axis, and both peak and valley
+        values when looking at the lateral axis.
 
     Returns
     -------
     step_sym : float
-        Step symmetry. Value is capped at `1.0` or `-1.0` depending on the
+        Step symmetry. Value is capped at 1.0 or -1.0 depending on the
         axis of interest.
     """
 
@@ -190,7 +195,7 @@ def step_time(peak_times):
     Parameters
     ----------
     peak_times : ndarray
-        Times of the peaks detected by :func:`peak.find_peaks`.
+        Times of the peaks detected by :func:`sensormotion.peak.find_peaks`.
 
     Returns
     -------
@@ -199,7 +204,7 @@ def step_time(peak_times):
     step_time_sd : float
         Standard deviation of the distribution of step times in the signal.
     step_time_cov : float
-        Coefficient of variation. Calculated as `sd/mean`.
+        Coefficient of variation. Calculated as sd/mean.
     """
 
     peak_time_differences = np.diff(peak_times)

sensormotion/peak.py

@@ -34,7 +34,8 @@ def find_peaks(time, signal, peak_type='peak', min_val=0.5, min_dist=25,
     peak_type : {'peak', 'valley', 'both'}, optional
         Type of peaks to be detected. `peak` will return positive peaks.
         `valley` will return negative peaks. `both` will return both peaks and
-        valleys. Peak indices are calculated by calling :func:`peak.indexes`.
+        valleys. Peak indices are calculated by calling
+        :func:`sensormotion.peak.indexes`.
     min_val : float between [0., 1.], optional
         Normalized threshold. Only the peaks with amplitude higher than the
         threshold will be detected.
@@ -46,7 +47,7 @@ def find_peaks(time, signal, peak_type='peak', min_val=0.5, min_dist=25,
         degree may fail to detect all the baseline present, while a high
         degree may make the data too oscillatory, especially at the edges. A
         value of 0 will not apply any baseline detrending. The baseline for
-        detrending is calculated by :func:`signal.baseline`.
+        detrending is calculated by :func:`sensormotion.signal.baseline`.
     plot : bool, optional
         Toggle to create a plot of the signal with peaks/valleys overlaid.
     show_grid : bool, optional

sensormotion/plot.py

@@ -96,8 +96,7 @@ def plot_signal(time, signal, title='', xlab='', ylab='',
                                            'color': 'b'},
                                           {'data': line2_data,
                                            'label': 'second line',
-                                           'line_Width': 4}]
-                            )
+                                           'line_Width': 4}])
     title : str, optional
         Title of the plot.
     xlab : str, optional

sensormotion/signal.py

@@ -136,7 +136,7 @@ def detrend_signal(signal, degree):
         degree may fail to detect all the baseline present, while a high
         degree may make the data too oscillatory, especially at the edges. A
         value of 0 will not apply any baseline detrending. The baseline for
-        detrending is calculated by :func:`signal.baseline`.
+        detrending is calculated by :func:`sensormotion.signal.baseline`.
 
     Returns
     -------
@@ -206,9 +206,10 @@ def filter_signal(b, a, signal):
     """
     Filter a signal.
 
-    Simple wrapper around `scipy.signal.filtfilt()` to apply a
+    Simple wrapper around :func:`scipy.signal.filtfilt` to apply a
     foward-backward filter to preserve phase of the input. Requires the
-    numerator and denominator polynomials from :func:`signal.build_filter`.
+    numerator and denominator polynomials from
+    :func:`sensormotion.signal.build_filter`.
 
     Parameters
     ----------

setup.py

@@ -7,7 +7,7 @@ def readme():
 
 
 setup(name='sensormotion',
-      version='1.0.2',
+      version='1.0.3',
       description='Python package for analyzing sensor-collected human motion '
                   'data (e.g. physical activity levels, gait dynamics)',
       long_description=readme(),