Weighted Average

docs/api.rst

@@ -387,6 +387,7 @@ Dual Mesh Construction
 Aggregations
 ------------
 
+
 Topological
 ~~~~~~~~~~~
 
@@ -413,16 +414,13 @@ on each face.
    UxDataArray.topological_all
    UxDataArray.topological_any
 
-
-
-Intersections
-~~~~~~~~~~~~~
-
+Weighted
+~~~~~~~~
 .. autosummary::
    :toctree: generated/
 
-   grid.intersections.gca_gca_intersection
-   grid.intersections.gca_const_lat_intersection
+   UxDataArray.weighted_mean
+
 
 
 Spherical Geometry

docs/user-guide/weighted_mean.ipynb

@@ -0,0 +1,208 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "23f93b0f-62ac-4efd-975c-368477c9ebbe",
+   "metadata": {},
+   "source": [
+    "# Weighted Mean\n",
+    "\n",
+    "UXarray supports computing weighted means based on geometric properties such as face areas or edge lengths. In this section of the user guide, we explain how to calculate variable means using unstructured grid geometries as weights. The examples below demonstrate the application of weighted means using grid face areas and grid edge lengths as weights.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "ed637e46-672c-45ba-a5f1-ed3c3248c8a1",
+   "metadata": {},
+   "source": [
+    "import uxarray as ux\n",
+    "import xarray as xr\n",
+    "import cartopy.crs as ccrs\n",
+    "\n",
+    "import warnings\n",
+    "\n",
+    "warnings.filterwarnings(\"ignore\")"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8518335d-2f75-4699-bc3d-862ab25830d1",
+   "metadata": {},
+   "source": [
+    "## Data\n",
+    "\n",
+    "Data used in this section is a 3-random-variable dataset on a quad hexagon mesh mapped to the edges and faces."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "a2f58f07d7881d4f",
+   "metadata": {},
+   "source": [
+    "grid_path = \"../../test/meshfiles/ugrid/quad-hexagon/grid.nc\"\n",
+    "quad_hex_data_path_edge_centered = (\n",
+    "    \"../../test/meshfiles/ugrid/quad-hexagon/random-edge-data.nc\"\n",
+    ")\n",
+    "quad_hex_data_path_face_centered = (\n",
+    "    \"../../test/meshfiles/ugrid/quad-hexagon/random-face-data.nc\"\n",
+    ")\n",
+    "\n",
+    "uxds_face = ux.open_mfdataset(grid_path, quad_hex_data_path_face_centered)\n",
+    "uxds_edge = ux.open_mfdataset(grid_path, quad_hex_data_path_edge_centered)"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "code",
+   "id": "6fac99462efcccdc",
+   "metadata": {},
+   "source": [
+    "(\n",
+    "    uxds_face.uxgrid.plot(line_color=\"black\")\n",
+    "    * uxds_edge[\"random_data_edge\"]\n",
+    "    .plot.points(\n",
+    "        cmap=\"inferno\", size=150, marker=\"square\", clabel=None, tools=[\"hover\"]\n",
+    "    )\n",
+    "    .relabel(\"Edge Data\")\n",
+    "    * uxds_face[\"random_data_face\"]\n",
+    "    .plot.points(\n",
+    "        cmap=\"inferno\", size=150, marker=\"triangle\", clabel=None, tools=[\"hover\"]\n",
+    "    )\n",
+    "    .relabel(\"Face Data\")\n",
+    ").opts(legend_position=\"top_right\")"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "id": "bb77e5067497a0f5",
+   "metadata": {},
+   "source": [
+    "## Weighted Mean based on Face Areas\n",
+    "\n",
+    "Here we first look at the data values on each face and the faces' respective areas. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "c87fb018ca75ba5e",
+   "metadata": {},
+   "source": [
+    "uxds_face[\"random_data_face\"].values"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "id": "def2b952ba7f1740",
+   "metadata": {},
+   "source": "We can simply call `UxDataArray.weighted_mean()` on the UXDataArray to compute the weighted mean. The differences between the weighted mean and the regular mean is small since the area differences across the faces are small. "
+  },
+  {
+   "cell_type": "code",
+   "id": "bd76b23993d9967f",
+   "metadata": {},
+   "source": [
+    "result = uxds_face[\"random_data_face\"].weighted_mean()\n",
+    "result.values"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "code",
+   "id": "a92f056d6b2a567b",
+   "metadata": {},
+   "source": [
+    "unweighted_result = uxds_face[\"random_data_face\"].mean()\n",
+    "unweighted_result.values"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "id": "e8ddb288f83486b8",
+   "metadata": {},
+   "source": [
+    "## Weighted Mean Based on Edge Length\n",
+    "\n",
+    "Here we show the similar steps but for edge-centered data and the edge lengths. "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "id": "1b01581da7ebacc",
+   "metadata": {},
+   "source": [
+    "uxds_edge[\"random_data_edge\"].values"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "code",
+   "id": "a50c11e691337cff",
+   "metadata": {},
+   "source": [
+    "uxds_edge.uxgrid.edge_node_distances.data"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "id": "647630d11f001fcf",
+   "metadata": {},
+   "source": "The differences between weighted and unweighted mean is more drastic (~0.1 value difference) since the edge lengths have a larger variance. "
+  },
+  {
+   "cell_type": "code",
+   "id": "6bace8386234b942",
+   "metadata": {},
+   "source": [
+    "result = uxds_edge[\"random_data_edge\"].weighted_mean()\n",
+    "result.values"
+   ],
+   "outputs": [],
+   "execution_count": null
+  },
+  {
+   "cell_type": "code",
+   "id": "d81bc60c195be6ec",
+   "metadata": {},
+   "source": [
+    "unweighted_result = uxds_edge[\"random_data_edge\"].mean()\n",
+    "unweighted_result.values"
+   ],
+   "outputs": [],
+   "execution_count": null
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.12"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

docs/userguide.rst

@@ -55,6 +55,9 @@ These user guides provide detailed explanations of the core functionality in UXa
 `Topological Aggregations <user-guide/topological-aggregations.ipynb>`_
  Aggregate data across grid dimensions
 
+`Weighted Mean <user-guide/weighted_mean.ipynb>`_
+ Compute the weighted average
+
 `Calculus Operators <user-guide/calculus.ipynb>`_
  Apply calculus operators (gradient, integral) on unstructured grid data
 
@@ -100,6 +103,7 @@ These user guides provide additional details about specific features in UXarray.
    user-guide/cross-sections.ipynb
    user-guide/remapping.ipynb
    user-guide/topological-aggregations.ipynb
+   user-guide/weighted_mean.ipynb
    user-guide/calculus.ipynb
    user-guide/tree_structures.ipynb
    user-guide/area_calc.ipynb