{ "cells": [ { "cell_type": "markdown", "id": "defae8d5978518cb", "metadata": {}, "source": [ "\"UXarray\n", "\n", "# UXarray Dataset & DataArray\n", "\n", "### In this section, you'll learn:\n", "\n", "* What are `UxDataset` and `UxDataArray`?\n", "* How do they relate to their Xarray counterparts?\n", "\n", "## Related Documentation\n", "\n", "* [UXarray Data Structures Documentation](https://uxarray.readthedocs.io/en/latest/user-guide/data-structures.html)\n", "\n", "### Prerequisites\n", "\n", "| Concepts | Importance | Notes |\n", "| --- | --- | --- |\n", "| [Introduction to Xarray](https://foundations.projectpythia.org/core/xarray/xarray-intro) | Necessary | |\n", "\n", "**Time to learn**: 15 minutes\n", "\n", "-----\n", "\n" ] }, { "cell_type": "markdown", "id": "8b0f60ea-73c4-4f6f-849f-fb0642fcb78c", "metadata": {}, "source": [ "## Overview" ] }, { "cell_type": "markdown", "id": "e6539b10-cca3-4c93-8368-528b157b26a1", "metadata": {}, "source": [ "As stated before in this chapter, ``UxDataset`` and ``UxDataArray`` are the UXarray classes that are inherited from Xarray counterparts and enable to perform analysis and visualization on unstructured mesh datasets. \n", "\n", "An instance of ``UxDataset`` can be thought of as a collection of data variables, i.e. ``UxDataArray`` objects, that reside on a particular unstructured grid as defined in the class property (``UxDataset.uxgrid`` or ``UxDataArray.uxgrid``).\n", "\n", "In other words, each of these data structures is linked to its own ``Grid`` object through ``uxgrid`` to enable grid-awareness, and for ``UxDataArray``s that belong to a specific ``UxDataset``, ``uxgrid`` of all of them points to the same ``Grid`` object. " ] }, { "cell_type": "markdown", "id": "3a6e4836-6c49-4598-98c0-9750923e84c0", "metadata": {}, "source": [ "## Unstructured Mesh Datasets" ] }, { "cell_type": "markdown", "id": "20746384-c123-4282-8db2-d75e47f6cb25", "metadata": {}, "source": [ "Since most of the unstructured grid datasets contain a single grid definition file along with one or more data files, UXarray's core API allows to open such datasets using those files. \n", "\n", "Let the following dataset have a single data file along with the grid definition: " ] }, { "cell_type": "code", "execution_count": 2, "id": "409a3239-e51b-4353-8418-29dc1693a4dd", "metadata": { "ExecuteTime": { "end_time": "2024-12-18T19:26:50.031729Z", "start_time": "2024-12-18T19:26:50.029554Z" } }, "outputs": [], "source": [ "grid_path = \"../../meshfiles/outCSne30.grid.ug\"\n", "data_path = \"../../meshfiles/outCSne30.data.nc\"" ] }, { "cell_type": "markdown", "id": "0cbfc5ef-d38e-42dd-a582-4c4259fe64ac", "metadata": {}, "source": [ "## Loading a `UxDataset`" ] }, { "cell_type": "markdown", "id": "29e59517-526f-434e-8647-bb8301118950", "metadata": {}, "source": [ "To open a grid file with a **single** data file, the `uxarray.open_dataset()` method can be used. UXarray also provides `uxarray.open_mfdataset()` for opening multiple data files at once (refer to the [UXarray Opening Multipled Data Files Documentation](https://uxarray.readthedocs.io/en/latest/user-guide/data-structures.html#opening-multiple-data-files) for that), but this notebook will cover only the former." ] }, { "cell_type": "code", "execution_count": 3, "id": "d5560f80-09f1-4c5f-b542-0c7c52ba729b", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.UxDataset> Size: 43kB\n",
       "Dimensions:  (n_face: 5400)\n",
       "Dimensions without coordinates: n_face\n",
       "Data variables:\n",
       "    psi      (n_face) float64 43kB ...
" ], "text/plain": [ " Size: 43kB\n", "Dimensions: (n_face: 5400)\n", "Dimensions without coordinates: n_face\n", "Data variables:\n", " psi (n_face) float64 43kB ..." ] }, "execution_count": 3, "metadata": {}, "output_type": "execute_result" } ], "source": [ "import uxarray as ux\n", "\n", "uxds = ux.open_dataset(grid_path, data_path)\n", "uxds" ] }, { "cell_type": "markdown", "id": "aa440c7e-0cfd-4ff1-b72f-a694dddd8a25", "metadata": {}, "source": [ "### Grid Accessor\n", "\n", "Let us first see the ``Grid``object this dataset object is linked to:" ] }, { "cell_type": "code", "execution_count": 5, "id": "e08df73d-f3e1-463d-94f3-a98f4e8aaeff", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<uxarray.Grid>\n",
       "Original Grid Type: UGRID\n",
       "Grid Dimensions:\n",
       "  * n_node: 5402\n",
       "  * n_face: 5400\n",
       "  * n_max_face_nodes: 4\n",
       "  * n_nodes_per_face: (5400,)\n",
       "Grid Coordinates (Spherical):\n",
       "  * node_lon: (5402,)\n",
       "  * node_lat: (5402,)\n",
       "Grid Coordinates (Cartesian):\n",
       "Grid Connectivity Variables:\n",
       "  * face_node_connectivity: (5400, 4)\n",
       "Grid Descriptor Variables:\n",
       "  * n_nodes_per_face: (5400,)\n",
       "
" ], "text/plain": [ "\n", "Original Grid Type: UGRID\n", "Grid Dimensions:\n", " * n_node: 5402\n", " * n_face: 5400\n", " * n_max_face_nodes: 4\n", " * n_nodes_per_face: (5400,)\n", "Grid Coordinates (Spherical):\n", " * node_lon: (5402,)\n", " * node_lat: (5402,)\n", "Grid Coordinates (Cartesian):\n", "Grid Connectivity Variables:\n", " * face_node_connectivity: (5400, 4)\n", "Grid Descriptor Variables:\n", " * n_nodes_per_face: (5400,)" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "uxds.uxgrid" ] }, { "cell_type": "markdown", "id": "a15b2d67-f30d-4c8f-b5c5-7f6ae82395fa", "metadata": {}, "source": [ "## Accessing Data Variables (``UxDataArray``)\n", "\n", "Similar to the Xarray conterparts, an ``UxDataset`` can have multiple ``UxDataArray``s in it, which are for different data variables. A variable of interest can be accessed in the same way Xarray provides:" ] }, { "cell_type": "code", "execution_count": 6, "id": "79626e59-d4bc-4e6b-a108-001e017b6fd2", "metadata": { "scrolled": true }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.UxDataArray 'psi' (n_face: 5400)> Size: 43kB\n",
       "[5400 values with dtype=float64]\n",
       "Dimensions without coordinates: n_face
" ], "text/plain": [ " Size: 43kB\n", "[5400 values with dtype=float64]\n", "Dimensions without coordinates: n_face" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "uxds[\"psi\"]" ] }, { "cell_type": "markdown", "id": "df0d0584-384f-45de-b63f-4c6803d15ed9", "metadata": {}, "source": [ "### Grid Accessor\n", "\n", "The ``Grid``object of this data array is the same ``Grid`` object as ``uxds``'s above:" ] }, { "cell_type": "code", "execution_count": 5, "id": "06e0a099-5e71-4b42-afc8-6fa1856a8e5e", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<uxarray.Grid>\n",
       "Original Grid Type: UGRID\n",
       "Grid Dimensions:\n",
       "  * n_node: 5402\n",
       "  * n_face: 5400\n",
       "  * n_max_face_nodes: 4\n",
       "  * n_nodes_per_face: (5400,)\n",
       "Grid Coordinates (Spherical):\n",
       "  * node_lon: (5402,)\n",
       "  * node_lat: (5402,)\n",
       "Grid Coordinates (Cartesian):\n",
       "Grid Connectivity Variables:\n",
       "  * face_node_connectivity: (5400, 4)\n",
       "Grid Descriptor Variables:\n",
       "  * n_nodes_per_face: (5400,)\n",
       "
" ], "text/plain": [ "\n", "Original Grid Type: UGRID\n", "Grid Dimensions:\n", " * n_node: 5402\n", " * n_face: 5400\n", " * n_max_face_nodes: 4\n", " * n_nodes_per_face: (5400,)\n", "Grid Coordinates (Spherical):\n", " * node_lon: (5402,)\n", " * node_lat: (5402,)\n", "Grid Coordinates (Cartesian):\n", "Grid Connectivity Variables:\n", " * face_node_connectivity: (5400, 4)\n", "Grid Descriptor Variables:\n", " * n_nodes_per_face: (5400,)" ] }, "execution_count": 5, "metadata": {}, "output_type": "execute_result" } ], "source": [ "uxda = uxds[\"psi\"]\n", "uxda.uxgrid" ] }, { "cell_type": "markdown", "id": "97f9b990-6a92-4de9-baf8-da7728ef67a5", "metadata": {}, "source": [ "## Relationship to Xarray" ] }, { "cell_type": "markdown", "id": "ffd122d2-513c-415d-97b9-5eb40db986af", "metadata": {}, "source": [ "For users coming from an Xarray background, much of UXarray's design is familiar thanks to the UXarray's inheritance of the core data structures from Xarray's counterparts and employment of design choices such as accessors. Inheritance has been chosen for the UXarray design both to provide the users with a Xarray-like user experience and to use the built-in Xarray functionality whenever possible while overwrite the others for unstructured grid arithmetic.\n", "\n", "As a simple Xarray example that would replicate the above UXarray dataset opening and variable access with UXarray, please see the following code: " ] }, { "cell_type": "code", "execution_count": 7, "id": "048279bd-3628-4478-9384-6807e3c24b65", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.Dataset> Size: 30kB\n",
       "Dimensions:  (lat: 45, lon: 80)\n",
       "Coordinates:\n",
       "  * lat      (lat) int64 360B -90 -86 -82 -78 -74 -70 -66 ... 66 70 74 78 82 86\n",
       "  * lon      (lon) float64 640B -180.0 -175.5 -171.0 ... 166.5 171.0 175.5\n",
       "Data variables:\n",
       "    psi      (lat, lon) float64 29kB ...
" ], "text/plain": [ " Size: 30kB\n", "Dimensions: (lat: 45, lon: 80)\n", "Coordinates:\n", " * lat (lat) int64 360B -90 -86 -82 -78 -74 -70 -66 ... 66 70 74 78 82 86\n", " * lon (lon) float64 640B -180.0 -175.5 -171.0 ... 166.5 171.0 175.5\n", "Data variables:\n", " psi (lat, lon) float64 29kB ..." ] }, "execution_count": 7, "metadata": {}, "output_type": "execute_result" } ], "source": [ "# Import\n", "import xarray as xr\n", "\n", "# Structured grid data file\n", "data_path_structured = \"../../meshfiles/outCSne30.structured.nc\"\n", "\n", "# Open dataset with Xarray\n", "xrds = xr.open_dataset(data_path_structured)\n", "xrds" ] }, { "cell_type": "code", "execution_count": 8, "id": "c641c1b3-c397-4856-91b5-95b4b3c9a3df", "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.DataArray 'psi' (lat: 45, lon: 80)> Size: 29kB\n",
       "[3600 values with dtype=float64]\n",
       "Coordinates:\n",
       "  * lat      (lat) int64 360B -90 -86 -82 -78 -74 -70 -66 ... 66 70 74 78 82 86\n",
       "  * lon      (lon) float64 640B -180.0 -175.5 -171.0 ... 166.5 171.0 175.5\n",
       "Attributes:\n",
       "    regrid_method:  nearest_s2d
" ], "text/plain": [ " Size: 29kB\n", "[3600 values with dtype=float64]\n", "Coordinates:\n", " * lat (lat) int64 360B -90 -86 -82 -78 -74 -70 -66 ... 66 70 74 78 82 86\n", " * lon (lon) float64 640B -180.0 -175.5 -171.0 ... 166.5 171.0 175.5\n", "Attributes:\n", " regrid_method: nearest_s2d" ] }, "execution_count": 8, "metadata": {}, "output_type": "execute_result" } ], "source": [ "xrda = xrds[\"psi\"]\n", "xrda" ] }, { "cell_type": "markdown", "id": "833b03b9-f49e-4601-8127-7af61dc2b640", "metadata": {}, "source": [ "
\n", "

See also:

\n", " For further information, please visit the \n", " UXarray Inheritance from Xarray documentation\n", "
" ] }, { "cell_type": "markdown", "id": "53694653-47d8-41c1-a7da-177af780b292", "metadata": {}, "source": [ "## What is next?\n", "The next section is the final section in this chapter that will provide information about how to operate spatial selection methods on ``UxDataArray``." ] } ], "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.12.8" } }, "nbformat": 4, "nbformat_minor": 5 }