Update notebooks and docstrings

intertidal/elevation.py

@@ -1241,8 +1241,8 @@ def intertidal_cli(
             dem=ds.elevation,
             freq=ds.qa_ndwi_freq,
             corr=ds.qa_ndwi_corr,
-            urban_mask=urban_mask,
             coastal_mask=coastal_mask,
+            urban_mask=urban_mask,
         )
 
         if exposure_offsets:

intertidal/extents.py

@@ -249,86 +249,61 @@ def load_gmw_mask(ds, gmw_path="/gdata1/data/mangroves/gmw_v3_2007_vec_aus.geojs
     return gmw_da
 
 
-
-
-
-
-
-# TODO: pass in ACLUM and connectivity mask directly
-
-
 def extents(
-    dem, freq, corr, urban_mask, coastal_mask, buffer=20000, min_correlation=0.15, sieve_size=5, **connectivity_kwargs
+    dem, freq, corr, coastal_mask, urban_mask, min_correlation=0.15, sieve_size=5
 ):
     """
-    Classify coastal ecosystems into broad classes based
-    on their respective patterns of wetting frequency,
-    proximity to the ocean, and relationships to tidal
-    inundation, elevation and urban land use (to mask
-    misclassifications).
-
-    Parameters:
-    -----------
-    dc : Datacube
-        A Datacube instance for loading data.
-    ds : xarray.Dataset
-        An xarray.Dataset that must include xarray.DataArrays for
-        at least 'elevation', 'qa_ndwi_freq' and 'qa_ndwi_corr'.
-        These arrays are generated as an output from the
+    Classify coastal ecosystems into broad classes based on
+    wetting frequency, proximity to ocean, and relationships
+    to tidal inundation, elevation, and urban land use.
+
+    Parameters
+    ----------
+    dem : xarray.DataArray
+        An intertidal Digital Elevation Model, as produced by
+        the `intertidal.elevation` algorithm.
+    freq : xarray.DataArray
+        Frequency of wetness for each pixel, generated by the
         `intertidal.elevation` algorithm.
-    buffer : int, optional
-        The distance by which to buffer the `ds` GeoBox to reduce edge
-        effects. This buffer will eventually be removed and clipped back
-        to the original GeoBox extent. Defaults to 20,000 metres.
-    min_correlation : int, optional
+    corr : xarray.DataArray
+        Correlation data between water index and tide height,
+        as generated by the `intertidal.elevation` algorithm.
+    coastal_mask : xarray.DataArray
+        A boolean mask identifying likely coastal pixels. This
+        is used to separate inland vs. ocean and coastal waters.
+        For Australia, this is obtained using the
+        `intertidal.extents.load_connectivity_mask` function,
+        which uses cost-distance modelling to identify likely
+        coastal pixels.
+    urban_mask : xarray.DataArray
+        A boolean mask identifying urban pixels that are applied
+        to remove false positive water observations over urban
+        areas. For Australia, this is obtained using the
+        `intertidal.io.load_aclum_mask` function.
+    min_correlation : float, optional
         Minimum correlation between water index and tide height
-        required for a pixel to be included in the intertidal pixel
-        analysis, 0.15 by default, aligning with the default value
-        used in the `intertidal.elevation` algorithm.
+        for identifying low confidence intertidal pixels. Default
+        is 0.15.
     sieve_size : int, optional
-        Maximum number of grouped pixels belonging to any single
-        class that are sieved out to remove small noisy dataset
-        features. Class values are replaced with the dominant
-        neighbouring class.
-    **connectivity_kwargs :
-        Optional keyword arguments to pass to `load_connectivity_mask`.
-
-    Returns:
-    --------
-    extents: xarray.DataArray
-        A categorical xarray.DataArray depicting the following pixel classes:
-        - Nodata (255),
-        - Ocean and coastal waters (1),
-        - Exposed intertidal (low confidence) (2),
-        - Exposed intertidal (high confidence) (3),
-        - Inland waters (4),
-        - Land (5)
-
-    Notes:
-    ------
-    Classes are defined as follows:
-
-    255: Nodata
-    1: Ocean and coastal waters
-       Pixels that are wet in 50% or more observations and located within
-       the coastal connectivity mask
-    2: Exposed intertidal (low confidence)
-       Pixels with water index/tide correlations higher than 0.15.
-       Pixels must be located within the coastal connectivity mask
-       and not be intertidal elevation (high confidence) pixels
-    3: Exposed intertidal (high confidence)
-       Pixels that are included in the intertidal elevation dataset
-    4: Inland waters
-       Pixels that are wet in more than 50% of observations and fall
-       outside of the coastal connectivity mask.
-    5: Land
-       Pixels that are wet in less than 50% of observations
+        Maximum number of grouped pixels to be sieved out to
+        remove small noisy features. Default is 5.
+
+    Returns
+    -------
+    xarray.DataArray
+        A categorical DataArray with the following classes:
+        - 255: Nodata
+        - 1: Ocean and coastal waters (wet ≥50% of observations, within coastal mask)
+        - 2: Exposed intertidal (low confidence) (correlation > 0.15, within coastal mask)
+        - 3: Exposed intertidal (high confidence) (included in intertidal elevation dataset)
+        - 4: Inland waters (wet >50% of observations, outside coastal mask)
+        - 5: Land (wet <50% of observations)
     """
 
     # Identify dataset geobox
     geobox = dem.odc.geobox
 
-    # Identify any pixels that are nodata in frequency 
+    # Identify any pixels that are nodata in frequency
     is_nan = freq.isnull()
 
     # Spilt pixels into those that were mostly wet vs mostly dry.