minor API doc updates

doc/api/index.rst

@@ -3,9 +3,6 @@
 API Reference
 =============
 
-:Release: |version|
-:Date: |today|
-
 This guide provides documentation for all modules, function, methods,
 and classes within *tobac* for those in the public API.
 

doc/index.md

@@ -31,10 +31,11 @@ h3:not(#hero h3) {
 
 <div id="hero">
 
-<div id="hero-left">  <!-- Start Hero Left -->
+<div id="hero-left">  <!-- Left side of the hero section -->
   <h2 style="font-size: 60px; font-weight: bold; margin: 2rem auto 0;"><em>tobac</em></h2>
   <h3 style="font-weight: bold; margin-top: 0;">Tracking atmospheric phenomena with <em>your data</em></h3>
-  <p><em>tobac</em> is a package that identifies, tracks, and can be used for object-based analysis of atmospheric phenomena in model, observational, and remote sensing datasets.</p>
+  <p><em>tobac</em> (Tracking and Object-Based Analysis of Clouds) is a package that identifies and tracks 
+atmospheric phenomena, enabling object-based analysis in model, observational, and remote sensing datasets.</p>
 
 <div class="homepage-button-container">
   <div class="homepage-button-container-row">

tobac/feature_detection.py

@@ -1,6 +1,6 @@
-"""Provide feature detection.
+"""First step toward working with *tobac*. Detects features from input 2D or 3D data.
 
-This module can work with any two-dimensional field.
+This module can work with any two-dimensional or three-dimensional field.
 To identify the features, contiguous regions above or 
 below a threshold are determined and labelled individually.
 To describe the specific location of the feature at a 
@@ -625,9 +625,9 @@ def feature_detection_threshold(
                         # find the updated label, and overwrite all of label_ind indices with
                         # updated label
                         labels_2_alt = labels_2[label_z, y_val_alt, x_val_alt]
-                        labels_2[
-                            label_locs_v, label_locs_h1, label_locs_h2
-                        ] = labels_2_alt
+                        labels_2[label_locs_v, label_locs_h1, label_locs_h2] = (
+                            labels_2_alt
+                        )
                         skip_list = np.append(skip_list, label_ind)
                         break
 
@@ -671,9 +671,9 @@ def feature_detection_threshold(
                         # find the updated label, and overwrite all of label_ind indices with
                         # updated label
                         labels_2_alt = labels_2[label_z, y_val_alt, label_x]
-                        labels_2[
-                            label_locs_v, label_locs_h1, label_locs_h2
-                        ] = labels_2_alt
+                        labels_2[label_locs_v, label_locs_h1, label_locs_h2] = (
+                            labels_2_alt
+                        )
                         new_label_ind = labels_2_alt
                         skip_list = np.append(skip_list, label_ind)
 
@@ -715,9 +715,9 @@ def feature_detection_threshold(
                         # find the updated label, and overwrite all of label_ind indices with
                         # updated label
                         labels_2_alt = labels_2[label_z, label_y, x_val_alt]
-                        labels_2[
-                            label_locs_v, label_locs_h1, label_locs_h2
-                        ] = labels_2_alt
+                        labels_2[label_locs_v, label_locs_h1, label_locs_h2] = (
+                            labels_2_alt
+                        )
                         new_label_ind = labels_2_alt
                         skip_list = np.append(skip_list, label_ind)
 

tobac/utils/general.py

@@ -26,6 +26,8 @@ def add_coordinates(
     """Add coordinates from the input cube of the feature detection
     to the trajectories/features.
 
+    :meta private:
+
     Parameters
     ----------
     t : pandas.DataFrame
@@ -118,16 +120,19 @@ def add_coordinates_3D(
 
 
 def get_bounding_box(x, buffer=1):
-    """Finds the bounding box of a ndarray, i.e. the smallest
-    bounding rectangle for nonzero values as explained here:
+    """Finds the bounding box of a ndarray
+
+    This is the smallest bounding rectangle for nonzero values as explained here:
     https://stackoverflow.com/questions/31400769/bounding-box-of-numpy-array
+
     Parameters
     ----------
     x : numpy.ndarray
         Array for which the bounding box is to be determined.
     buffer : int, optional
         Number to set a buffer between the nonzero values and
         the edges of the box. Default is 1.
+
     Returns
     -------
     bbox : list
@@ -351,6 +356,9 @@ def combine_tobac_feats(list_of_feats, preserve_old_feat_nums=None):
     Function to combine a list of tobac feature detection dataframes
     into one combined dataframe that can be used for tracking
     or segmentation.
+
+    :meta private:
+
     Parameters
     ----------
     list_of_feats: array-like of Pandas DataFrames
@@ -386,6 +394,7 @@ def combine_feature_dataframes(
     """Function to combine a list of tobac feature detection dataframes
     into one combined dataframe that can be used for tracking
     or segmentation.
+
     Parameters
     ----------
     feature_df_list: array-like of Pandas DataFrames
@@ -617,16 +626,16 @@ def transform_feature_points(
 
 
 def standardize_track_dataset(TrackedFeatures, Mask, Projection=None):
-    """
+    """Combine a feature mask with the feature data table into a common dataset returned by tobac.segmentation
+
     CAUTION: this function is experimental. No data structures output are guaranteed to be supported in future versions of tobac.
-    Combine a feature mask with the feature data table into a common dataset.
-    returned by tobac.segmentation
     with the TrackedFeatures dataset returned by tobac.linking_trackpy.
     Also rename the variables to be more descriptive and comply with cf-tree.
     Convert the default cell parent ID  to an integer table.
     Add a cell dimension to reflect
     Projection is an xarray DataArray
     TODO: Add metadata attributes
+
     Parameters
     ----------
     TrackedFeatures : xarray.core.dataset.Dataset
@@ -649,6 +658,7 @@ def standardize_track_dataset(TrackedFeatures, Mask, Projection=None):
         longitude_of_prime_meridian :0.0
         false_easting :0.0
         false_northing :0.0
+
     Returns
     -------
     ds : xarray.core.dataset.Dataset