Skip to content

Commit 17e84a4

Browse files
philipc2aaronzedwickrajeeja
authored
User Guide on Custom Grids & .from_xarray() methods (#1086)
* docs/user-guide/custom-grid.ipynb * add notebook * update notebook * update api ref * docstrings * update docstrings * gcam * o Minor notebook fixes --------- Co-authored-by: Aaron Zedwick <[email protected]> Co-authored-by: Rajeev Jain <[email protected]>
1 parent 62ca314 commit 17e84a4

File tree

5 files changed

+425
-1
lines changed

5 files changed

+425
-1
lines changed

‎docs/api.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -195,6 +195,7 @@ I/O & Conversion
195195
UxDataArray.to_geodataframe
196196
UxDataArray.to_polycollection
197197
UxDataArray.to_dataset
198+
UxDataArray.from_xarray
198199

199200
UxDataset
200201
-----------
@@ -222,6 +223,7 @@ I/O & Conversion
222223
:toctree: generated/
223224

224225
UxDataset.from_structured
226+
UxDataset.from_xarray
225227

226228
Plotting
227229
--------

‎docs/user-guide/custom-grid.ipynb‎

Lines changed: 355 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,355 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"id": "a8e2583ad32cdf8",
6+
"metadata": {},
7+
"source": [
8+
"# Custom Grid Topology\n",
9+
"\n",
10+
"This notebook will showcase how to construct UXarray data structures from custom grid topology information, including how to convert existing Xarray data structures to UXarray."
11+
]
12+
},
13+
{
14+
"cell_type": "code",
15+
"execution_count": null,
16+
"id": "57e64b0ff76581ca",
17+
"metadata": {},
18+
"outputs": [],
19+
"source": [
20+
"import uxarray as ux\n",
21+
"import xarray as xr\n",
22+
"import numpy as np"
23+
]
24+
},
25+
{
26+
"cell_type": "markdown",
27+
"id": "4cd183a0-3658-4c68-9e08-ed4ff063a0ea",
28+
"metadata": {},
29+
"source": [
30+
"## Minimal Grid Definition\n",
31+
"\n",
32+
"The UGRID conventions require a minimal set of variables for representing a 2D unstructured grid. \n",
33+
"\n",
34+
"| **Variable** | **Shape** | **Description** |\n",
35+
"|--------------------------|--------------------------------|------------------------------------------------|\n",
36+
"| `node_lon` | `(n_node, )` | Longitude of the nodes that make up each face. |\n",
37+
"| `node_lat` | `(n_node, )` | Latitude of the nodes that make up each face. |\n",
38+
"| `face_node_connectivity` | `(n_face, n_max_face_nodes])` | Indices of the nodes that surround each face. |\n"
39+
]
40+
},
41+
{
42+
"cell_type": "markdown",
43+
"id": "072075f6-6b91-4e91-9c28-67bb9ee073ef",
44+
"metadata": {},
45+
"source": [
46+
"## Fixed Face Sizes\n",
47+
"\n",
48+
"For grids where each face has the same number of nodes, such as strictly triangular grids, each row in the `face_node_connectivity` array will contain the indices of nodes that surround each face, with no fill values. Below is an example of the node coordinates and connectivity required for representing a single triangle in the UGRID conventions."
49+
]
50+
},
51+
{
52+
"cell_type": "code",
53+
"execution_count": null,
54+
"id": "f608c0e2-9334-4e1e-aed4-d44b923a5566",
55+
"metadata": {},
56+
"outputs": [],
57+
"source": [
58+
"node_lon = np.array([-20.0, 0.0, 20.0])\n",
59+
"node_lat = np.array([-10.0, 10.0, -10.0])\n",
60+
"face_node_connectivity = np.array(\n",
61+
" [\n",
62+
" [0, 1, 2],\n",
63+
" ]\n",
64+
")"
65+
]
66+
},
67+
{
68+
"cell_type": "markdown",
69+
"id": "f8e3b665-c225-44d6-81b1-80ad23a1b38d",
70+
"metadata": {},
71+
"source": [
72+
"These variables can be passed directly into the `Grid.from_topology()` class-method, which allows custom grid topology information. This is especially useful for cases where a specific grid format isn't directly supported. "
73+
]
74+
},
75+
{
76+
"cell_type": "code",
77+
"execution_count": null,
78+
"id": "b1b3fe63-28f1-4082-910f-8fa3179f1cf8",
79+
"metadata": {},
80+
"outputs": [],
81+
"source": [
82+
"uxgrid_tri = ux.Grid.from_topology(\n",
83+
" node_lon=node_lon, node_lat=node_lat, face_node_connectivity=face_node_connectivity\n",
84+
")"
85+
]
86+
},
87+
{
88+
"cell_type": "code",
89+
"execution_count": null,
90+
"id": "d9846c0f-309b-4b8a-b355-98d23bfd5ce9",
91+
"metadata": {},
92+
"outputs": [],
93+
"source": [
94+
"uxgrid_tri.plot(title=\"Triangle\")"
95+
]
96+
},
97+
{
98+
"cell_type": "markdown",
99+
"id": "f96283a6-a6b8-40ae-99e5-860686fc580d",
100+
"metadata": {},
101+
"source": [
102+
"## Mixed Face Sizes\n",
103+
"\n",
104+
"For grids where each face does not have the same number of nodes, the `face_node_connectivity` array will have it's final dimension (`n_max_face_nodes`) set to the largest element shape. For example, a grid with triangles and quadrialterals will have a final dimension of 4. Any element that has less than the maximum number of nodes will be padded with a fill value. The `face_node_connectivity` array below showcases a basic grid with a single triangle and quadrilateral. Observe that the first row is set to `[0, 1, 2, -1]`, with the first three integers being the indices of the triangle corners, and the final value used as a fill value."
105+
]
106+
},
107+
{
108+
"cell_type": "code",
109+
"execution_count": null,
110+
"id": "43e13ad3-e020-464f-a14b-bbac8bed6bb5",
111+
"metadata": {},
112+
"outputs": [],
113+
"source": [
114+
"node_lon = np.array([-20.0, 0.0, 20.0, -20, -40])\n",
115+
"node_lat = np.array([-10.0, 10.0, -10.0, 10, -10])\n",
116+
"face_node_connectivity = np.array([[0, 1, 2, -1], [0, 1, 3, 4]])"
117+
]
118+
},
119+
{
120+
"cell_type": "markdown",
121+
"id": "c28d3bb0-b469-41e4-a250-5b8f5f2125a9",
122+
"metadata": {},
123+
"source": [
124+
"The `fill_value` parameter must be passed in when working with a mixed topology grid. "
125+
]
126+
},
127+
{
128+
"cell_type": "code",
129+
"execution_count": null,
130+
"id": "4669559c-5f79-47ed-a53f-6bf85b1eaea4",
131+
"metadata": {},
132+
"outputs": [],
133+
"source": [
134+
"uxgrid_tri_quad = ux.Grid.from_topology(\n",
135+
" node_lon=node_lon,\n",
136+
" node_lat=node_lat,\n",
137+
" face_node_connectivity=face_node_connectivity,\n",
138+
" fill_value=-1,\n",
139+
")"
140+
]
141+
},
142+
{
143+
"cell_type": "code",
144+
"execution_count": null,
145+
"id": "e54be66c-d602-41c1-a966-efc4bb7a29c8",
146+
"metadata": {},
147+
"outputs": [],
148+
"source": [
149+
"uxgrid_tri_quad.plot(title=\"Triangle & Quad\")"
150+
]
151+
},
152+
{
153+
"cell_type": "markdown",
154+
"id": "36d09bd1-87cc-4b78-8d2d-8108ef61f7a2",
155+
"metadata": {},
156+
"source": [
157+
"## Working with Existing Xarray Structures\n",
158+
"\n",
159+
"The previous examples showcase how to create a `Grid` from custom topology. The follow sections will walk through how to match data to the `Grid`."
160+
]
161+
},
162+
{
163+
"cell_type": "markdown",
164+
"id": "0876cfed-16a2-4532-ab7e-60754c897a5f",
165+
"metadata": {},
166+
"source": [
167+
"### `xr.DataArray` to `ux.UxDataArray`\n",
168+
"\n",
169+
"Consider the previous example where we constructed the `uxgrid_tri` grid, consisting of a single triangle. Below is an example `xr.DataArray` containing four temperature values. "
170+
]
171+
},
172+
{
173+
"cell_type": "code",
174+
"execution_count": null,
175+
"id": "0d7dce48-e6f4-4bba-8b25-961139fb07b5",
176+
"metadata": {},
177+
"outputs": [],
178+
"source": [
179+
"xrda_temp = xr.DataArray(\n",
180+
" name=\"temp\",\n",
181+
" data=np.array(\n",
182+
" [\n",
183+
" [100, 105, 108, 109],\n",
184+
" ]\n",
185+
" ).T,\n",
186+
" dims=[\"time\", \"cell\"],\n",
187+
")\n",
188+
"xrda_temp"
189+
]
190+
},
191+
{
192+
"cell_type": "markdown",
193+
"id": "41f67fbad5c3e485",
194+
"metadata": {},
195+
"source": [
196+
"The original dimension must be mapped to their UGRID equivalent. \n",
197+
"\n",
198+
"| **Data Mapping** | **UGRID Dimension Name** |\n",
199+
"|------------------|--------------------------|\n",
200+
"| Faces | n_face |\n",
201+
"| Edges | n_edge |\n",
202+
"| Nodes | n_node |\n",
203+
"\n",
204+
"\n",
205+
"In the example above, the `cell` dimension corresponds to the faces of the grid, meaning we want to translate the dimension to `n_face`\n",
206+
"\n"
207+
]
208+
},
209+
{
210+
"cell_type": "code",
211+
"execution_count": null,
212+
"id": "db7ea793-4f8e-4ae9-beec-1bfb0080d79f",
213+
"metadata": {},
214+
"outputs": [],
215+
"source": [
216+
"ugrid_dims = {\"cell\": \"n_face\"}"
217+
]
218+
},
219+
{
220+
"cell_type": "markdown",
221+
"id": "da24da79813502a5",
222+
"metadata": {},
223+
"source": [
224+
"The `UxDataArray.from_xarray()` takes in a user-defined `Grid` in addition to the original `xr.DataArray` and UGRID dimension mapping and returns a `UxDataArray`"
225+
]
226+
},
227+
{
228+
"cell_type": "code",
229+
"execution_count": null,
230+
"id": "797993ac-0e83-437b-a950-704f31f4eae4",
231+
"metadata": {},
232+
"outputs": [],
233+
"source": [
234+
"uxda_temp = ux.UxDataArray.from_xarray(xrda_temp, uxgrid_tri, ugrid_dims)\n",
235+
"uxda_temp"
236+
]
237+
},
238+
{
239+
"cell_type": "markdown",
240+
"id": "67131fdf-3431-47ea-8e9c-0409300d7667",
241+
"metadata": {},
242+
"source": [
243+
"### `xr.Dataset` to `ux.UxDataset`\n",
244+
"\n",
245+
"More commonly, you may have an entire `xr.Dataset` that contains data variables. "
246+
]
247+
},
248+
{
249+
"cell_type": "code",
250+
"execution_count": null,
251+
"id": "e967c9466b3cb25d",
252+
"metadata": {},
253+
"outputs": [],
254+
"source": [
255+
"xrda_vorticity = xr.DataArray(\n",
256+
" name=\"vorticity\",\n",
257+
" data=np.array(\n",
258+
" [\n",
259+
" [1, 2, 3, 4],\n",
260+
" [5, 6, 7, 8],\n",
261+
" [9, 10, 11, 12],\n",
262+
" ]\n",
263+
" ).T,\n",
264+
" dims=[\"time\", \"vertex\"],\n",
265+
")"
266+
]
267+
},
268+
{
269+
"cell_type": "markdown",
270+
"id": "86c9a24a4320d7d0",
271+
"metadata": {},
272+
"source": [
273+
"In this example, we have a cell-centered `temp` and vertex-centered `vorticity` variable. "
274+
]
275+
},
276+
{
277+
"cell_type": "code",
278+
"execution_count": null,
279+
"id": "906532aa-acb3-43c4-95f9-ef9d29312865",
280+
"metadata": {},
281+
"outputs": [],
282+
"source": [
283+
"ds = xr.Dataset(data_vars={\"temp\": xrda_temp, \"vorticity\": xrda_vorticity})\n",
284+
"ds"
285+
]
286+
},
287+
{
288+
"cell_type": "markdown",
289+
"id": "bb01a75189469712",
290+
"metadata": {},
291+
"source": [
292+
"We must now include an additional entry into our `ugrid_dims` dictionary for our vertex-centered data variable."
293+
]
294+
},
295+
{
296+
"cell_type": "code",
297+
"execution_count": null,
298+
"id": "a266b291-c189-40a3-955b-d64dc937d5c9",
299+
"metadata": {},
300+
"outputs": [],
301+
"source": [
302+
"ugrid_dims = {\"cell\": \"n_face\", \"vertex\": \"n_node\"}"
303+
]
304+
},
305+
{
306+
"cell_type": "code",
307+
"execution_count": null,
308+
"id": "8a9b3bf5-38bb-4e9a-8890-4d540b9f62b7",
309+
"metadata": {},
310+
"outputs": [],
311+
"source": [
312+
"uxds = ux.UxDataset.from_xarray(ds=ds, uxgrid=uxgrid_tri, ugrid_dims=ugrid_dims)"
313+
]
314+
},
315+
{
316+
"cell_type": "markdown",
317+
"id": "7d0b1326",
318+
"metadata": {},
319+
"source": [
320+
"uxds now has two `UxDataArray` objects, one for the cell-centered data `temp` and one for the vertex-centered data `vorticity`. There are 4 time steps 0, 1, 2, and 3. Values for time step 0 are shown below."
321+
]
322+
},
323+
{
324+
"cell_type": "code",
325+
"execution_count": null,
326+
"id": "992a409a",
327+
"metadata": {},
328+
"outputs": [],
329+
"source": [
330+
"uxds[\"vorticity\"][0]"
331+
]
332+
}
333+
],
334+
"metadata": {
335+
"kernelspec": {
336+
"display_name": "uxarray_env3.12",
337+
"language": "python",
338+
"name": "python3"
339+
},
340+
"language_info": {
341+
"codemirror_mode": {
342+
"name": "ipython",
343+
"version": 3
344+
},
345+
"file_extension": ".py",
346+
"mimetype": "text/x-python",
347+
"name": "python",
348+
"nbconvert_exporter": "python",
349+
"pygments_lexer": "ipython3",
350+
"version": "3.12.7"
351+
}
352+
},
353+
"nbformat": 4,
354+
"nbformat_minor": 5
355+
}

‎docs/userguide.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,9 @@ These user guides provide detailed explanations of the core functionality in UXa
3131
`Data Structures <user-guide/data-structures.ipynb>`_
3232
Core data structures for working with unstructured grid and data files
3333

34+
`Custom Grid Topology <user-guide/custom-grid.ipynb>`_
35+
Create a Grid from custom Grid topology and convert existing Xarray data structures to UXarray.
36+
3437
`Loading Data using Dask <user-guide/parallel-load-ux-with-dask.ipynb>`_
3538
Read data with chunking and/or in parallel
3639

0 commit comments

Comments
 (0)