Lily edits (#386)

* Implemented edits for pages 31 and 32 * Implemented grammar fixes for pages 33-34 * Implemented grammatical fixes for pages 31-40 * Updated Matplotlib file to fix pre-commit * Implemented grammatical fixes for pages 41-50 * Update netcdf-cf.ipynb * Update netcdf-cf.ipynb * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update pandas.ipynb * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Update computation-masking.ipynb * Update enso-xarray.ipynb * Update xarray-intro.ipynb --------- Co-authored-by: Julia Kent <[email protected]> Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
ProjectPythia · Apr 24, 2023 · df53323 · df53323
1 parent 7ac805d
commit df53323
Show file tree

Hide file tree

Showing 10 changed files with 469 additions and 468 deletions.
diff --git a/appendix/how-to-contribute.md b/appendix/how-to-contribute.md
@@ -7,12 +7,11 @@ This content is under construction!
 General information on how to contribute to any Project Pythia repository
 may be found [here][pythia contributor's guide].
 
-A full contributor's guide will appear here, cross-referencing our tutorials on open Pull Requests on GitHub.
+This page will eventually contain a full guide to contributing to Project Pythia. As GitHub Pull Requests are an important part of contributing to Pythia, this guide will cross-reference tutorials on GitHub and Pull Requests.
 
-A simple way to comment on anything you find in this book is to use the "open issue" and "suggest edit" buttons under the GitHub Octocat logo at the top of each page. These links will take you to GitHub where the source material for the book is hosted. You'll need a free (and broadly useful) GitHub account. See
-the main [Project Pythia Contributor's Guide][pythia contributor's guide].
+If you need to comment on anything in Pythia Foundations you feel needs work, you can use the "open issue" or "suggest edit" buttons at the top of any Pythia Foundations page. These buttons appear when you hover over the GitHub Octocat logo. Clicking on these buttons will take you to the relevant page on GitHub, where the entirety of the Pythia Foundations material is hosted. In order to actually suggest changes, you must have a free GitHub account, as listed in the GitHub section of Pythia Foundations. This contributor's guide is strictly for Pythia Foundations; for general Project Pythia contribution guidelines, see the main [Project Pythia Contributor's Guide][pythia contributor's guide].
 
-You may also quickly provide feedback via this [Google form](https://docs.google.com/forms/d/e/1FAIpQLSeVa1TC9xM-dk7qIE2e8bsgSrIP82yYDNw3wew3J46eREJa4w/viewform?usp=sf_link).
+To quickly provide feedback about minor issues without the use of GitHub, you can also use this [Google Form](https://docs.google.com/forms/d/e/1FAIpQLSeVa1TC9xM-dk7qIE2e8bsgSrIP82yYDNw3wew3J46eREJa4w/viewform?usp=sf_link).
 
 ## Contributing a new Jupyter Notebook
 

diff --git a/appendix/template.ipynb b/appendix/template.ipynb
diff --git a/core/data-formats.md b/core/data-formats.md
@@ -4,4 +4,4 @@
 This content is under construction!
 ```
 
-This section will contain tutorials on how to interact in Python with data file formats in widespread use in the geosciences, such as NetCDF.
+There are many data file formats used commonly in the geosciences, such as NetCDF and GRIB. This section contains tutorials on how to interact with these files in Python.
diff --git a/core/data-formats/netcdf-cf.ipynb b/core/data-formats/netcdf-cf.ipynb
diff --git a/core/pandas/pandas.ipynb b/core/pandas/pandas.ipynb
diff --git a/core/xarray/computation-masking.ipynb b/core/xarray/computation-masking.ipynb
diff --git a/core/xarray/dask-arrays-xarray.ipynb b/core/xarray/dask-arrays-xarray.ipynb
diff --git a/core/xarray/enso-xarray.ipynb b/core/xarray/enso-xarray.ipynb
@@ -23,7 +23,7 @@
    "source": [
     "## Overview\n",
     "\n",
-    "In this notebook, we will:\n",
+    "In this tutorial, we perform and demonstrate the following tasks:\n",
     "\n",
     "1. Load SST data from the CESM2 model\n",
     "2. Mask data using `.where()`\n",
@@ -62,7 +62,9 @@
     "tags": []
    },
    "source": [
-    "## Imports \n"
+    "## Imports \n",
+    "\n",
+    "For this tutorial, we import several Python packages. As plotting ENSO data requires a geographically accurate map, Cartopy is imported to handle geographic features and map projections. Xarray is used to manage raw data, and Matplotlib allows for feature-rich data plotting. Finally, a custom Pythia package is imported, in this case allowing access to the Pythia example data library."
    ]
   },
   {
@@ -91,15 +93,15 @@
    "metadata": {},
    "source": [
     "\n",
-    "In this notebook, we are going to combine several topics we've covered so far to compute the [Niño 3.4 Index](https://climatedataguide.ucar.edu/climate-data/nino-sst-indices-nino-12-3-34-4-oni-and-tni) for the CESM2 submission for the [CMIP6 project](https://esgf-node.llnl.gov/projects/cmip6/). \n",
+    "In this tutorial, we combine topics covered in previous Xarray tutorials to demonstrate a real-world example. The real-world scenario demonstrated in this tutorial is the computation of the [Niño 3.4 Index](https://climatedataguide.ucar.edu/climate-data/nino-sst-indices-nino-12-3-34-4-oni-and-tni), as shown in the CESM2 submission for the [CMIP6 project](https://esgf-node.llnl.gov/projects/cmip6/). A rough definition of Niño 3.4, in addition to a definition of Niño data computation, is listed below:\n",
     "\n",
     "> Niño 3.4 (5N-5S, 170W-120W): The Niño 3.4 anomalies may be thought of as representing the average equatorial SSTs across the Pacific from about the dateline to the South American coast. The Niño 3.4 index typically uses a 5-month running mean, and El Niño or La Niña events are defined when the Niño 3.4 SSTs exceed +/- 0.4C for a period of six months or more.\n",
     "\n",
-    "> Nino X Index computation: (a) Compute area averaged total SST from Niño X region; (b) Compute monthly climatology (e.g., 1950-1979) for area averaged total SST from Niño X region, and subtract climatology from area averaged total SST time series to obtain anomalies; (c) Smooth the anomalies with a 5-month running mean; (d) Normalize the smoothed values by its standard deviation over the climatological period.\n",
+    "> Niño X Index computation: a) Compute area averaged total SST from Niño X region; b) Compute monthly climatology (e.g., 1950-1979) for area averaged total SST from Niño X region, and subtract climatology from area averaged total SST time series to obtain anomalies; c) Smooth the anomalies with a 5-month running mean; d) Normalize the smoothed values by its standard deviation over the climatological period.\n",
     "\n",
     "![](https://www.ncdc.noaa.gov/monitoring-content/teleconnections/nino-regions.gif)\n",
     "\n",
-    "At the end of this notebook, you should be able to produce a plot that looks similar to this [Oceanic Niño Index plot](https://climatedataguide.ucar.edu/sites/default/files/styles/extra_large/public/2022-03/indices_oni_2_2_lg.png):\n",
+    "The overall goal of this tutorial is to produce a plot of ENSO data using Xarray; this plot will resemble the Oceanic Niño Index plot shown below.\n",
     "\n",
     "![ONI index plot from NCAR Climate Data Guide](https://climatedataguide.ucar.edu/sites/default/files/styles/extra_large/public/2022-03/indices_oni_2_2_lg.png)"
    ]
@@ -110,7 +112,7 @@
     "tags": []
    },
    "source": [
-    "Open the SST and areacello datasets, and use Xarray's `merge` method to combine them into a single dataset:"
+    "In this first example, we begin by opening datasets containing the sea-surface temperature (SST) and grid-cell size data. (These datasets are taken from the Pythia example data library, using the Pythia package imported above.) The two datasets are then combined into a single dataset using Xarray's `merge` method."
    ]
   },
   {
@@ -132,7 +134,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Visualize the first time slice to make sure the data looks as expected:"
+    "This example uses Matplotlib and Cartopy to plot the first time slice of the dataset on an actual geographic map. By doing so, we verify that the data values fit the pattern of SST data:"
    ]
   },
   {
@@ -156,10 +158,7 @@
    "source": [
     "## Select the Niño 3.4 region \n",
     "\n",
-    "There are a couple ways to select the Niño 3.4 region:\n",
-    "\n",
-    "1. Use `sel()` or `isel()`\n",
-    "2. Use `where()` and select all values within the bounds of interest"
+    "In this set of examples, we demonstrate the selection of data values from a dataset which are located in the Niño 3.4 geographic region. The following example illustrates a selection technique that uses the `sel()` or `isel()` method:"
    ]
   },
   {
@@ -176,7 +175,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The other option for selecting our region of interest is to use "
+    "This example illustrates the alternate technique for selecting Niño 3.4 data, which makes use of the `where()` method:"
    ]
   },
   {
@@ -195,7 +194,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Let's plot the selected region to make sure we are doing the right thing."
+    "Finally, we plot the selected region to ensure it fits the definition of the Niño 3.4 region:"
    ]
   },
   {
@@ -220,7 +219,7 @@
    "source": [
     "## Compute the anomalies\n",
     "\n",
-    "We first group by month and subtract the mean SST at each point in the Niño 3.4 region. We then compute the weighted average over the region to obtain the anomalies:"
+    "There are three main steps to obtain the anomalies from the Niño 3.4 dataset created in the previous set of examples. First, we use the `groupby()` method to convert to monthly data. Second, we subtract the mean sea-surface temperature (SST) from the monthly data. Finally, we obtain the anomalies by computing a weighted average. These steps are illustrated in the next example:"
    ]
   },
   {
@@ -238,7 +237,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Now, smooth the anomalies with a 5-month running mean:"
+    "In this example, we smooth the data curve by applying a `mean` function with a 5-month moving window to the anomaly dataset. We then plot the smoothed data against the original data to demonstrate:"
    ]
   },
   {
@@ -266,7 +265,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Compute the standard deviation of the SST in the Nino 3.4 region, over the entire time period of the data array:"
+    "Since the ENSO index conveys deviations from a norm, the calculation of Niño data requires a standard deviation. In this example, we calculate the standard deviation of the SST in the Niño 3.4 region data, across the entire time period of the data array:"
    ]
   },
   {
@@ -283,7 +282,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Then we'll normalize the values by dividing the rolling mean by the standard deviation of the SST in the Niño 3.4 region:"
+    "The final step of the Niño 3.4 index calculation involves normalizing the data. In this example, we perform this normalization by dividing the smoothed anomaly data by the standard deviation calculated above:"
    ]
   },
   {
@@ -306,7 +305,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "We will highlight values in excess of $\\pm$0.5, roughly corresponding to El Niño (warm) and La Niña (cold) events."
+    "In this example, we use Matplotlib to generate a plot of our final Niño 3.4 data. This plot is set up to highlight values above 0.5, corresponding to El Niño (warm) events, and values below -0.5, corresponding to La Niña (cold) events."
    ]
   },
   {
@@ -356,7 +355,7 @@
    "source": [
     "## Summary\n",
     "\n",
-    "We have applied a variety of Xarray's selection, grouping, and statistical functions to compute and visualize an important climate index. "
+    "This tutorial covered the use of Xarray features, including selection, grouping, and statistical functions, to compute and visualize a data index important to climate science."
    ]
   },
   {
@@ -394,7 +393,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.4"
+   "version": "3.10.9"
   },
   "toc-autonumbering": false,
   "toc-showcode": false,