Merge pull request #11 from bonnland/add-documentation

Add more documentation

README.md

@@ -6,7 +6,12 @@
 [![Binder](https://binder.projectpythia.org/badge_logo.svg)](http://binder.projectpythia.org/v2/gh/ProjectPythia/na-cordex-viz-cookbook/main?labpath=notebooks)
 [![DOI](https://zenodo.org/badge/635958518.svg)](https://zenodo.org/badge/latestdoi/635958518)
 
-This Project Pythia Cookbook covers how to load and view data summaries from the NA-CORDEX dataset. Documentation for the NA-CORDEX dataset can be found here: https://na-cordex.org/na-cordex-on-aws.html
+The NA-CORDEX data archive contains cloud-optimized, Zarr-based output from regional climate models (RCMs) run over a domain covering most of North America using boundary conditions from global climate model (GCM) simulations in the CMIP5 archive. These simulations run from 1950–2100 with a spatial resolution of 0.22°/25km or 0.44°/50km. Data is available for impacts-relevant variables at daily and longer frequencies.
+
+This Project Pythia Cookbook covers how to load and view data summaries from the NA-CORDEX dataset. 
+
+- Complete documentation for the cloud-optimized version of the NA-CORDEX dataset can be found here: https://na-cordex.org/na-cordex-on-aws.html
+- More information on the scope and objectives for NA-CORDEX can be found here:  https://na-cordex.org/index.html
 
 ## Motivation
 

notebooks/plot-diagnostics.ipynb

@@ -6,11 +6,59 @@
    "source": [
     "# Make Diagnostic Plots for NA-CORDEX Zarr Stores\n",
     "\n",
+    "The NA-CORDEX data archive contains output from regional climate models (RCMs) run over a domain covering most of North America using boundary conditions from global climate model (GCM) simulations in the CMIP5 archive.  It differs from many climate datasets by combining runs from many independently derived simulations.  The usage of Zarr, Xarray, and Intake-ESM help simplify the problem of examining these disparate runs.\n",
+    "\n",
+    "See the [README](../README.md) file for more pointers and information on the NA-CORDEX data archive.\n",
+    "\n",
+    "## Overview \n",
+    "\n",
     "This cookbook provides useful methods for summarizing data values in large climate datasets.   It clearly shows where data have extreme values and where data are missing; this can be useful for validating that the data were gathered and stored correctly.   While this cookbook is specifically designed to examine any portion of the NA-CORDEX dataset using an intake catalog, the code can be adapted straightforwardly to other datasets that can be loaded via `xarray`.\n",
     "\n",
+    "Topics covered in this notebook include:\n",
+    "\n",
+    "1. Different Ways to Create and Connect to Dask Distributed Cluster\n",
+    "1. How to Find and Obtain Data Using an Intake-ESM Catalog\n",
+    "1. How to Create Various Statistical Summary Plots with matplotlib"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Prerequisites\n",
+    "\n",
+    "To more fully understand how the code in this notebook works, users are encouraged to explore the following introductory articles.\n",
+    "\n",
+    "| Concepts | Importance | Notes |\n",
+    "| --- | --- | --- |\n",
+    "| [Intro to Xarray](https://foundations.projectpythia.org/core/xarray/xarray-intro.html) | Helpful | |\n",
+    "| [Dask Arrays with Xarray](https://foundations.projectpythia.org/core/xarray/dask-arrays-xarray.html) | Helpful | |\n",
+    "| [Understanding of Zarr Metadata](https://foundations.projectpythia.org/core/data-formats/netcdf-cf.html) | Helpful | Familiarity with metadata structure |\n",
+    "| [Understanding of Matplotlib](https://foundations.projectpythia.org/core/matplotlib/matplotlib-basics.html) | Helpful | Familiarity with plot elements in matplotlib |\n",
+    "\n",
+    "- **Time to learn**: 45 minutes\n",
+    "\n",
+    "**Note**: This notebook contains optional choices for running on NCAR supercomputers.   These can be ignored for users running outside of the NCAR domain."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "---"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "## Imports\n",
+    "\n",
     "The main python packages used are `xarray`, `intake-esm`, `dask`, and `matplotlib`.\n",
     "\n",
-    "* [NA-CORDEX on AWS Documentation](https://na-cordex.org/na-cordex-on-aws.html)"
+    "Because some of the CORDEX data have been interpolated from a Lambert Conformal grid onto a rectangular grid for ease of use, there can be many missing values on the edges of the interpolated grid. For this reason, we also turn off warnings complaining about missing values in the data."
    ]
   },
   {
@@ -847,7 +895,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.9.12"
+   "version": "3.10.13"
   },
   "widgets": {
    "application/vnd.jupyter.widget-state+json": {