Adds land-sea mask generation (#783)

* Refactors grid generation and updates generating bounds

* Fixes dtype in gaussian grid creation

* Initial land-sea mask implementation

* Fixes exception that occurs when landsea mask resource is missing

* Fixes copying mask as it's modified in place by _improve_mask

* Fixes returning DataArray from _pcmdi_land_sea_mask

* Renames accessor and masking methods

* Fixes broken test expecting dataarray

* Adds option to output mask in dataset

* Adds dispatcher options and updates documentation

* Fixes missing import for MaskAccessor

* Changes function names and updates docstrings

* Adds documentation section for module-level methods

* Adds ability to define the source mask to use in the PCMDI land-sea mask generation

* Fixes documentation function reference

* Refactor land-sea mask handling and documentation

- Updated pcmdi_land_sea_mask() docstring and disabled time decoding for navy_land.nc
- Replaced bundled navy_land.nc with pooch fetch-and-cache system
- Removed mask_get_resource_path() and its tests
- Added _data._get_pcmdi_mask_path() with corresponding tests
- Updated environment configs to require pooch >=1.8
- Refreshed related docstrings

* Moves land/sea mask from geomask to spatial accessor, exposes generate method

* Fixes generating mask for a grid

* Adds land/sea mask example

* Updates landsea mask notebook

* Re-run notebook to remove env error

* Address Copilot review comments

* Renames criteria to threshold and corrects documentation via copilot review

---------

Co-authored-by: tomvothecoder <tomvothecoder@gmail.com>

Author: jasonb5

conda-env/ci.yml

@@ -13,7 +13,9 @@ dependencies:
     - netcdf4
     - numpy >=2.0.0,<3.0.0
     - pandas
+    - pooch >=1.8
     - python-dateutil
+    - regionmask
     - scipy
     - sparse
     - xarray >=2024.03.0
@@ -26,4 +28,3 @@ dependencies:
     # ==================
     - pytest
     - pytest-cov
-    - pooch # Required for xarray tutorial data

conda-env/dev.yml

@@ -13,7 +13,9 @@ dependencies:
     - netcdf4
     - numpy >=2.0.0,<3.0.0
     - pandas
+    - pooch >=1.8
     - python-dateutil
+    - regionmask
     - scipy
     - sparse
     - xarray >=2024.03.0
@@ -34,7 +36,6 @@ dependencies:
     - pandoc
     - ipython # Required for nbsphinx syntax highlighting
     - gsw-xarray # Required for vertical regridding example
-    - pooch # Required for xarray tutorial data
     # Quality Assurance
     # ==================
     - types-python-dateutil

docs/_static/thumbnails/spatial-landsea-mask.png

@@ -39,6 +39,17 @@ Below is a list of top-level API functions that are available in ``xcdat``.
     create_zonal_grid
     tutorial.open_dataset
 
+Module-level API Functions
+--------------------------
+
+Below is a list of module-level API functions that are available in ``xcdat``.
+
+.. autosummary::
+    :toctree: generated/
+
+    mask.pcmdi_land_sea_mask
+
+
 Accessors
 ---------
 
@@ -123,6 +134,9 @@ Methods
     Dataset.bounds.get_bounds
     Dataset.bounds.add_missing_bounds
     Dataset.spatial.average
+    Dataset.spatial.mask_land
+    Dataset.spatial.mask_sea
+    Dataset.spatial.generate_land_sea_mask
     Dataset.temporal.average
     Dataset.temporal.group_average
     Dataset.temporal.climatology