diff --git a/conda-env/ci.yml b/conda-env/ci.yml index 4e9b162d9..46df89981 100644 --- a/conda-env/ci.yml +++ b/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 diff --git a/conda-env/dev.yml b/conda-env/dev.yml index 82f688b98..9cabb0d11 100644 --- a/conda-env/dev.yml +++ b/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 diff --git a/docs/_static/thumbnails/spatial-landsea-mask.png b/docs/_static/thumbnails/spatial-landsea-mask.png new file mode 100644 index 000000000..a9cbf8517 Binary files /dev/null and b/docs/_static/thumbnails/spatial-landsea-mask.png differ diff --git a/docs/api.rst b/docs/api.rst index e625146d3..987762b34 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -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 diff --git a/docs/examples/spatial-landsea-mask.ipynb b/docs/examples/spatial-landsea-mask.ipynb new file mode 100644 index 000000000..7407eb38b --- /dev/null +++ b/docs/examples/spatial-landsea-mask.ipynb @@ -0,0 +1,1037 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "3d6ebf97-8656-4c44-bf9e-4652ba1d153b", + "metadata": {}, + "source": [ + "# Spatial Land/Sea Mask\n", + "\n", + "Authors: [Jason Boutte](https://github.com/jasonb5/) & [Jiwoo Lee](https://github.com/lee1043/) & [Tom Vo](https://github.com/tomvothecoder/)\n", + "\n", + "Updated: 10/09/25 [xcdat v0.9.1]\n", + "\n", + "Related APIs:\n", + "\n", + "- [xarray.Dataset.spatial.mask_land()](../generated/xarray.Dataset.spatial.mask_land.rst)\n", + "- [xarray.Dataset.spatial.mask_sea()](../generated/xarray.Dataset.spatial.mask_sea.rst)\n", + "- [xarray.Dataset.spatial.generate_land_sea_mask()](../generated/xarray.Dataset.spatial.generate_land_sea_mask.rst)\n" + ] + }, + { + "cell_type": "markdown", + "id": "c3b6a296-35d4-47d7-ab50-de3ab34707eb", + "metadata": {}, + "source": [ + "## Overview\n", + "\n", + "In geophysical sciences it can often be useful to mask data that is not of interest. Spatial land/sea masking functionality in xcdat allows users to quickly generate and apply land/sea masks derived from various methods.\n", + "\n", + "In the example below, we demonstrate masking land/sea, generating land/sea masks and customizing the mask generation.\n", + "\n", + "The data used in this example can be found in the [xcdat-data repository](https://github.com/xCDAT/xcdat-data).\n" + ] + }, + { + "cell_type": "markdown", + "id": "481d258e-1618-4936-a7f5-5daed7404274", + "metadata": {}, + "source": [ + "### Notebook Kernel Setup\n", + "\n", + "Users can [install their own instance of xcdat](../getting-started-guide/installation.rst) and follow these examples using their own environment (e.g., with VS Code, Jupyter, Spyder, iPython) or [enable xcdat with existing JupyterHub instances](../getting-started-guide/getting-started-hpc-jupyter.rst).\n", + "\n", + "First, create the conda environment:\n", + "\n", + "```bash\n", + "conda create -n xcdat_notebook -c conda-forge xcdat xesmf matplotlib ipython ipykernel cartopy nc-time-axis gsw-xarray jupyter pooch\n", + "```\n", + "\n", + "Then install the kernel from the `xcdat_notebook` environment using `ipykernel` and name the kernel with the display name (e.g., `xcdat_notebook`):\n", + "\n", + "```bash\n", + "python -m ipykernel install --user --name xcdat_notebook --display-name xcdat_notebook\n", + "```\n", + "\n", + "Then to select the kernel `xcdat_notebook` in Jupyter to use this kernel.\n" + ] + }, + { + "cell_type": "markdown", + "id": "59cddcb2-861c-4b16-b977-16cccce82112", + "metadata": {}, + "source": [ + "## 1. Open the `Dataset`\n" + ] + }, + { + "cell_type": "code", + "execution_count": 1, + "id": "b1a3c9e7-4670-4d80-9882-afcfd557043f", + "metadata": {}, + "outputs": [ + { + "data": { + "text/html": [ + "
<xarray.Dataset> Size: 7MB\n", + "Dimensions: (time: 60, bnds: 2, lat: 145, lon: 192)\n", + "Coordinates:\n", + " * time (time) object 480B 1870-01-16 12:00:00 ... 1874-12-16 12:00:00\n", + " * lat (lat) float64 1kB -90.0 -88.75 -87.5 -86.25 ... 87.5 88.75 90.0\n", + " * lon (lon) float64 2kB 0.0 1.875 3.75 5.625 ... 354.4 356.2 358.1\n", + " height float64 8B ...\n", + "Dimensions without coordinates: bnds\n", + "Data variables:\n", + " time_bnds (time, bnds) object 960B ...\n", + " lat_bnds (lat, bnds) float64 2kB ...\n", + " lon_bnds (lon, bnds) float64 3kB ...\n", + " tas (time, lat, lon) float32 7MB ...\n", + "Attributes: (12/48)\n", + " Conventions: CF-1.7 CMIP-6.2\n", + " activity_id: CMIP\n", + " branch_method: standard\n", + " branch_time_in_child: 0.0\n", + " branch_time_in_parent: 87658.0\n", + " creation_date: 2020-06-05T04:06:11Z\n", + " ... ...\n", + " variant_label: r10i1p1f1\n", + " version: v20200605\n", + " license: CMIP6 model data produced by CSIRO is li...\n", + " cmor_version: 3.4.0\n", + " tracking_id: hdl:21.14100/af78ae5e-f3a6-4e99-8cfe-5f2...\n", + " DODS_EXTRA.Unlimited_Dimension: time