{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Reading In and Accessing Grid Data" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This notebook will show how to use UXarray to represent various unstructured\n", "grids in the UGRID convention and to access grid information, combined with\n", "Xarray to read in grid definition and data files." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Dependencies\n", "- uxarray\n", "- xarray\n", "- geocat-datafiles (for accessing test datasets)\n" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Background Information\n", "\n", "When working with unstructured grids, the grid definition and data variables\n", "are often stored as separate files (most of the time as netCDF). This means\n", "that there are multiple separate files that need to be read in at once.\n", "\n", "For example, the NOAA Geoflow project consists of 4 files (1 grid file and 3\n", "data files). This project follows the UGRID conventions. Special thanks to\n", "John Clyne, Shilpi Gupta, and the VAPOR team for providing these data!\n", "\n", "```\n", "geoflow-small\n", "│ grid.nc\n", "│ v1.nc\n", "│ v2.nc\n", "│ v3.nc\n", "```" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Opening The Grid and Data Files with Xarray\n", "\n", "First, read in the grid definition and data variable netCCDF files by using\n", "`xarray.open_dataset` and/or `xr.open_mf_dataset`." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Imports" ] }, { "cell_type": "code", "execution_count": 1, "metadata": {}, "outputs": [], "source": [ "import geocat.datafiles as gdf\n", "import xarray as xr" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Data" ] }, { "cell_type": "code", "execution_count": 2, "metadata": {}, "outputs": [], "source": [ "# Base data path\n", "base_path = \"netcdf_files/geoflow-small/\"\n", "\n", "# Path to Grid file\n", "grid_path = base_path + \"grid.nc\"\n", "\n", "# Paths to Data Variable files\n", "var_names = ['v1.nc', 'v2.nc', 'v3.nc']\n", "data_paths = [base_path + name for name in var_names]" ] }, { "cell_type": "code", "execution_count": 3, "metadata": {}, "outputs": [], "source": [ "# Open the Grid file\n", "grid_ds = xr.open_dataset(gdf.get(grid_path))" ] }, { "cell_type": "code", "execution_count": 4, "metadata": {}, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.Dataset>\n",
       "Dimensions:          (nMeshFaces: 3840, nFaceNodes: 4, nMeshNodes: 6000,\n",
       "                      meshLayers: 20)\n",
       "Coordinates:\n",
       "    mesh_node_x      (nMeshNodes) float64 0.0 5.214 16.5 ... 62.7 68.8 72.0\n",
       "    mesh_node_y      (nMeshNodes) float64 58.28 59.8 62.06 ... -31.68 -31.72\n",
       "Dimensions without coordinates: nMeshFaces, nFaceNodes, nMeshNodes, meshLayers\n",
       "Data variables:\n",
       "    mesh             int32 -2147483647\n",
       "    mesh_face_nodes  (nMeshFaces, nFaceNodes) float64 0.0 1.0 ... 5.998e+03\n",
       "    mesh_depth       (meshLayers, nMeshNodes) float64 ...
" ], "text/plain": [ "\n", "Dimensions: (nMeshFaces: 3840, nFaceNodes: 4, nMeshNodes: 6000,\n", " meshLayers: 20)\n", "Coordinates:\n", " mesh_node_x (nMeshNodes) float64 ...\n", " mesh_node_y (nMeshNodes) float64 ...\n", "Dimensions without coordinates: nMeshFaces, nFaceNodes, nMeshNodes, meshLayers\n", "Data variables:\n", " mesh int32 ...\n", " mesh_face_nodes (nMeshFaces, nFaceNodes) float64 ...\n", " mesh_depth (meshLayers, nMeshNodes) float64 ..." ] }, "execution_count": 4, "metadata": {}, "output_type": "execute_result" } ], "source": [ "grid_ds" ] }, { "cell_type": "code", "execution_count": 5, "metadata": {}, "outputs": [], "source": [ "# Open a single file or multiple files\n", "multi_data_ds = xr.open_mfdataset([\n", " gdf.get(data_paths[0]),\n", " gdf.get(data_paths[1]),\n", " gdf.get(data_paths[2])\n", "])" ] }, { "cell_type": "code", "execution_count": 6, "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.Dataset>\n",
       "Dimensions:  (time: 1, meshLayers: 20, nMeshNodes: 6000)\n",
       "Coordinates:\n",
       "  * time     (time) float64 13.0\n",
       "Dimensions without coordinates: meshLayers, nMeshNodes\n",
       "Data variables:\n",
       "    v1       (time, meshLayers, nMeshNodes) float64 dask.array<chunksize=(1, 20, 6000), meta=np.ndarray>\n",
       "    v2       (time, meshLayers, nMeshNodes) float64 dask.array<chunksize=(1, 20, 6000), meta=np.ndarray>\n",
       "    v3       (time, meshLayers, nMeshNodes) float64 dask.array<chunksize=(1, 20, 6000), meta=np.ndarray>
" ], "text/plain": [ "\n", "Dimensions: (time: 1, meshLayers: 20, nMeshNodes: 6000)\n", "Coordinates:\n", " * time (time) float64 13.0\n", "Dimensions without coordinates: meshLayers, nMeshNodes\n", "Data variables:\n", " v1 (time, meshLayers, nMeshNodes) float64 dask.array\n", " v2 (time, meshLayers, nMeshNodes) float64 dask.array\n", " v3 (time, meshLayers, nMeshNodes) float64 dask.array" ] }, "execution_count": 6, "metadata": {}, "output_type": "execute_result" } ], "source": [ "multi_data_ds" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Representing The Unstructured Grid with UXarray" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Import UXarray" ] }, { "cell_type": "code", "execution_count": 7, "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false }, "pycharm": { "name": "#%%\n" } }, "outputs": [], "source": [ "import uxarray as ux" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### UXarray.Grid object" ] }, { "cell_type": "code", "execution_count": 8, "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } }, "outputs": [], "source": [ "# Construct a UXarray Grid object from `grid_ds`\n", "grid = ux.Grid(grid_ds)" ] }, { "cell_type": "code", "execution_count": 9, "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false } }, "outputs": [ { "data": { "text/html": [ "
\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "\n", "
<xarray.Dataset>\n",
       "Dimensions:          (nMeshFaces: 3840, nFaceNodes: 4, nMeshNodes: 6000,\n",
       "                      meshLayers: 20)\n",
       "Coordinates:\n",
       "    mesh_node_x      (nMeshNodes) float64 0.0 5.214 16.5 ... 62.7 68.8 72.0\n",
       "    mesh_node_y      (nMeshNodes) float64 58.28 59.8 62.06 ... -31.68 -31.72\n",
       "Dimensions without coordinates: nMeshFaces, nFaceNodes, nMeshNodes, meshLayers\n",
       "Data variables:\n",
       "    mesh             int32 -2147483647\n",
       "    mesh_face_nodes  (nMeshFaces, nFaceNodes) float64 0.0 1.0 ... 5.998e+03\n",
       "    mesh_depth       (meshLayers, nMeshNodes) float64 ...
" ], "text/plain": [ "\n", "Dimensions: (nMeshFaces: 3840, nFaceNodes: 4, nMeshNodes: 6000,\n", " meshLayers: 20)\n", "Coordinates:\n", " mesh_node_x (nMeshNodes) float64 0.0 5.214 16.5 ... 62.7 68.8 72.0\n", " mesh_node_y (nMeshNodes) float64 58.28 59.8 62.06 ... -31.68 -31.72\n", "Dimensions without coordinates: nMeshFaces, nFaceNodes, nMeshNodes, meshLayers\n", "Data variables:\n", " mesh int32 -2147483647\n", " mesh_face_nodes (nMeshFaces, nFaceNodes) float64 0.0 1.0 ... 5.998e+03\n", " mesh_depth (meshLayers, nMeshNodes) float64 ..." ] }, "execution_count": 9, "metadata": {}, "output_type": "execute_result" } ], "source": [ "grid.ds" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As can be seen, the Grid object has its own `grid.ds` of type `xarray.Dataset`\n", "to define the grid topology. However, the Grid object has further attributes,\n", "variables, and functions to specify the unstructured grid and be executed on\n", "it, which can be explored in the next notebooks." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Accessing Grid Information\n", "\n", "Unstructured grids can be represented in one of many different conventions\n", "(**UGRID, SCRIP, EXODUS**, etc). These conventions have different definitions\n", "and representations of the attributes and variables used to describe\n", "the unstructured grid topology. Even more, the [UGRID conventions](\n", "https://ugrid-conventions.github.io/ugrid-conventions/) does not\n", "enforce standard variable namings for most of the attributes and variables\n", "(other than just a few required ones).\n", "\n", "UXarray unifies all of these conventions at the data loading step by\n", "representing grids in the UGRID convention regardless of the original grid\n", "type that is read in from the file. Furthermore, it uses a set of\n", "standardized names for topology attributes and variables, while still\n", "providing the user with the original attribute names and variables that\n", "came from the grid definition file.\n", "\n", "This section will showcase **UXarray's Standardized UGRID Names** for \n", "accessing the grid topology attributes and variables stored in the \n", "`UXarray.Grid` object.\n", "\n", "For more details on how to load in data, or multiple ways of accessing the \n", "grid topology information, check out our [UXarray Usage \n", "Examples](https://uxarray.readthedocs.io/en/latest/examples.html)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Topology attribute and variable names coming from the grid file\n", "\n", "Let's first have a look at the original attribute and variable names that come from the grid file in UGRID convention with custom names:" ] }, { "cell_type": "code", "execution_count": 10, "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false }, "pycharm": { "name": "#%%\n" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "Original attribute and variable names from the grid file:\n", " ['mesh', 'mesh_face_nodes', 'mesh_depth', 'mesh_node_x', 'mesh_node_y', 'nMeshFaces', 'nFaceNodes', 'nMeshNodes', 'meshLayers']\n" ] } ], "source": [ "# Extract variable names\n", "grid_names = list(grid.ds.keys()) + list(grid.ds.coords) + list(grid.ds.dims)\n", "\n", "print(\"Original attribute and variable names from the grid file:\\n\", grid_names)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### UXarray's standardized UGRID Names for topology attributes and variables\n", "\n", "UXarray provides a dictionary, `Grid.ds_var_names`, to map the original\n", "topology attribute and variable names that come from the grid file into\n", "a standardized set of names. In other words, the dictionary uses a\n", "standardized set of UGRID attribute and variable names as keys, and the\n", "original variable names that come from the grid file as values. UXarray \n", "utilizes this dictionary under the hood to return references to the \n", "variables and attributes that are stored within `UXarray.Grid.ds`.\n", "\n", "This eliminates the need to remember the original variable names and\n", "needing to index through the `ds_var_names` dictionary. Because of this,\n", "we find this as the most convenient approach:" ] }, { "cell_type": "code", "execution_count": 11, "metadata": {}, "outputs": [], "source": [ "x_2 = grid.Mesh2_node_x\n", "y_2 = grid.Mesh2_node_y\n", "face_nodes_2 = grid.Mesh2_face_nodes\n", "n_face_nodes_2 = grid.nMesh2_node" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Please note, for instance, we accessed the actual variable `mesh_node_x`\n", "of `grid` via indexing the dictionary with the standardized name\n", "`Mesh2_node_x`. Regardless of the grid type we read in (e.g. UGRID, \n", "SCRIP, Exodus, etc.), this would be the same because of our representation \n", "of the grid in the UGRID convention with standardized names." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "### Other ways:" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Indexing with original variable names\n", "\n", "The original variable name can be used as an index into the grid dataset, \n", "`Grid.ds`:" ] }, { "cell_type": "code", "execution_count": 12, "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false }, "pycharm": { "name": "#%%\n" } }, "outputs": [], "source": [ "x_2 = grid.ds['mesh_node_x']\n", "y_2 = grid.ds['mesh_node_y']\n", "face_nodes_2 = grid.ds['mesh_face_nodes']\n", "n_face_nodes_2 = grid.ds['nFaceNodes']" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "#### Indexing with UXarray variable dictionary\n", "\n", "The dictionary, `Grid.ds_var_names`, can be used to index into the \n", "dataset. However, this makes the indexing code much longer than the \n", "other methods:" ] }, { "cell_type": "code", "execution_count": 13, "metadata": { "collapsed": false, "jupyter": { "outputs_hidden": false }, "pycharm": { "name": "#%%\n" } }, "outputs": [], "source": [ "var_names_dict = grid.ds_var_names\n", "x_2 = grid.ds[var_names_dict['Mesh2_node_x']]\n", "y_2 = grid.ds[var_names_dict['Mesh2_node_y']]\n", "face_nodes_2 = grid.ds[var_names_dict['Mesh2_face_nodes']]\n", "n_face_nodes_2 = grid.ds[var_names_dict['nMesh2_node']]" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In conclusion, there are multiple ways of accessing the grid attributes and\n", "variables. Even though the UXarray developers recommend using the\n", "standardized UGRID names method, users can find each various pros/cons \n", "with each of these access ways." ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "## Running Grid-Specific Functions" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "UXarray even has a few computational functions implemented already! " ] }, { "cell_type": "code", "execution_count": 14, "metadata": {}, "outputs": [], "source": [ "grid_total_face_area = grid.calculate_total_face_area()\n", "grid_face_areas = grid.compute_face_areas()" ] }, { "cell_type": "code", "execution_count": 15, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "12.566370618717663" ] }, "execution_count": 15, "metadata": {}, "output_type": "execute_result" } ], "source": [ "grid_total_face_area" ] }, { "cell_type": "code", "execution_count": 16, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "array([0.00205959, 0.00363576, 0.00318908, ..., 0.00315344, 0.00361048,\n", " 0.00205959])" ] }, "execution_count": 16, "metadata": {}, "output_type": "execute_result" } ], "source": [ "grid_face_areas" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "There is also a Grid attribute for the result of the `grid.compute_face_areas()` function:" ] }, { "cell_type": "code", "execution_count": 17, "metadata": {}, "outputs": [ { "data": { "text/plain": [ "array([0.00205959, 0.00363576, 0.00318908, ..., 0.00315344, 0.00361048,\n", " 0.00205959])" ] }, "execution_count": 17, "metadata": {}, "output_type": "execute_result" } ], "source": [ "grid.face_areas" ] } ], "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.6" }, "vscode": { "interpreter": { "hash": "8e8ae2f388051fced6c30f82a529eeca8cf1e059ab06a64326e2a2ad0ec3c36c" } } }, "nbformat": 4, "nbformat_minor": 4 }