diff --git a/docs/contributing.rst b/docs/contributing.rst index e430490db..e358fd6f5 100644 --- a/docs/contributing.rst +++ b/docs/contributing.rst @@ -310,7 +310,7 @@ development purposes. Use the following commands for this:: $ conda env create --file ci/environment.yml $ conda activate uxarray_build -THe above commands will use the ``environment.yml`` conda environment definition +The above commands will use the ``environment.yml`` conda environment definition file that is hosted under the ``ci`` folder and create a conda environment with the name ``uxarray_build``. Once you activate that environment with the help of the second command, you will be able to develop UXarray codes in your local configuration. diff --git a/docs/examples/009-subsetting.ipynb b/docs/examples/009-subsetting.ipynb index 25c23b39e..05e66b264 100644 --- a/docs/examples/009-subsetting.ipynb +++ b/docs/examples/009-subsetting.ipynb @@ -2,20 +2,23 @@ "cells": [ { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "# Subsetting an Unstructured Grid: Analysis Over Chicago\n", "\n", "Authors: [Philip Chmielowiec](https://github.com/philipc2)\n", "\n", "This usage example showcases various ways of subsetting an unstructured grid using UXarray, focussing on analyzing a region around Chicago, Illinois." - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "import uxarray as ux\n", @@ -34,27 +37,27 @@ "\n", "\n", "warnings.filterwarnings(\"ignore\")" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "## Setup\n", "\n", "In this example, we will be using the `geocat-datafiles` package to obtain our grid and data files.\n", "\n", "The dataset used in this example is a 30km global MPAS meshes. We will be investigating the relative humidity vertically interpolated to 200hPa (`relhum200hPa`) data variable." - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "datafiles = (\n", @@ -63,164 +66,164 @@ " ),\n", " geodf.get(\"netcdf_files/MPAS/FalkoJudt/dyamond_1/30km/x1.655362.grid_subset.nc\"),\n", ")" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "uxds = ux.open_dataset(datafiles[1], datafiles[0])" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "clim = (uxds['relhum_200hPa'][0].values.min(), uxds['relhum_200hPa'][0].values.max())" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "features = gf.coastline(projection=ccrs.PlateCarree(), line_width=1, scale='50m') * \\\n", " gf.states(projection=ccrs.PlateCarree(), line_width=1, scale='50m')" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "## Global Grid\n", "\n", "Many unstructured grids, such as those from global climate models, span the entire surface of a sphere (both with or without masks, such as continents).\n", "\n", "UXarray supports working with these global grids, handling cases that arise with the spherical geometry of the earth (wrap around at the antimeridian, pole points, etc.)\n" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "uxds['relhum_200hPa'][0].plot.rasterize(method='polygon',\n", " exclude_antimeridian=True,\n", " title = \"Global Grid\",\n", " **plot_opts) * features" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", - "source": [ - "In addition to plotting global grids, we can perform analysis operations." - ], "metadata": { "collapsed": false - } + }, + "source": [ + "In addition to plotting global grids, we can perform analysis operations." + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "uxds['relhum_200hPa'][0].values.mean()" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "## Regional Subsets\n", "\n", "UXarray supports taking subsets of a grid, which allows us to select a region and perform analysis directly on that area, as opposed to the global grid.\n", "\n", "There are currently three supported subsetting methods, both for the `Grid` and `UxDataArray` data structures." - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "uxds['relhum_200hPa'].subset" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "uxds['relhum_200hPa'].uxgrid.subset" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "### Bounding Box\n", "\n", "We can declare a bounding box centered about the Chicago area by specifying the minimum and maximum longitude and latitude bounds.\n" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "lon_bounds = (-87.6298 - 2, -87.6298 + 2)\n", "lat_bounds = (41.8781 - 2, 41.8781 + 2)" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "Our bounding box ensures that the coordinates of our select element (`nodes`, `edge_centers`, or `face_centers`) are within the defined bounding box range.\n", "\n", "Below is an example using the corner nodes for our subset." - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "bbox_subset_nodes = uxds['relhum_200hPa'][0].subset.bounding_box(lon_bounds, lat_bounds, element='nodes')\n", @@ -230,23 +233,23 @@ " clim=clim,\n", " title=\"Bounding Box Subset\",\n", " **plot_opts) * features" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", - "source": [ - "And similarly using face centers." - ], "metadata": { "collapsed": false - } + }, + "source": [ + "And similarly using face centers." + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "bbox_subset_faces= uxds['relhum_200hPa'][0].subset.bounding_box(lon_bounds, lat_bounds, element='face centers')\n", @@ -256,51 +259,51 @@ " clim=clim,\n", " title=\"Bounding Box Subset (Face Center Query)\",\n", " **plot_opts) * features" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "While the bounding box is generally the same, you will notice differences along the border depending on which element is used to query.\n", "\n", - ":::{note}\n", + "```{note}\n", "Specifying which element to query (i.e. ``nodes``, ``edgecenters``, or ``face centers``) is supported by all subsetting methods.\n", - ":::" - ], - "metadata": { - "collapsed": false - } + "```" + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "### Bounding Circle\n", "\n", "A bounding circle is defined using a center coordinate (lon, lat) and a radius (in degrees). The resulting subset will contain all elements within the radius of that circle." - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "center_coord = [-87.6298, 41.8781]\n", "\n", "r = 2" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "bcircle_subset = uxds['relhum_200hPa'][0].subset.bounding_circle(center_coord, r)\n", @@ -310,36 +313,36 @@ " clim=clim,\n", " title=\"Bounding Circle Subset\",\n", " **plot_opts) * features" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "### Nearest Neighbor\n", "\n", "Similar to the bounding circle, we can perform a nearest neighbor subset at some center coordinate (lon, lat) and query for some number of elements `k`" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "center_coord = [-87.6298, 41.8781]" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "nn_subset = uxds['relhum_200hPa'][0].subset.nearest_neighbor(center_coord, k = 30, element='nodes')\n", @@ -348,14 +351,14 @@ " clim=clim,\n", " title= \"Nearest Neighbor Subset\",\n", " **plot_opts) * features" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "nn_subset_120 = uxds['relhum_200hPa'][0].subset.nearest_neighbor(center_coord, k = 120, element=\"face centers\")\n", @@ -365,14 +368,14 @@ " clim=clim,\n", " title= \"Nearest Neighbor Subset (120 Faces)\",\n", " **plot_opts) * features" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "nn_subset_1 = uxds['relhum_200hPa'][0].subset.nearest_neighbor(center_coord, k = 1, element=\"face centers\")\n", @@ -381,67 +384,64 @@ " clim=clim,\n", " title= \"Nearest Neighbor Subset (Closest Face)\",\n", " **plot_opts) * features" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "markdown", + "metadata": { + "collapsed": false + }, "source": [ "### Analysis Operators\n", "\n", "Since each subset is a newly initialized ``UxDataArray``, paired also with a newly initialized `Grid`, we can perform analysis operators directly on these new objects.\n", "\n", "Below is a few examples of basic statical operations on the subset data arrays." - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "bbox_subset_nodes.values.mean(), bbox_subset_faces.values.mean(), bcircle_subset.values.mean()" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "bbox_subset_nodes.values.std(), bbox_subset_faces.values.std(), bcircle_subset.values.std()" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "bbox_subset_nodes.values.min(), bbox_subset_faces.values.min(), bcircle_subset.values.min()" - ], - "metadata": { - "collapsed": false - } + ] }, { "cell_type": "code", "execution_count": null, + "metadata": { + "collapsed": false + }, "outputs": [], "source": [ "bbox_subset_nodes.values.max(), bbox_subset_faces.values.max(), bcircle_subset.values.max()" - ], - "metadata": { - "collapsed": false - } + ] } ], "metadata": {