Merge pull request #164 from UXARRAY/philipc2/update-usage-examples

Updated usage examples

docs/examples.rst

@@ -15,5 +15,5 @@ see the :doc:`contributing`.
    :maxdepth: 1
    :hidden:
 
-   examples/reading-data.ipynb
-   examples/template.ipynb
+   examples/001-read-grid-data.ipynb
+   examples/002-access-grid-info.ipynb

docs/examples/002-access-grid-info.ipynb

@@ -0,0 +1,287 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "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",
+    "## Overview\n",
+    "\n",
+    "This notebook will showcase the different methods available for accessing\n",
+    "the grid topology attributes and variables stored in the `UXarray.Grid`\n",
+    "object.\n",
+    "\n",
+    "For more details on how to load in data, check out our [previous usage\n",
+    "example](https://uxarray.readthedocs.io/en/latest/examples/read-grid-data.html)\n",
+    "\n",
+    "**Methods**\n",
+    "1. Indexing with Original Variable Names\n",
+    "2. Indexing with UXarray Variable Dictionary\n",
+    "3. UXarray's Standardized UGRID Names (Most convenient)"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## Data\n",
+    "\n",
+    "We will be using two grid files, both of which are in the UGRID convention.\n",
+    "However, the key difference between them is the names used to describe the\n",
+    "attributes and variables.\n",
+    "\n",
+    "Let us first read in the data:"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "outputs": [],
+   "source": [
+    "import uxarray as ux\n",
+    "import xarray as xr"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "outputs": [],
+   "source": [
+    "# Base data path\n",
+    "base_path = \"../../test/meshfiles/\"\n",
+    "\n",
+    "# Path to Grid files\n",
+    "ugrid_01_path = base_path + \"outCSne30.ug\"\n",
+    "ugrid_02_path = base_path + \"geoflow-small/grid.nc\"\n",
+    "\n",
+    "# Load grid files and create UXarray Grid objects\n",
+    "ugrid_01_ds = xr.open_dataset(ugrid_01_path)\n",
+    "ugrid_02_ds = xr.open_dataset(ugrid_02_path)\n",
+    "\n",
+    "ugrid_01 = ux.Grid(ugrid_01_ds)\n",
+    "ugrid_02 = ux.Grid(ugrid_02_ds)"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "The output of the bottom cell showcases the slight differences\n",
+    "in variable names:"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "Variable Names\n",
+      "ugrid_01 variable names: ['Mesh2', 'Mesh2_face_nodes', 'Mesh2_node_x', 'Mesh2_node_y', 'nMesh2_face', 'nMaxMesh2_face_nodes', 'nMesh2_node']\n",
+      "ugrid_02 variable names: ['mesh', 'mesh_face_nodes', 'mesh_depth', 'mesh_node_x', 'mesh_node_y', 'nMeshFaces', 'nFaceNodes', 'nMeshNodes', 'meshLayers']\n"
+     ]
+    }
+   ],
+   "source": [
+    "# Extract variable names\n",
+    "ugrid_01_names = list(ugrid_01.ds.keys()) + \\\n",
+    "                 list(ugrid_01.ds.coords) + \\\n",
+    "                 list(ugrid_01.ds.dims)\n",
+    "ugrid_02_names = list(ugrid_02.ds.keys()) + \\\n",
+    "                 list(ugrid_02.ds.coords) + \\\n",
+    "                 list(ugrid_02.ds.dims)\n",
+    "\n",
+    "print(\"\\nAttribute and variable names for each grid:\")\n",
+    "print(\"ugrid_01 variable names:\", ugrid_01_names)\n",
+    "print(\"ugrid_02 variable names:\", ugrid_02_names)"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## 1. Indexing with Original Variable Names\n",
+    "\n",
+    "The simplest approach is to use the original variable name as an index\n",
+    "into the grid dataset, `Grid.ds`. Since `ugrid_01` and `ugrid_02` have\n",
+    "different names for most of their topology attributes and variables, the\n",
+    "index for accessing them will be different for both grids."
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "outputs": [],
+   "source": [
+    "x_1 = ugrid_01.ds['Mesh2_node_x']\n",
+    "y_1 = ugrid_01.ds['Mesh2_node_y']\n",
+    "face_nodes_1 = ugrid_01.ds['Mesh2_face_nodes']\n",
+    "n_face_nodes_1 = ugrid_01.ds['nMaxMesh2_face_nodes']\n",
+    "\n",
+    "x_2 = ugrid_02.ds['mesh_node_x']\n",
+    "y_2 = ugrid_02.ds['mesh_node_y']\n",
+    "face_nodes_2 = ugrid_02.ds['mesh_face_nodes']\n",
+    "n_face_nodes_2 = ugrid_02.ds['nFaceNodes']"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## 2. Indexing with UXarray Variable Dictionary\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.\n",
+    "\n",
+    "This allows us to use the same index into either dataset. However, this\n",
+    "makes the indexing code much longer than the previous method."
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 24,
+   "outputs": [],
+   "source": [
+    "var_names_dict = ugrid_01.ds_var_names\n",
+    "x_1 = ugrid_01.ds[var_names_dict['Mesh2_node_x']]\n",
+    "y_1 = ugrid_01.ds[var_names_dict['Mesh2_node_y']]\n",
+    "face_nodes_1 = ugrid_01.ds[var_names_dict['Mesh2_face_nodes']]\n",
+    "n_face_nodes_1 = ugrid_01.ds[var_names_dict['nMesh2_node']]\n",
+    "\n",
+    "var_names_dict = ugrid_02.ds_var_names\n",
+    "x_2 = ugrid_02.ds[var_names_dict['Mesh2_node_x']]\n",
+    "y_2 = ugrid_02.ds[var_names_dict['Mesh2_node_y']]\n",
+    "face_nodes_2 = ugrid_02.ds[var_names_dict['Mesh2_face_nodes']]\n",
+    "n_face_nodes_2 = ugrid_02.ds[var_names_dict['nMesh2_node']]"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "Please note, for instance, we accessed the actual variable `mesh_node_x`\n",
+    "of `ugrid_02` via indexing the dictionary with the standardized name\n",
+    "`Mesh2_node_x`, likewise in `ugrid_01`."
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "## 3. UXarray's Standardized UGRID Names\n",
+    "The last way of accessing grid topology attributes and variables is to use\n",
+    "the standardized UGRID namings provided by UXarray. This method still\n",
+    "utilizes the dictionary, `ds_var_names`, under the hood to return a\n",
+    "reference to the variable or attribute that is stored withing\n",
+    "`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."
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 22,
+   "outputs": [],
+   "source": [
+    "x_1 = ugrid_01.Mesh2_node_x\n",
+    "y_1 = ugrid_01.Mesh2_node_y\n",
+    "face_nodes_1 = ugrid_01.Mesh2_face_nodes\n",
+    "n_face_nodes_1 = ugrid_01.nMesh2_node\n",
+    "\n",
+    "x_2 = ugrid_02.Mesh2_node_x\n",
+    "y_2 = ugrid_02.Mesh2_node_y\n",
+    "face_nodes_2 = ugrid_02.Mesh2_face_nodes\n",
+    "n_face_nodes_2 = ugrid_02.nMesh2_node"
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "In conclusion, there are three 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 with\n",
+    "each of these access ways."
+   ],
+   "metadata": {
+    "collapsed": false
+   }
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}