Updated docstrings and documentation

docs/source/demos/demo_allan.rst

@@ -122,4 +122,4 @@ ramp).
 
 
 Feel free to download a copy of this demo
-(:jupyter-download:script:`demo_allan`).
+(:jupyter-download-script:`demo_allan`).

docs/source/demos/demo_bouts.rst

@@ -269,4 +269,4 @@ type needs to be converted to total seconds to allow comparison with BEC.
    skbouts.label_bouts(postdives.dt.total_seconds(), bec, as_diff=True)
 
 Feel free to download a copy of this demo
-(:jupyter-download:script:`demo_bouts`).
+(:jupyter-download-script:`demo_bouts`).

docs/source/demos/demo_ellipsoid.rst

@@ -179,4 +179,4 @@ Or compare visually on a 3D plot:
 
 
 Feel free to download a copy of this demo
-(:jupyter-download:script:`demo_ellipsoid`).
+(:jupyter-download-script:`demo_ellipsoid`).

docs/source/demos/demo_imu2body.rst

@@ -289,4 +289,4 @@ Or with segment-specific rotations:
                             figsize=_FIG4X1);
 
 Feel free to download a copy of this demo
-(:jupyter-download:script:`demo_imu2body`).
+(:jupyter-download-script:`demo_imu2body`).

docs/source/demos/demo_simulbouts.rst

@@ -275,4 +275,4 @@ Compare cumulative frequency distributions:
    x_mle.plot_ecdf(fit2, ax=axs[1]);
 
 Feel free to download a copy of this demo
-(:jupyter-download:script:`demo_simulbouts`).
+(:jupyter-download-script:`demo_simulbouts`).

docs/source/demos/demo_tdr.rst

@@ -283,4 +283,4 @@ Dive stamps
    print(tdrX.stamp_dives())
 
 Feel free to download a copy of this demo
-(:jupyter-download:script:`demo_tdr`).
+(:jupyter-download-script:`demo_tdr`).

skdiveMove/__init__.py

@@ -45,12 +45,36 @@
    calibrate
    dump_config_template
 
