diff --git a/docs/_static/images/userguides/zonal_mean.png b/docs/_static/images/userguides/zonal_mean.png
new file mode 100644
index 000000000..bf2dcb18d
Binary files /dev/null and b/docs/_static/images/userguides/zonal_mean.png differ
diff --git a/docs/user-guide/zonal-average.ipynb b/docs/user-guide/zonal-average.ipynb
index 4d4eb2f65..9031f6d51 100644
--- a/docs/user-guide/zonal-average.ipynb
+++ b/docs/user-guide/zonal-average.ipynb
@@ -27,18 +27,14 @@
},
{
"cell_type": "code",
+ "execution_count": null,
"id": "185e2061bc4c75b9",
"metadata": {
- "execution": {
- "iopub.execute_input": "2025-09-26T15:41:01.836324Z",
- "iopub.status.busy": "2025-09-26T15:41:01.836130Z",
- "iopub.status.idle": "2025-09-26T15:41:05.102704Z",
- "shell.execute_reply": "2025-09-26T15:41:05.102291Z"
- },
"jupyter": {
"is_executing": true
}
},
+ "outputs": [],
"source": [
"from pathlib import Path\n",
"\n",
@@ -54,9 +50,7 @@
" \"../../test/meshfiles/ugrid/outCSne30/outCSne30.ug\",\n",
" \"../../test/meshfiles/ugrid/outCSne30/outCSne30_vortex.nc\",\n",
")"
- ],
- "outputs": [],
- "execution_count": null
+ ]
},
{
"cell_type": "markdown",
@@ -73,6 +67,10 @@
"- **Non-conservative**: Calculates the mean by sampling face values at specific latitude lines and weighting each contribution by the length of the line where each face intersects that latitude.\n",
"- **Conservative**: Preserves integral quantities by calculating the mean by sampling face values within latitude bands and weighting contributions by their area overlap with latitude bands.\n",
"\n",
+ "Please check the figure below for a visualization of non-conservative (left) and conservative (right) zonal averaging on an unstructured spherical mesh. The weight contribution by each face is provided by line segment and area overlaps between the face and the zonal band for the non-conservative and conservative cases, respectively. A green-colored line-segment and polygon is provided as an example for each case.\n",
+ "\n",
+ "
\n",
+ "\n",
"```{seealso}\n",
"[NCL Zonal Average](https://www.ncl.ucar.edu/Applications/zonal.shtml) — NCL reference with conventional rectilinear grids.\n",
"```\n"
@@ -95,110 +93,10 @@
},
{
"cell_type": "code",
- "execution_count": 34,
+ "execution_count": null,
"id": "global_field_plot",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2025-09-26T15:41:05.104590Z",
- "iopub.status.busy": "2025-09-26T15:41:05.104455Z",
- "iopub.status.idle": "2025-09-26T15:41:07.888812Z",
- "shell.execute_reply": "2025-09-26T15:41:07.888366Z"
- }
- },
- "outputs": [
- {
- "data": {},
- "metadata": {},
- "output_type": "display_data"
- },
- {
- "data": {
- "application/vnd.holoviews_exec.v0+json": "",
- "text/html": [
- "
<xarray.DataArray 'psi_zonal_mean' (latitudes: 19)> Size: 152B\n", - "array([1.08546247, 1.09219987, 1.10863654, 1.10011333, 1.04989243,\n", - " 1.03074397, 1.01980815, 1.01312147, 0.9973705 , 1.00000001,\n", - " 1.00262952, 0.98687854, 0.98019186, 0.96925608, 0.95010754,\n", - " 0.89988665, 0.89136345, 0.90780013, 0.91453753])\n", - "Coordinates:\n", - " * latitudes (latitudes) float64 152B -90.0 -80.0 -70.0 ... 70.0 80.0 90.0\n", - "Attributes:\n", - " zonal_mean: True\n", - " conservative: False
<xarray.DataArray 'psi_zonal_mean' (latitudes: 6)> Size: 48B\n", - "array([1.10364701, 1.03897837, 1.00563134, 0.99327248, 0.96134106,\n", - " 0.89634629])\n", - "Coordinates:\n", - " * latitudes (latitudes) float64 48B -75.0 -45.0 -15.0 15.0 45.0 75.0\n", - "Attributes:\n", - " zonal_mean: True\n", - " conservative: True\n", - " lat_band_edges: [-90. -60. -30. 0. 30. 60. 90.]
<xarray.UxDataArray 'RELHUM' (lev: 72, n_face: 21600)> Size: 6MB\n", - "[1555200 values with dtype=float32]\n", - "Coordinates:\n", - " * lev (lev) float64 576B 0.1238 0.1828 0.2699 ... 986.2 993.8 998.5\n", - " time object 8B ...\n", - "Dimensions without coordinates: n_face\n", - "Attributes:\n", - " mdims: 1\n", - " units: percent\n", - " long_name: Relative humidity\n", - " standard_name: relative_humidity\n", - " cell_methods: time: mean
<xarray.DataArray 'RELHUM_zonal_mean' (lev: 72, lat: 18)> Size: 5kB\n", - "array([[1.39507087e-04, 1.46236242e-04, 1.57333357e-04, ...,\n", - " 1.38013987e-04, 1.37959549e-04, 1.37912750e-04],\n", - " [1.46500082e-04, 1.56465467e-04, 1.59396877e-04, ...,\n", - " 1.38380448e-04, 1.37978277e-04, 1.37925847e-04],\n", - " [1.39333293e-04, 1.40268996e-04, 1.41239536e-04, ...,\n", - " 1.41590019e-04, 1.37986484e-04, 1.37942334e-04],\n", - " ...,\n", - " [9.95636673e+01, 9.57479248e+01, 9.42285156e+01, ...,\n", - " 1.00770416e+02, 1.01268219e+02, 1.04364807e+02],\n", - " [9.75083466e+01, 9.47997131e+01, 9.26638336e+01, ...,\n", - " 9.82491531e+01, 9.99979477e+01, 1.02430000e+02],\n", - " [9.58398132e+01, 9.40848160e+01, 9.15409851e+01, ...,\n", - " 9.66513596e+01, 9.93786469e+01, 1.01074776e+02]],\n", - " shape=(72, 18), dtype=float32)\n", - "Coordinates:\n", - " * lev (lev) float64 576B 0.1238 0.1828 0.2699 ... 986.2 993.8 998.5\n", - " * lat (lat) float64 144B -85.0 -75.0 -65.0 -55.0 ... 55.0 65.0 75.0 85.0\n", - "Attributes:\n", - " zonal_mean: True\n", - " conservative: False
<xarray.DataArray 'RELHUM_zonal_mean' (lev: 5)> Size: 20B\n", - "array([2.2769236e-06, 3.7543796e-06, 2.1681481e-06, 4.8164511e-06,\n", - " 2.9139337e-06], dtype=float32)\n", - "Coordinates:\n", - " * lev (lev) float64 40B 0.1238 0.1828 0.2699 0.3986 0.5885