Merge branch 'main' into earthaccess

_quarto.yml

@@ -46,6 +46,9 @@ website:
         - section: "GEDI / IS2 Science Tutorial"
           contents: 
             - tutorials/index.md
+            - href: tutorials/GEDI_data_SSC23.ipynb
+              text: "GEDI Level 2B V002 Data"
+
 
 format:
   html:

tutorials/data-access/index.ipynb

@@ -8,56 +8,204 @@
    },
    "source": [
     "# **Accessing and working with ICESat-2 data in the cloud**\n",
-    "    \n",
     "\n",
     "## **1. Tutorial Overview**\n",
     "\n",
-    "Outline:\n",
-    "* ICESat-2 Data Access, NASA DAAC @ NSIDC\n",
-    "    * Overview of ICESat-2 Mission and land products ([see USFS Application Workshop slides](https://docs.google.com/presentation/d/1SZs7dyZ1K2CSVXS0txZ-LIvc-5Brn_D0pBEtzfQmvcE/edit#slide=id.g2374337d1d0_0_184)\n",
-    "    * NSIDC DAAC resources / tools\n",
-    "        * Walk through myriad options with different capabilities/use cases \n",
-    "        * Modified version of [table from IS2 Hackweek](https://icesat-2-2023.hackweek.io/tutorials/data-access-and-format/overview.html)\n",
-    "    * Basic earthaccess demo of ATL08 access\n",
-    "        * Need common area / time of interest across IS2 / GEDI tutorials\n",
+    "### Introduction\n",
     "\n",
-    "* The icepyx Software Library and Community\n",
+    "The purpose of this notebook is to provide an introduction to the land and water data available from the NASA ICESat-2 Mission, along with an overview of data search and access options for the data. We will then provide examples in python for how to search and access the data using the `earthaccess` and `icepyx` software libraries.\n",
     "\n",
-    "### Intro (update) \n",
+    "### **Credits**\n",
     "\n",
-    "This notebook demonstrates searching for cloud-hosted ICESat-2 data and directly accessing Land Ice Height (ATL06) granules from an Amazon Compute Cloud (EC2) instance using the `earthaccess` package. NASA data \"in the cloud\" are stored in Amazon Web Services (AWS) Simple Storage Service (S3) Buckets. **Direct Access** is an efficient way to work with data stored in an S3 Bucket when you are working in the cloud. Cloud-hosted granules can be opened and loaded into memory without the need to download them first. This allows you take advantage of the scalability and power of cloud computing. \n",
+    "The notebook was created by Rachel Wegener, University of Maryland; Luis Lopez, NSIDC DAAC; and Amy Steiker, NSIDC DAAC.\n",
     "\n",
-    "The Amazon Global cloud is divided into geographical regions.  To have direct access to data stored in a region, our compute instance - a virtual computer that we create to perform processing operations in place of using our own desktop or laptop - must be in the same region as the data.  This is a fundamental concept of _analysis in place_. **NASA cloud-hosted data is in Amazon Region us-west2.  So your compute instance must also be in us-west2.** If we wanted to use data stored in another region, to use direct access for that data, we would start a compute instance in that region.\n",
+    "### **Learning Objectives**\n",
     "\n",
-    "As an example data  collection, we use ICESat-2 Land Ice Height (ATL06) over the Juneau Icefield, AK, for March 2003. ICESat-2 data granules, including ATL06, are stored in HDF5 format. We demonstrate how to open an HDF5 granule and access data variables using `xarray`. Land Ice Heights are then plotted using `hvplot`. \n",
+    "By the end of this demonstration you will be able to:  \n",
     "\n",
-    "`earthaccess` is a package developed by Luis Lopez (NSIDC developer) to allow easy search of the NASA Common Metadata Repository (CMR) and download of NASA data collections.  It can be used for programmatic search and access for both _DAAC-hosted_ and _cloud-hosted_ data. It manages authenticating using Earthdata Login credentials which are then used to obtain the S3 tokens that are needed for S3 direct access. https://github.com/nsidc/earthaccess\n",
+    "1. Learn about the coverage, resolution, and structure of land and water data from the NASA ICESat-2 mission;\n",
+    "2. Understand the available resources at the National Snow and Ice Data Center (NSIDC), including user support documents, data access options, and data tools and services such as OpenAltimetry;\n",
+    "3. Use `earthaccess` and `hvplot` to search, access, and visualize ICESat-2 data within a cloud environment. \n",
+    "4. Use `icepyx` to explore and subset variables within ICESat-2 land height files. \n",
     "\n",
+    "### **Prerequisites**\n",
     "\n",
-    "### **Credits**\n",
+    "See [Prerequisites](https://nasa-openscapes.github.io/2023-ssc/tutorials/prerequisites.html)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "76516cb7-7c90-4461-9e88-3481c60b79a8",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "## **2. NASA's ICESat-2 Mission: Land and Water Products**"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "8ba67dda-4523-4992-962b-3ed3e2dbd28a",
+   "metadata": {},
+   "source": [
+    "### Introduction to ICESat-2 \n",
     "\n",
-    "The notebook was created by ... \n",
+    "A quick summary of the ICESat-2 Mission and its instrument, ATLAS: Advanced Topographic Laser Altimeter System:\n",
     "\n",
+    "* Height determined using round-trip travel time of laser light (photon counting lidar)\n",
+    "* 10,000 laser pulses released per second, split into 3 weak/strong beam pairs at a wavelength of 532 nanometers (bright green on the visible spectrum).\n",
+    "* Measurements taken every 70 cm along the satellite's ground track, roughly 11 m wide footprint.\n",
     "\n",
-    "### **Learning Objectives [UPDATE] **\n",
+    "The number of photons that return to the telescope depends on surface reflectivity and cloud cover (which obscures ATLAS's view of Earth). As such, the spatial resolution of signal photons varies.\n",
     "\n",
-    "By the end of this demonstration you will be able to:  \n",
-    "1. use `earthaccess` to search for ICESat-2 data using spatial and temporal filters and explore search results;  \n",
-    "2. open data granules using direct access to the ICESat-2 S3 bucket;  \n",
-    "3. load a HDF5 group into an `xarray.Dataset`;  \n",
-    "4. visualize the land ice heights using `hvplot`.  \n",
+    "![ICESat-2 Beam Structure](.images/icesat2-schematic.png)  "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c443cc21-1191-47dd-8f3c-2ce0bce77b4c",
+   "metadata": {},
+   "source": [
+    "### ICESat-2: Land and Water Products \n",
     "\n",
-    "### **Prerequisites**\n",
+    "There are over 20 ICESat-2 data products, structured by processing level and surface type:\n",
     "\n",
-    "See [Prerequisites](https://nasa-openscapes.github.io/2023-ssc/tutorials/prerequisites.html)"
+    "![ICESat-2 land and water products](.images/land-veg-products.png)  \n",
+    "\n",
+    "Additional quick look products are available:\n",
+    "\n",
+    "* Satellite observations available within 3 days, versus 30-45 days for standard products\n",
+    "* Supports decision-making applications: vegetation height, surface water and flooding, land surface deformation from landslides and volcanoes\n",
+    "* Note that geolocation and height uncertainty is greater for these products (see user guides for more info) \n",
+    "\n",
+    "[L3A Land and Vegetation Height Quick Look (ATL08QL)](https://nsidc.org/data/atl08QL/)\n",
+    "\n",
+    "[L3A Along Track Inland Surface Water Data Quick Look (ATL13QL)](https://nsidc.org/data/atl13QL/)\n",
+    "\n",
+    "See https://nsidc.org/data/icesat-2/products for more details."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a0bd3942-99dc-4102-a243-c392b5e1fcd5",
+   "metadata": {},
+   "source": [
+    "### ATLAS/ICESat-2 L3A Land and Vegetation Height (ATL08)\n",
+    "\n",
+    "https://doi.org/10.5067/ATLAS/ATL08.006 \n",
+    "\n",
+    "\n",
+    "ATL08 contains heights for both terrain and canopy in the along-track direction, plus\n",
+    "other descriptive parameters. \n",
+    "* Data are derived from geolocated, time-tagged photon heights from the ATLAS/ICESat-2 L2A Global Geolocated Photon Data (ATL03) product.\n",
+    "\n",
+    "**Spatial Resolution**\n",
+    "* Canopy and ground surfaces are processed in fixed 100 m data segments\n",
+    "* Each segment typically contain more than 100 signal photons but may contain less. \n",
+    "\n",
+    "**Temporal Resolution**\n",
+    "* 91-day repeat cycle along each of ATLAS/ICESat-2's 1,387 Reference Ground Tracks (RGTs)\n",
+    "\n",
+    "**Uncertainty**\n",
+    "* Expected ranging precision for flat surfaces: Standard deviation of ~25 cm.\n",
+    "* Terrain height uncertainty estimates depend on ATL03, and local uncertainties within each 100 m segment\n",
+    "\n",
+    "See the [ATL08 User Guide](https://nsidc.org/sites/default/files/documents/user-guide/atl08-v006-userguide.pdf) for more information. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "6eb4be8f-46cd-47b7-94d9-5c0cad1c0fd5",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "## **3. Overview of ICESat-2 NSIDC DAAC Data, Tools, and Resources**"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "a6f62b23-7cf7-4eec-9e63-094e7d3106a1",
+   "metadata": {},
+   "source": [
+    "### Overview of NSIDC data and resources\n",
+    "\n",
+    "The NASA National Snow and Ice Data Center Distributed Active Archive Center ([NSIDC DAAC](https://nsidc.org/data/data-programs/nsidc-daac)) provides over 800 data sets covering the Earth's cryosphere and more, all of which are available to the public free of charge. These data can be used to study topics relating to snow cover, sea ice, ice sheets, ice shelves, glaciers, frozen ground, soil moisture, climate interactions, and more. Beyond providing these data, NSIDC creates tools for data access, supports data users, performs scientific research, and educates the public about the cryosphere.\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "47bc72ca-5fda-4b5b-9bb1-d1946c790bb4",
+   "metadata": {},
+   "source": [
+    "#### Data Access Tools for ICESat-2 \n",
+    "\n",
+    "There are many tool and access options available for ICESat-2, which can be found on each of the dataset landing pages on NSIDC's website. See the [**ATL08 Data Access & Tools**](https://nsidc.org/data/atl08/versions/6#anchor-1) section as an example. This notebook will descibe three of those options in more detail: [OpenAltimetry](https://openaltimetry.earthdatacloud.nasa.gov/data/icesat2/), [icepyx](https://icepyx.readthedocs.io/en/latest/), and [earthaccess](https://nsidc.github.io/earthaccess/). \n",
+    "\n",
+    "**Using OpenAltimetry to Visualize ICESat-2 Data**\n",
+    "\n",
+    "Key functions of [OpenAltimetry](https://openaltimetry.earthdatacloud.nasa.gov/data/icesat2/) include:\n",
+    "* Ground track filtering and visualization\n",
+    "* On-the-fly plotting of segment elevations and photon clouds based date and region of interest\n",
+    "* Access data in CSV or subsetted HDF5 format\n",
+    "* Plot and analyze photon data from your area of interest using a Jupyter Notebook\n",
+    "\n",
+    "Upload a shapefile of interest; view track coverage:\n",
+    "![](.images/oa-viz.png)  \n",
+    "\n",
+    "Select a region; view elevation profile:\n",
+    "![](.images/oa-plot.png) \n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "810c992e-d16a-4668-a7f4-76c1747e207f",
+   "metadata": {},
+   "source": [
+    "#### Navigating ICESat-2 Tool & Access options:\n",
+    "\n",
+    "This table provides an overview of the capabilities across the tools and services highlighted in this notebook:\n",
+    "\n",
+    "\n",
+    "|                                             | `icepyx` | `earthaccess` | OpenAltimetry |\n",
+    "|---------------------------------------------|----------|---------------|---------------|\n",
+    "| Filter spatially using:                     |          |               |               |\n",
+    "| - Interactive map widget                    |          |               | x             |\n",
+    "| - Bounding Box                              | x        | x             | x             |\n",
+    "| - Polygon                                   | x        | x             |               |\n",
+    "| - GeoJSON or Shapefile                      | x        |               | x             |\n",
+    "| Filter by time and date                     | x        | x             | x             |\n",
+    "| Preview data                                | x        | x             | x             |\n",
+    "| Download data from DAAC                     | x        | x             | x             |\n",
+    "| Access cloud-hosted data                    | x        | x             |               |\n",
+    "| Subset (spatially, temporally, by variable) | x        |               | x             |\n",
+    "| Plot data with built-in methods             | x        |               | x             |\n",
+    "\n"
    ]
   },
   {
    "cell_type": "markdown",
    "id": "816f31af",
+   "metadata": {
+    "tags": []
+   },
+   "source": [
+    "## **4. Search and access of ATL08 using `earthaccess`**\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "b75fc7fe-9d2c-489a-add9-df02b0c96146",
    "metadata": {},
    "source": [
-    "## **2. Tutorial steps**\n",
+    "This notebook demonstrates searching for cloud-hosted ICESat-2 data and directly accessing Land Ice Height (ATL06) granules from an Amazon Compute Cloud (EC2) instance using the `earthaccess` package. NASA data \"in the cloud\" are stored in Amazon Web Services (AWS) Simple Storage Service (S3) Buckets. **Direct Access** is an efficient way to work with data stored in an S3 Bucket when you are working in the cloud. Cloud-hosted granules can be opened and loaded into memory without the need to download them first. This allows you take advantage of the scalability and power of cloud computing. \n",
+    "\n",
+    "The Amazon Global cloud is divided into geographical regions.  To have direct access to data stored in a region, our compute instance - a virtual computer that we create to perform processing operations in place of using our own desktop or laptop - must be in the same region as the data.  This is a fundamental concept of _analysis in place_. **NASA cloud-hosted data is in Amazon Region us-west2.  So your compute instance must also be in us-west2.** If we wanted to use data stored in another region, to use direct access for that data, we would start a compute instance in that region.\n",
+    "\n",
+    "As an example data  collection, we use ICESat-2 Land Ice Height (ATL06) over the Juneau Icefield, AK, for March 2003. ICESat-2 data granules, including ATL06, are stored in HDF5 format. We demonstrate how to open an HDF5 granule and access data variables using `xarray`. Land Ice Heights are then plotted using `hvplot`. \n",
+    "\n",
+    "`earthaccess` is a package developed by Luis Lopez (NSIDC developer) to allow easy search of the NASA Common Metadata Repository (CMR) and download of NASA data collections.  It can be used for programmatic search and access for both _DAAC-hosted_ and _cloud-hosted_ data. It manages authenticating using Earthdata Login credentials which are then used to obtain the S3 tokens that are needed for S3 direct access. https://github.com/nsidc/earthaccess\n",
     "\n",
     "## Import Packages\n",
     "\n",
@@ -98,7 +246,10 @@
   {
    "cell_type": "markdown",
    "id": "15ae2994",
-   "metadata": {},
+   "metadata": {
+    "jp-MarkdownHeadingCollapsed": true,
+    "tags": []
+   },
    "source": [
     "## Authenticate\n",
     "\n",
@@ -124,7 +275,9 @@
   {
    "cell_type": "markdown",
    "id": "28d7b582",
-   "metadata": {},
+   "metadata": {
+    "tags": []
+   },
    "source": [
     "## Search for ICESat-2 Collections\n",
     "\n",
@@ -227,7 +380,10 @@
   {
    "cell_type": "markdown",
    "id": "8df10797",
-   "metadata": {},
+   "metadata": {
+    "jp-MarkdownHeadingCollapsed": true,
+    "tags": []
+   },
    "source": [
     "## Search a data set using spatial and temporal filters \n",
     "\n",
@@ -280,6 +436,7 @@
    "cell_type": "markdown",
    "id": "810da59e",
    "metadata": {
+    "jp-MarkdownHeadingCollapsed": true,
     "tags": []
    },
    "source": [
@@ -334,7 +491,10 @@
   {
    "cell_type": "markdown",
    "id": "0a4335c8",
-   "metadata": {},
+   "metadata": {
+    "jp-MarkdownHeadingCollapsed": true,
+    "tags": []
+   },
    "source": [
     "## **3. Learning outcomes recap**\n",
     "\n",