+
+Detect and quantify periods of major activities in a TDR record,
+calibrating depth readings to generate summaries of diving behaviour. These
+procedures include wet/dry phase detection, zero-offset correction (ZOC) of
+depth, detection of dives, as well as proper labelling of the latter, among
+others utilities for the analysis of TDR records.
+
+All core procedures are encapsulated in :class:`TDR`, and are controlled by
+a set of user-defined variables in a configuration file, and systematically
+executed systematically by function :func:`calibrate`. This function can be
+used as a template for custom processing using different
+sequences. User-defined variables can also be directly specified as a
+dictionary, which is a class attribute. The standard approach follows the
+logical processing sequence described below:
+
+1. Zero-offset correction
+2. Detection of wet phases
+3. Detection of dives
+4. Detection of dive phases
+5. Speed calibration (if required)
+6. Calculation of statistics
+
+Class :class:`TDR` methods implement these steps.
+
 """
 
 from skdiveMove.tdr import TDR, calibrate
 from skdiveMove.calibconfig import dump_config_template
 
 __author__ = "Sebastian Luque <[email protected]>"
 __license__ = "AGPLv3"
-__version__ = "0.3.2"
+__version__ = "0.3.2.post1"
 __all__ = ["TDR", "calibrate", "dump_config_template"]

skdiveMove/helpers.py

@@ -20,7 +20,7 @@ def _load_dataset(filename_or_obj, **kwargs):
     filename_or_obj : str, Path or xarray.backends.*DataStore
         String indicating the file where the data comes from.
     **kwargs :
-        Arguments passed to `xarray.load_dataset`.
+        Keyword arguments passed to :func:`~xarray.load_dataset`.
 
     Returns
     -------
@@ -194,7 +194,6 @@ def _speed_stats(x, vdist=None):
     ----------
     x : pandas.Series
         Series with speed measurements.
-
     vdist : float, optional
         Vertical distance corresponding to `x`.
 

skdiveMove/imutools/imu.py

@@ -149,8 +149,9 @@ def read_netcdf(cls, imu_file,
             Whether input data include depth measurements.
         depth_name : str, optional
             Name of the depth ``DataArray`` in the ``Dataset``.
-        **kwargs : optional keyword arguments
-            Arguments passed to :func:`xarray.load_dataset`.
+        **kwargs
+            Optional keyword arguments passed to
+            :func:`xarray.load_dataset`.
 
         Returns
         -------
@@ -225,11 +226,11 @@ def allan_coefs(self, sensor, taus):
         deviation ``adevs``, compute the Allan deviation coefficient for
         each error type:
 
-        - Quantization
-        - (Angle, Velocity) Random Walk
-        - Bias Instability
-        - Rate Random Walk
-        - Rate Ramp
+          - Quantization
+          - (Angle, Velocity) Random Walk
+          - Bias Instability
+          - Rate Random Walk
+          - Rate Ramp
 
         Parameters
         ----------
@@ -289,22 +290,22 @@ def compute_orientation(self, method="Madgwick", **kwargs):
         The method must be one of the following estimators implemented in
         Python module :mod:`ahrs.filters`:
 
-        - ``AngularRate``: Attitude from angular rate
-        - ``AQUA``: Algebraic quaternion algorithm
-        - ``Complementary``: Complementary filter
-        - ``Davenport``: Davenport's q-method
-        - ``EKF``: Extended Kalman filter
-        - ``FAAM``: Fast accelerometer-magnetometer combination
-        - ``FLAE``: Fast linear attitude estimator
-        - ``Fourati``: Fourati's nonlinear attitude estimation
-        - ``FQA``: Factored quaternion algorithm
-        - ``Madgwick``: Madgwick orientation filter
-        - ``Mahony``: Mahony orientation filter
-        - ``OLEQ``: Optimal linear estimator quaternion
-        - ``QUEST``
-        - ``ROLEQ``: Recursive optimal linear estimator of quaternion
-        - ``SAAM``: Super-fast attitude from accelerometer and magnetometer
-        - ``Tilt``: Attitude from gravity
+          - ``AngularRate``: Attitude from angular rate
+          - ``AQUA``: Algebraic quaternion algorithm
+          - ``Complementary``: Complementary filter
+          - ``Davenport``: Davenport's q-method
+          - ``EKF``: Extended Kalman filter
+          - ``FAAM``: Fast accelerometer-magnetometer combination
+          - ``FLAE``: Fast linear attitude estimator
+          - ``Fourati``: Fourati's nonlinear attitude estimation
+          - ``FQA``: Factored quaternion algorithm
+          - ``Madgwick``: Madgwick orientation filter
+          - ``Mahony``: Mahony orientation filter
+          - ``OLEQ``: Optimal linear estimator quaternion
+          - ``QUEST``
+          - ``ROLEQ``: Recursive optimal linear estimator of quaternion
+          - ``SAAM``: Super-fast attitude from accelerometer and magnetometer
+          - ``Tilt``: Attitude from gravity
 
         The estimated quaternions are stored in the ``quats`` attribute.
 

skdiveMove/imutools/imu2body.py

@@ -83,8 +83,9 @@ def scatterIMU_svd(vectors, svd, R_ctr2i, normalize=False, center=False,
         Whether to animate the plot.
     animate_file : str, optional
         Output file for the animation.
-    **kwargs : optional keyword arguments
-        Arguments passed to `pyplot.figure` (e.g. ``figsize``).
+    **kwargs
+        Optional keyword arguments passed to
+        :func:`~matplotlib.pyplot.figure` (e.g. ``figsize``).
 
     Returns
     -------
@@ -175,8 +176,9 @@ def _scatterIMU_svd(vectors, svd, R_b2i, normalize=False, title=None,
         Whether to animate the plot.
     animate_file : str, optional
         Output file for the animation.
-    **kwargs : optional keyword arguments
-        Arguments passed to `pyplot.figure` (e.g. ``figsize``).
+    **kwargs
+        Optional keyword arguments passed to
+        :func:`~matplotlib.pyplot.figure` (e.g. ``figsize``).
 
     Returns
     -------
@@ -262,8 +264,9 @@ def scatterIMU3D(vectors, col_vector, normalize=True, title=None,
         Output file for the animation.
     cbar_label : str, optional
         Title for the color bar.
-    **kwargs : optional keyword arguments
-        Arguments passed to `pyplot.figure` (e.g. ``figsize``).
+    **kwargs
+        Optional keyword arguments passed to
+        :func:`~matplotlib.pyplot.figure` (e.g. ``figsize``).
 
     Returns
     -------
@@ -534,7 +537,7 @@ def from_csv_nc(cls, surface_details_csv, imu_nc, endasc_col=0,
 
         Returns
         -------
-        `IMU2Body`
+        IMU2Body
 
         """
         # Read CSV
