Add API extending xgcm vertical regridding (#388)

Author: jasonb5

conda-env/ci.yml

@@ -22,6 +22,7 @@ dependencies:
     # Constrained because 0.6.3 breaks with import ESMF
     # Source: https://github.com/pangeo-data/xESMF/issues/212
     - xesmf >0.6.3
+    - xgcm
     # Quality Assurance
     # ==================
     - types-python-dateutil

conda-env/dev.yml

@@ -19,6 +19,7 @@ dependencies:
     - pandas=1.5.3
     - python-dateutil=2.8.2
     - xarray=2023.4.2
+    - xgcm=0.8.0
     # ==================
     # Optional
     # ==================
@@ -35,6 +36,7 @@ dependencies:
     - nbsphinx=0.9.1
     - pandoc=3.1.1
     - ipython=8.11.0 # Required for nbsphinx syntax highlighting
+    - gsw-xarray=0.3.0 # Required for vertical regridding example
     # ==================
     # Quality Assurance
     # ==================

conda-env/readthedocs.yml

@@ -18,6 +18,7 @@ dependencies:
     - pandas=1.5.3
     - python-dateutil=2.8.2
     - xarray=2023.4.2
+    - xgcm=0.8.0
     # ==================
     # Optional
     # ==================

docs/api.rst

@@ -88,6 +88,7 @@ Classes
     xcdat.regridder.accessor.RegridderAccessor
     xcdat.regridder.regrid2.Regrid2Regridder
     xcdat.regridder.xesmf.XESMFRegridder
+    xcdat.regridder.xgcm.XGCMRegridder
 
 .. currentmodule:: xarray
 
@@ -123,6 +124,7 @@ Methods
     Dataset.regridder.horizontal
     Dataset.regridder.horizontal_xesmf
     Dataset.regridder.horizontal_regrid2
+    Dataset.regridder.vertical
 
 .. _dsmeth_1:
 

docs/examples/horizontal-regridding.ipynb renamed to docs/examples/regridding-horizontal.ipynb

@@ -1,27 +1,30 @@
 {
  "cells": [
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "a31785d6-310c-4871-9ac6-064a7874945f",
    "metadata": {
     "tags": []
    },
    "source": [
     "# Horizontal Regridding\n",
+    "\n",
     "Author: [Jason Boutte](https://github.com/jasonb5)\n",
     "\n",
     "Date: 08/24/22\n",
     "\n",
     "Related APIs:\n",
     "\n",
-    "* [xarray.Dataset.regridder.horizontal](../generated/xarray.Dataset.regridder.horizontal.rst)\n",
+    "- [xarray.Dataset.regridder.horizontal](../generated/xarray.Dataset.regridder.horizontal.rst)\n",
     "\n",
     "The data used in this example can be found through the [Earth System Grid Federation (ESGF) search portal](https://aims2.llnl.gov/search).\n",
     "\n",
     "## Overview\n",
+    "\n",
     "We'll cover horizontal regridding using the `xESMF` and `Regrid2` tools as well as various methods supported by `xESMF`.\n",
     "\n",
-    "It should be noted that `Regrid2` treats the grid cells as being flat."
+    "It should be noted that `Regrid2` treats the grid cells as being flat.\n"
    ]
   },
   {
@@ -39,14 +42,16 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "7d904843-4079-4ebe-a3d0-ab439e8ce052",
    "metadata": {},
    "source": [
     "## 1. Open the Dataset\n",
+    "\n",
     "We are using xarray's OPeNDAP support to read a netCDF4 dataset file directly from its source. The data is not loaded over the network until we perform operations on it (e.g., temperature unit adjustment).\n",
     "\n",
-    "More information on the xarray's OPeNDAP support can be found [here](https://docs.xarray.dev/en/stable/user-guide/io.html#opendap)."
+    "More information on the xarray's OPeNDAP support can be found [here](https://docs.xarray.dev/en/stable/user-guide/io.html#opendap).\n"
    ]
   },
   {
@@ -640,25 +645,27 @@
     }
    ],
    "source": [
-    "filepath = 'http://aims3.llnl.gov/thredds/dodsC/css03_data/CMIP6/CMIP/CCCma/CanESM5/historical/r13i1p1f1/Amon/tas/gn/v20190429/tas_Amon_CanESM5_historical_r13i1p1f1_gn_185001-201412.nc'\n",
+    "filepath = \"http://aims3.llnl.gov/thredds/dodsC/css03_data/CMIP6/CMIP/CCCma/CanESM5/historical/r13i1p1f1/Amon/tas/gn/v20190429/tas_Amon_CanESM5_historical_r13i1p1f1_gn_185001-201412.nc\"\n",
     "\n",
     "ds = xcdat.open_dataset(filepath)\n",
     "\n",
     "# Unit adjust (-273.15, K to C)\n",
-    "ds['tas'] = ds['tas'] - 273.15\n",
+    "ds[\"tas\"] = ds[\"tas\"] - 273.15\n",
     "\n",
-    "ds"
+    "ds\n"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "1aa0dc89-d664-4721-8759-45065060a5b1",
    "metadata": {},
    "source": [
     "## 2. Create the output grid\n",
+    "\n",
     "Related API: [xcdat.create_gaussian_grid()](../generated/xcdat.create_gaussian_grid.rst)\n",
     "\n",
-    "In this example, we will generate a gaussian grid with 32 latitudes to regrid our input data to."
+    "In this example, we will generate a gaussian grid with 32 latitudes to regrid our input data to.\n"
    ]
   },
   {
@@ -685,24 +692,26 @@
     "\n",
     "fig, axes = plt.subplots(ncols=2, figsize=(16, 4))\n",
     "\n",
-    "ds.regridder.grid.plot.scatter('lon', 'lat', s=0.01, ax=axes[0])\n",
-    "axes[0].set_title('Input Grid')\n",
+    "ds.regridder.grid.plot.scatter(\"lon\", \"lat\", s=0.01, ax=axes[0])\n",
+    "axes[0].set_title(\"Input Grid\")\n",
     "\n",
-    "output_grid.plot.scatter('lon', 'lat', s=0.1, ax=axes[1])\n",
-    "axes[1].set_title('Output Grid')\n",
+    "output_grid.plot.scatter(\"lon\", \"lat\", s=0.1, ax=axes[1])\n",
+    "axes[1].set_title(\"Output Grid\")\n",
     "\n",
-    "plt.tight_layout()"
+    "plt.tight_layout()\n"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "9d5fe21a-85ef-4737-95fd-0a0868e89579",
    "metadata": {},
    "source": [
     "## 3. Regrid the data\n",
+    "\n",
     "Related API: [xarray.Dataset.regridder.horizontal()](../generated/xarray.Dataset.regridder.horizontal.rst)\n",
     "\n",
-    "Here we will regrid the input data to the ouptut grid using the `xESMF` tool and the `bilinear` method."
+    "Here we will regrid the input data to the ouptut grid using the `xESMF` tool and the `bilinear` method.\n"
    ]
   },
   {
@@ -725,25 +734,27 @@
     }
    ],
    "source": [
-    "output = ds.regridder.horizontal('tas', output_grid, tool='xesmf', method='bilinear')\n",
+    "output = ds.regridder.horizontal(\"tas\", output_grid, tool=\"xesmf\", method=\"bilinear\")\n",
     "\n",
     "fig, axes = plt.subplots(ncols=2, figsize=(16, 4))\n",
     "\n",
     "ds.tas.isel(time=0).plot(ax=axes[0])\n",
-    "axes[0].set_title('Input data')\n",
+    "axes[0].set_title(\"Input data\")\n",
     "\n",
     "output.tas.isel(time=0).plot(ax=axes[1])\n",
-    "axes[1].set_title('Output data')\n",
+    "axes[1].set_title(\"Output data\")\n",
     "\n",
-    "plt.tight_layout()"
+    "plt.tight_layout()\n"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "4084129e-dd96-4d0d-ae01-4a66f897e4e5",
    "metadata": {},
    "source": [
     "## 4. Regridding algorithms\n",
+    "\n",
     "Related API: [xarray.Dataset.regridder.horizontal()](../generated/xarray.Dataset.regridder.horizontal.rst)\n",
     "\n",
     "In this example, we will compare the different regridding methods supported by `xESMF`.\n",
@@ -752,11 +763,11 @@
     "\n",
     "Methods:\n",
     "\n",
-    "* bilinear\n",
-    "* conservative\n",
-    "* nearest_s2d\n",
-    "* nearest_d2s\n",
-    "* patch"
+    "- bilinear\n",
+    "- conservative\n",
+    "- nearest_s2d\n",
+    "- nearest_d2s\n",
+    "- patch\n"
    ]
   },
   {
@@ -779,35 +790,37 @@
     }
    ],
    "source": [
-    "methods = ['bilinear', 'conservative', 'nearest_s2d', 'nearest_d2s', 'patch']\n",
+    "methods = [\"bilinear\", \"conservative\", \"nearest_s2d\", \"nearest_d2s\", \"patch\"]\n",
     "\n",
     "fig, axes = plt.subplots(3, 2, figsize=(16, 12))\n",
     "\n",
     "axes = axes.flatten()\n",
     "\n",
     "for i, method in enumerate(methods):\n",
-    "    output = ds.regridder.horizontal('tas', output_grid, tool='xesmf', method=method)\n",
+    "    output = ds.regridder.horizontal(\"tas\", output_grid, tool=\"xesmf\", method=method)\n",
     "\n",
     "    output.tas.isel(time=0).plot(ax=axes[i])\n",
     "\n",
     "    axes[i].set_title(method)\n",
     "\n",
     "axes[-1].set_visible(False)\n",
     "\n",
-    "plt.tight_layout()"
+    "plt.tight_layout()\n"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "92685e37-ed43-42c2-b9b3-8b4722075ebc",
    "metadata": {},
    "source": [
     "## 5. Masking\n",
+    "\n",
     "Related API: [xarray.Dataset.regridder.horizontal()](../generated/xarray.Dataset.regridder.horizontal.rst)\n",
     "\n",
     "`xESMF` supports masking by simply adding a data variable with the id `mask`.\n",
     "\n",
-    "See `xESMF` [documentation](https://pangeo-xesmf.readthedocs.io/en/latest/notebooks/Masking.html) for additonal details."
+    "See `xESMF` [documentation](https://pangeo-xesmf.readthedocs.io/en/latest/notebooks/Masking.html) for additonal details.\n"
    ]
   },
   {
@@ -830,32 +843,36 @@
     }
    ],
    "source": [
-    "ds['mask'] = xr.where(ds.tas.isel(time=0)<-10, 1, 0)\n",
+    "ds[\"mask\"] = xr.where(ds.tas.isel(time=0) < -10, 1, 0)\n",
     "\n",
-    "masked_output = ds.regridder.horizontal('tas', output_grid, tool='xesmf', method='bilinear')\n",
+    "masked_output = ds.regridder.horizontal(\n",
+    "    \"tas\", output_grid, tool=\"xesmf\", method=\"bilinear\"\n",
+    ")\n",
     "\n",
     "fig, axes = plt.subplots(ncols=2, figsize=(18, 4))\n",
     "\n",
-    "ds['mask'].plot(ax=axes[0], cmap='binary_r')\n",
-    "axes[0].set_title('Mask')\n",
+    "ds[\"mask\"].plot(ax=axes[0], cmap=\"binary_r\")\n",
+    "axes[0].set_title(\"Mask\")\n",
     "\n",
     "masked_output.tas.isel(time=0).plot(ax=axes[1])\n",
-    "axes[1].set_title('Masked output')\n",
+    "axes[1].set_title(\"Masked output\")\n",
     "\n",
-    "plt.tight_layout()"
+    "plt.tight_layout()\n"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "99daebe0-0b0d-4a88-988a-5e2d685de80d",
    "metadata": {},
    "source": [
     "## 6. Regridding using `regrid2`\n",
+    "\n",
     "Related API: [xarray.Dataset.regridder.horizontal()](../generated/xarray.Dataset.regridder.horizontal.rst)\n",
     "\n",
     "`Regrid2` is a conservative regridder for rectilinear (lat/lon) grids originally from the `cdutil` package from `CDAT`.\n",
     "\n",
-    "This regridder assumes constant latitude lines when generating weights."
+    "This regridder assumes constant latitude lines when generating weights.\n"
    ]
   },
   {
@@ -888,19 +905,19 @@
     }
    ],
    "source": [
-    "output = ds.regridder.horizontal('tas', output_grid, tool='regrid2')\n",
+    "output = ds.regridder.horizontal(\"tas\", output_grid, tool=\"regrid2\")\n",
     "\n",
     "fig, axes = plt.subplots(ncols=2, figsize=(16, 4))\n",
     "\n",
     "ds.tas.isel(time=0).plot(ax=axes[0])\n",
     "\n",
-    "output.tas.isel(time=0).plot(ax=axes[1])"
+    "output.tas.isel(time=0).plot(ax=axes[1])\n"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3.9.13 ('xcdat_dev')",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -914,7 +931,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.13"
+   "version": "3.10.8"
   },
   "vscode": {
    "interpreter": {