Add ability to detect "families"

doc/api/index.rst

@@ -17,9 +17,11 @@ Documentation is broken down by directory and module.
    tracking
    segmentation
    merge_split
+   merge_split.families
    utils.bulk_statistics
    utils.general
    plotting
    analysis.cell_analysis
    analysis.feature_analysis
    analysis.spatial
+

doc/conf.py

@@ -182,6 +182,7 @@ def setup(app):
     "examples/Basics/Methods-and-Parameters-for-Feature-Detection_Part_2": "_static/thumbnails/Basics_Methods-and-Parameters-for-Feature-Detection_Part_2_Thumbnail.png",
     "examples/Basics/Methods-and-Parameters-for-Linking": "_static/thumbnails/Basics_Methods-and-Parameters-for-Linking_Thumbnail.png",
     "examples/Basics/Methods-and-Parameters-for-Segmentation": "_static/thumbnails/Basics_Methods-and-Parameters-for-Segmentation_Thumbnail.png",
+    "examples/Basics/Idealized-Family-Detection": "_static/thumbnails/Idealized-Family-Detection_Thumbnail.png",
     "examples/Example_OLR_Tracking_model/Example_OLR_Tracking_model": "_static/thumbnails/Example_OLR_Tracking_model_Thumbnail.png",
     "examples/Example_OLR_Tracking_satellite/Example_OLR_Tracking_satellite": "_static/thumbnails/Example_OLR_Tracking_satellite_Thumbnail.png",
     "examples/Example_Precip_Tracking/Example_Precip_Tracking": "_static/thumbnails/Example_Precip_Tracking_Thumbnail.png",

doc/getting_started/family_detection.md

@@ -0,0 +1,21 @@
+# Families
+
+Features ({doc}`/userguide/feature_detection/index`) are the *base unit* of *tobac*. However, sometimes you want to identify how features interact together. **Families** are the way to do this. Families aggregate features, allowing one to link features together spatially. 
+
+## Family Examples
+- Identifying individual convective cores (features) within a broader MCS (family)
+- Identifying individual updrafts (features) within a single cloud (family)
+
+## Algorithm Basics
+You can either detect families from data ({py:func}`tobac.merge_split.families.identify_feature_families_from_data`) or from segmentation output ({py:func}`tobac.merge_split.families.identify_feature_families_from_segmentation`). Similar to segmentation, families are identified based on a single threshold when detected from data (defined by {py:code}`threshold`), but it does *not* need to be the same field that you detect the features on[^3dcaveat].
+
+## Family Example Notebooks
+
+```{nblinkgallery}
+:caption: Jupyter Notebook Examples
+
+../examples/Basics/Idealized-Family-Detection.ipynb
+```
+
+
+[^3dcaveat]: Although, you cannot currently project 2D features to 3D families.

doc/getting_started/index.md

@@ -11,6 +11,7 @@ feature_detection_overview
 tracking_basics
 segmentation
 merge_split
+family_detection
 plotting
 get_help
 ```

doc/userguide/families/family_detection.md

@@ -0,0 +1,23 @@
+# Families
+
+As described in Getting Started ({doc}`/getting_started/family_detection`), features ({doc}`/userguide/feature_detection/index`) are the *base unit* of *tobac*, whereas **families** stitch multiple *features* together. Families aggregate features, allowing one to link features together spatially. 
+
+One can think about *families* as a kind of spatial clustering, although at the moment not using any preexisting clustering methods. As with every other method in *tobac*, family detection is modular, meaning that you can choose to use it or not.  
+
+## Family Examples
+- Identifying individual convective cores (features) within a broader MCS (family)
+- Identifying individual updrafts (features) within a single cloud (family)
+
+## Algorithm Basics
+You can either detect families from data ({py:func}`tobac.merge_split.families.identify_feature_families_from_data`) or from segmentation output ({py:func}`tobac.merge_split.families.identify_feature_families_from_segmentation`). Similar to segmentation, families are identified based on a single threshold when detected from data (defined by {py:code}`threshold`), but it does *not* need to be the same field that you detect the features on[^3dcaveat].
+
+## Family Example Notebooks
+
+```{nblinkgallery}
+:caption: Jupyter Notebook Examples
+
+../examples/Basics/Idealized-Family-Detection.ipynb
+```
+
+
+[^3dcaveat]: Although, you cannot currently project 2D features to 3D families.