@@ -764,12 +767,12 @@ def get_orientations(self):
             DataFrame indexed the by the rows of the surface details table,
             and having the following columns:
 
-            - ``R``: Rotation
-            - ``SVD``: SVD matrices
-            - ``quality``: Tuple (quality index, std) for the estimate
-            - ``phi``: Roll angle (degrees) from body to IMU frame
-            - ``theta``: Pitch angle (degrees) from body to IMU frame
-            - ``psi``: Yaw angle (degrees) from body to IMU frame
+              - ``R``: Rotation
+              - ``SVD``: SVD matrices
+              - ``quality``: Tuple (quality index, std) for the estimate
+              - ``phi``: Roll angle (degrees) from body to IMU frame
+              - ``theta``: Pitch angle (degrees) from body to IMU frame
+              - ``psi``: Yaw angle (degrees) from body to IMU frame
 
         See Also
         --------
@@ -1037,8 +1040,8 @@ def scatterIMU3D(self, surface_idx, vec_name, smoothed_accel=False,
         smoothed_accel : bool, optional
             Whether to plot the smoothed acceleration (if
             `vec_name="acceleration"`)
-        **kwargs : optional keyword arguments
-            Arguments passed to :meth:`scatterIMU3D`.
+        **kwargs
+            Optional keyword arguments passed to :meth:`scatterIMU3D`.
 
         Returns
         -------
@@ -1077,9 +1080,9 @@ def tsplotIMU_depth(self, vec_name, surface_idx=None,
         smoothed_accel : bool, optional
             Whether to plot the smoothed acceleration (if
             `vec_name="acceleration"`)
-        **kwargs : optional keyword arguments
-            Arguments passed to :func:`~matplotlib.pyplot.subplots`
-            (e.g. ``figsize``).
+        **kwargs
+            Optional keyword arguments passed to
+            :func:`~matplotlib.pyplot.subplots` (e.g. ``figsize``).
 
         Returns
         -------
@@ -1138,9 +1141,9 @@ def get_orientation(self, surface_idx, plot=True, **kwargs):
             Index in surface details table to be analyzed.
         plot : bool, optional
             Whether to generate a plot of the estimate
-        **kwargs : optional keyword arguments
-            Arguments passed to :meth:`scatterIMU_svd`.  Only ``title`` and
-            ``animate`` are taken.
+        **kwargs
+            Optional keyword arguments passed to :meth:`scatterIMU_svd`.
+            Only ``title`` and ``animate`` are taken.
 
         Returns
         -------

skdiveMove/imutools/imucalibrate.py

@@ -151,8 +151,9 @@ def __init__(self, x_calib, periods, axis_order=list("xyz"),
             List of characters specifying which axis ``x``, ``y``, or ``z``
             was pointing in the same direction as gravity in each period in
             ``periods``.
-        **kwargs : optional keyword arguments
-            Arguments passed to the `IMUBase.__init__` for instantiation.
+        **kwargs
+            Optional keyword arguments passed to the `IMUBase.__init__` for
+            instantiation.
 
         """
         super(IMUcalibrate, self).__init__(x_calib, **kwargs)
@@ -183,10 +184,11 @@ def read_netcdf(cls, imu_nc, load_dataset_kwargs=dict(), **kwargs):
         load_dataset_kwargs : dict, optional
             Dictionary of optional keyword arguments passed to
             :func:`xarray.load_dataset`.
-        **kwargs : optional keyword arguments
-            Additional arguments passed to :meth:`IMUcalibrate.__init__`
-            method, except ``has_depth`` or ``imu_filename``.  The input
-            ``Dataset`` is assumed to have a depth ``DataArray``.
+        **kwargs
+            Additional keyword arguments passed to
+            :meth:`IMUcalibrate.__init__` method, except ``has_depth`` or
+            ``imu_filename``.  The input ``Dataset`` is assumed to have a
+            depth ``DataArray``.
 
         Returns
         -------
@@ -245,7 +247,8 @@ def savgol_filter(self, var, period_idx, win_len, polyorder=1):
 
     def build_tmodels(self, var, T_alpha=None, T_brk=None,
                       use_axis_order=False, filter_sig=True, **kwargs):
-        r"""Build temperature models for experimental tri-axial IMU sensor signals
+        r"""Build temperature models for experimental tri-axial IMU sensor
+        signals
 
         Perform thermal compensation on *motionless* tri-axial IMU sensor
         data.  A simple approach is used for the compensation:
@@ -285,26 +288,26 @@ def build_tmodels(self, var, T_alpha=None, T_brk=None,
             correction.  Default is to apply a Savitzky-Golay filter to the
             signal for characterizing the temperature relationship, and to
             calculate the standardized signal.
-        **kwargs : optional keyword arguments
-            Arguments passed to `savgol_filter` (e.g. ``win_len`` and
-            ``polyorder``).
+        **kwargs
+            Optional keyword arguments passed to `savgol_filter`
+            (e.g. ``win_len`` and ``polyorder``).
 
         Returns
         -------
         list
             List of tuples as long as there are periods, with tuple elements:
 
-            - Dictionary with regression model objects for each sensor
-              axis.
-            - DataFrame with hierarchical column index with sensor axis
-              label at the first level.  The following columns are in the
-              second level:
+              - Dictionary with regression model objects for each sensor
+                axis.
+              - DataFrame with hierarchical column index with sensor axis
+                label at the first level.  The following columns are in the
+                second level:
 
-              - temperature
-              - var_name
-              - var_name_pred
-              - var_name_temp_refC
-              - var_name_adj
+                  - temperature
+                  - var_name
+                  - var_name_pred
+                  - var_name_temp_refC
+                  - var_name_adj
 
         Notes
         -----
@@ -437,9 +440,9 @@ def plot_experiment(self, period_idx, var, units_label=None, **kwargs):
         units_label : str, optional
             Label for the units of the chosen variable.  Defaults to the
             "units_label" attribute available in the DataArray.
-        **kwargs : optional keyword arguments
-            Arguments passed to :func:`~matplotlib.pyplot.subplots`
-            (e.g. ``figsize``).
+        **kwargs
+            Optional keyword arguments passed to
+            :func:`~matplotlib.pyplot.subplots` (e.g. ``figsize``).
 
         Returns
         -------
@@ -540,9 +543,9 @@ def plot_var_model(self, var, use_axis_order=True, units_label=None,
             "units_label" attribute available in the DataArray.
         axs : array_like, optional
             Array of Axes instances to plot in.
-        **kwargs : optional keyword arguments
-            Arguments passed to :func:`~matplotlib.pyplot.subplots`
-            (e.g. ``figsize``).
+        **kwargs
+            Optional keyword arguments passed to
+            :func:`~matplotlib.pyplot.subplots` (e.g. ``figsize``).
 
         Returns
         -------
@@ -669,9 +672,9 @@ def plot_standardized(self, var, use_axis_order=True, units_label=None,
             the plot for reference.
         axs : array_like, optional
             Array of Axes instances to plot in.
-        **kwargs : optional keyword arguments
-            Arguments passed to :func:`~matplotlib.pyplot.subplots`
-            (e.g. ``figsize``).
+        **kwargs
+            Optional keyword arguments passed to
+            :func:`~matplotlib.pyplot.subplots` (e.g. ``figsize``).
 
         Returns
         -------