diff --git a/doc/api/index.rst b/doc/api/index.rst index c7eac6c2..0c47e1a3 100644 --- a/doc/api/index.rst +++ b/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. diff --git a/doc/index.md b/doc/index.md index 2c630587..df7423e6 100644 --- a/doc/index.md +++ b/doc/index.md @@ -31,10 +31,11 @@ h3:not(#hero h3) {
-
+

tobac

Tracking atmospheric phenomena with your data

-

tobac is a package that identifies, tracks, and can be used for object-based analysis of atmospheric phenomena in model, observational, and remote sensing datasets.

+

tobac (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.

diff --git a/tobac/feature_detection.py b/tobac/feature_detection.py index 77efa198..1da900ac 100644 --- a/tobac/feature_detection.py +++ b/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) diff --git a/tobac/utils/general.py b/tobac/utils/general.py index 88482c17..51d3af60 100644 --- a/tobac/utils/general.py +++ b/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,9 +120,11 @@ 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 @@ -128,6 +132,7 @@ def get_bounding_box(x, buffer=1): 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