Migrate nsidc data tutorials content

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
 
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.10"
+          python-version: "3.11"
 
       - name: Install package
         run: python -m pip install .[dev]

.gitignore

@@ -2,6 +2,10 @@
 docs/_build/
 docs/api/
 
+# Icepyx-related
+.order_restart
+notebooks/.order_restart
+
 # Temporary local data store
 downloaded-data/
 

docs/conf.py

@@ -80,3 +80,26 @@
 always_document_param_types = True
 
 nb_execution_mode = "off"
+
+
+def copy_notebook_images(app, _exception):
+    """Copy notebook static images into place post-build."""
+    import shutil
+    from pathlib import Path
+
+    source_dir = Path(app.srcdir) / "notebooks" / "img"
+    dest_dir = Path(app.outdir) / "notebooks" / "img"
+
+    if dest_dir.exists():
+        shutil.rmtree(dest_dir)
+
+    shutil.copytree(source_dir, dest_dir)
+
+
+def setup(app):
+    """Setup build-finished action to copy images into place.
+
+    Because the images are only referenced in jupyter notebooks, and not source
+    files parsed directly by sphinx, the images will not be copied on their own.
+    """
+    app.connect("build-finished", copy_notebook_images)

docs/contributing.md

@@ -44,7 +44,8 @@ Available tasks:
 
 ## Jupyter Notebooks
 
-There are Jupyter Notebooks showing `iceflow` functionality under `notebooks/`.
+There are Jupyter Notebooks showing `iceflow` functionality under
+`docs/notebooks/`.
 
 To get started with developing existing or new notebooks, first install the
 notebook-specific dependencies:
@@ -56,15 +57,13 @@ pip install --editable .[notebooks]
 Then:
 
 ```
-cd notebooks/
+cd docs/notebooks/
 jupyter lab
 ```
 
 Develop notebooks and confirm that they work as expected. Before committing
-changes, clear all outputs.
-
-See below for information about adding rendered versions of notebooks to
-ReadTheDocs.
+changes, ensure all cells are evaluated so that outputs are populated. These
+notebooks are included in the docs and will be displayed on ReadTheDocs.
 
 ## Documentation
 
@@ -90,15 +89,6 @@ Please review this carefully and ensure that any changes are accurately
 reflected. On a merge to main, changes to the documentation will be reflected on
 the main, public-facing documentation site.
 
-> [!NOTE] Most of the documentation is designed to be generated automatically.
-> E.g., changes to the API and markdown documents will be automatically
-> refelcted in the documentation. The one exception are the jupyter notebooks
-> (e.g., `iceflow-example.ipynb`), which are static and must be re-generated
-> manually. Use the `invoke docs.render-notebooks-for-docs` task to re-generate
-> these files, and then commit any changes to the repository. See the
-> `notebooks/generate_rendered_notebooks_for_docs.sh` for how to add new
-> rendered notebooks to the docs.
-
 ## Releasing
 
 To release a new version of the software, first update the CHANGELOG.md to
@@ -111,11 +101,21 @@ $ bump-my-version bump {major|minor|patch}
 
 This will update files containing the software version number.
 
-> [!WARNING]
->
-> Please do not attempt to update version numbers by hand!
+:::{warning}
+
+Please do not attempt to update version numbers by hand!
+
+:::
 
 Commit these changes and, once ready, merge them into `main` (through the use of
 a Pull Request on a feature branch). Tag the commit you want to release on
 `main` to initiate a GitHub Action (GHA) that will release the package to
 anaconda.org.
+
+:::{warning}
+
+Jupyter notebooks found in `./notebooks` may need to be re-rendered, depending
+on the changes introduced. It is a good idea to review the notebooks and
+identify any necessary changes that should accompany a PR.
+
+:::

docs/getting-started.md

@@ -2,25 +2,8 @@
 
 ## Jupyter Notebooks
 
-[Jupyter notebooks](https://docs.jupyter.org/en/latest/) provide executable
-examples of how to use `iceflow`:
-
-- [iceflow-example.ipynb](./iceflow-example.ipynb) provides an example of how to
-  search for, download, and interact with `ILATM1B v1` data for a small area of
-  interest. This notebook also illustrates how to perform
-  [ITRF](https://itrf.ign.fr/) transformations to facilitate comparisons across
-  datasets. To learn more about ITRF transformations, see the
-  [corrections.ipynb](https://github.com/nsidc/NSIDC-Data-Tutorials/blob/main/notebooks/iceflow/corrections.ipynb)
-  notebook in the
-  [NSIDC-Data-Tutorials GitHub repository](https://github.com/nsidc/NSIDC-Data-Tutorials).
-
-- [iceflow-with-icepyx.ipynb](./iceflow-with-icepyx.ipynb) shows how to search
-  for, download, and interact with a large amount of data across many datasets
-  supported by `iceflow`. It also illustrates how to utilize
-  [icepyx](https://icepyx.readthedocs.io/en/latest/) to find and access ICESat-2
-  data. Finally, the notebook provides a simple time-series analysis for
-  elevation change over an area of interest across `iceflow` supported datasets
-  and ICESat-2.
+Executable Jupyter Notebooks provide a great starting point for using `iceflow`.
+See [Jupyter Notebooks](./notebooks/index.md) for more information.
 
 ## API overview
 

docs/index.md

@@ -6,8 +6,7 @@
 :caption: content
 
 getting-started.md
-iceflow-example.ipynb
-iceflow-with-icepyx.ipynb
+notebooks/index.md
 contributing.md
 API Docs <api/nsidc>
 LICENSE

docs/notebooks/0_introduction.ipynb

@@ -0,0 +1,147 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<center>\n",
+    "<img src='./img/nsidc_logo.png'/>\n",
+    "\n",
+    "# Altimetry Data at NSIDC\n",
+    "#### Point Cloud Data Overview\n",
+    "</center>\n",
+    "\n",
+    "\n",
+    "\n",
+    "## Altimetry Data Introduction\n",
+    "\n",
+    "<div>\n",
+    "<img align=\"right\" width=\"50%\" height=\"200px\" src='./img/vaex.png'/>\n",
+    "</div>\n",
+    "\n",
+    "This Jupyter notebook aims to teach students and researchers interested in cryospheric sciences about airborne altimetry and related data sets from NASA’s [IceBridge](https://www.nasa.gov/mission_pages/icebridge/index.html) mission, and satellite altimetry data from [ICESat/GLAS](https://icesat.gsfc.nasa.gov/icesat/) and [ICESat-2](https://icesat-2.gsfc.nasa.gov/). Accessing and combining data from these different missions can be difficult as file formats and coordinate reference systems changed over time.\n",
+    "\n",
+    "\n",
+    "### Learning Goals\n",
+    "\n",
+    "After completing this notebook you will understand the basics about pre-IceBridge, IceBridge, ICESat/GLAS and ICESat-2 datasets\n",
+    "\n",
+    "## Mission Overview\n",
+    "\n",
+    "In 2003, NASA launched the Ice, Cloud and Land Elevation Satellite mission with the Geoscience Laser Altimeter System (ICESat/GLAS) instrument onboard. Over the following six years, ICESat/GLAS collected valuable ice thickness data in the Polar Regions. Unfortunately, the ICESat/GLAS mission ended in 2009 before a follow-up mission could be launched. An airborne campaign called Operation IceBridge was funded to fill the gap and continue ice thickness measurements. Between 2009 and 2019, Operation IceBridge flew numerous campaigns over Greenland, the Antarctic ice sheets, and sea ice in the Arctic and Southern Ocean. In September 2018, ICESat-2 was launched to continue NASA's collection of ice, cloud and land elevation data.\n",
+    "\n",
+    "### Pre-IceBridge\n",
+    "\n",
+    "The Airborne Topographic Mapper (ATM) is a conically-scanning laser altimeter that measures the surface topography of a swath of terrain directly beneath the path of an aircraft. ATM surveys can be used to detect surface changes. Differences of laser swaths surveyed over the same area but a few years apart can be used to estimate elevation changes between the first and second survey. Comparing the surveys conducted 1993-4 and 1998-9 resulted in the first comprehensive assessment of the mass balance change of the Greenland ice sheet ([Krabill et al., 1999](https://science.sciencemag.org/content/283/5407/1522), [2000](https://science.sciencemag.org/content/289/5478/428)).  ATM surveys can also be used to calibrate/validate satellite altimeter measurements (e.g. [Martin et al., 2005](https://atm.wff.nasa.gov/files/browser/ATM_Calibration_Procedures_and_Accuracy_Assessment_2012.pdf)).  The ATM was deployed on a wide variety of platforms, including the NASA P3, a Chilean Navy P3, a US Navy P3, the NASA DC8, the NCAR C-130, and a half-dozen Twin Otters to collected high quality topographic data. For a complete list of the ATM deployments visit [https://atm.wff.nasa.gov/deployments/](https://atm.wff.nasa.gov/deployments/)\n",
+    "\n",
+    "### ICESat/GLAS\n",
+    "\n",
+    "ICESat/GLAS was the benchmark Earth Observing System mission for measuring ice sheet mass balance, cloud and aerosol heights, as well as land topography and vegetation characteristics. From 2003 to 2009, the ICESat/GLAS mission provided multi-year elevation data for ice sheet mass balance as well as stratospheric cloud property information over polar areas. This mission also provided topographic and vegetation data from around the globe beyond the polar-specific ice height information over the Greenland and Antarctic ice sheets. Launched on 12 January 2003, after seven years in orbit and 18 laser-operation campaigns, the ICESat/GLAS science mission ended due to the failure of its primary instrument in 2009.\n",
+    "\n",
+    "\n",
+    "### IceBridge\n",
+    "\n",
+    "The operation IceBridge was with its surveying flights from 2009 to 2019 the largest airborne survey of the Earth's polar ice. It has yielded an unprecedented three-dimensional view of the Arctic and Antarctic ice sheets, ice shelves and sea ice. The flights provide a yearly, multi-instrument look at the behavior of the rapidly changing features of the polar ice.\n",
+    "Data collected during Operation IceBridge helps scientists bridge the gap in polar satellite observations between ICESat/GLAS (2003-2009) and ICESat-2 (2018-present). Although the IceBridge data are not continuous its mission became critical for extending the ice altimetry time series in the Arctic and Antarctic, after ICESat/GLAS stopped collecting data in 2009.\n",
+    "\n",
+    "IceBridge flights were generally conducted in March-May over Greenland and in October-November over Antarctica.\n",
+    "\n",
+    "### ICESat-2\n",
+    "\n",
+    "The ICESat-2 mission was designed to provide elevation data needed to determine ice sheet mass balance as well as vegetation canopy information. It provides topographic measurements of cities, lakes and reservoirs, oceans and land surfaces around the globe. The sole instrument on ICESat-2 is the Advanced Topographic Laser Altimeter System (ATLAS), a space-based Lidar. It was designed and built at Goddard Space Flight Center, with the laser generation and detection systems provided by Fibertek. ATLAS measures the travel time of laser photons from the satellite to Earth and back; travel times from multiple laser pulses are used to determine elevation data.\n",
+    "\n",
+    "**Note:** We recommend using the [*icepyx*](https://github.com/icesat2py/icepyx) library to access and interact with ICESat-2 data. \n",
+    "\n",
+    "<p align=\"center\">\n",
+    "<img style=\"align: center;\" width=\"80%\" src='./img/iceflow-coverage.jpg'/>\n",
+    "    <br>\n",
+    "    <b><center>Fig 2. mission coverages</center></b>\n",
+    "</p>\n",
+    "\n",
+    "\n",
+    "## Data Sets and their Spatial and Temporal Coverage\n",
+    "\n",
+    "NSIDC provides a list of all available data sets within each mission including further mission information and documentation for each data set:\n",
+    "* [ICESat/GLAS data sets at NSIDC](https://nsidc.org/data/icesat/data.html)\n",
+    "* [Pre-IceBridge and IceBridge data sets at NSIDC](https://nsidc.org/data/icebridge/data_summaries.html)\n",
+    "* [ICESat-2 data sets at NSIDC](https://nsidc.org/data/icesat-2/data-sets)\n",
+    "\n",
+    "\n",
+    "---\n",
+    "\n",
+    "\n",
+    "|Data Set| Spatial Coverage | Temporal Coverage| Mission  | Sensors  |\n",
+    "|--------|------------------|------------------|------------|---------|\n",
+    "|[BLATM L1B](https://nsidc.org/data/BLATM1B)| South: N:-53, S: -90, E:180, W:-180 <br> North: N:90, S: 60, E:180, W:-180 | 23 Jun. 1993 - 30 Oct. 2008 | Pre-IceBridge | ATM\n",
+    "|[ILATM L1B V1](https://nsidc.org/data/ILATM1B/versions/1) | South: N:-53, S: -90, E:180, W:-180 <br> North: N:90, S: 60, E:180, W:-180 | 31 Mar. 2009 - 8 Nov. 2012  <br> (updated 2013) | IceBridge | ATM\n",
+    "|[ILATM L1B V2](https://nsidc.org/data/ILATM1B/versions/2)| South: N:-53, S: -90, E:180, W:-180 <br> North: N:90, S: 60, E:180, W:-180 | 20 Mar. 2013 - 16 May 2019  <br> (updated 2020)| IceBridge|ATM\n",
+    "|[ILVIS2](https://nsidc.org/data/ILVIS2)| North: N:90, S: 60, E:180, W:-180|25 Aug. 2017 - 20 Sept. 2017|IceBridge | ALTIMETERS, LASERS, LVIS\n",
+    "|[GLAH06](https://nsidc.org/data/GLAH06/)| Global: N:86, S: -86, E:180, W:-180|20 Feb. 2003 - 11 Oct. 2009|ICESat/GLAS | ALTIMETERS, CD, GLAS, GPS, <br> GPS Receiver, LA, PC\n",
+    "\n",
+    "\n",
+    "--- \n",
+    "\n",
+    "**Note**: If you have questions about the data sets please refer to the user guides or contact NSIDC user services at [email protected]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Challenges\n",
+    "\n",
+    "The wealth of data from these missions presents an opportunity to study the evolution of ice thickness over several decades. However, combining data from these missions presents several challenges:\n",
+    "\n",
+    "* Data from the Airborne Topographic Mapper (ATM) flown during the IceBridge campaigns is stored in four different file formats. ICESat/GLAS and ICESat-2 data are also in different file formats. Therefore, the data needs to be harmonized, that means placed into similar formats before comparisons can be made.\n",
+    "* The coordinate reference systems used to locate measurements have changed over the years, as the Earth's surface is not static and changes shape. To account for these changes, terrestrial reference frames that relate latitude and longitude to points on the Earth are updated on a regular basis. Since the launch of ICESat/GLAS, the International Terrestrial Reference Frame [(ITRF)](https://www.iers.org/IERS/EN/DataProducts/ITRF/itrf.html) has been updated three times. The geolocation of a point measured at the beginning of the record and the end of the record is not the same even though the latitude and longitude is the same. These changes in geolocation need to be reconciled to allow meaningful comparisons within the long-term data record.\n",
+    "\n",
+    "The `iceflow` Python library addresses these concerns by providing the ability to search, download, and access laser altimetry data from (pre-)Operation IceBridge and ICESat/GLAS datasets. The library also supports International Terrestrial Reference Frame (ITRF) transformations to facilitate comparisons across datasets.\n",
+    "\n",
+    "Companion Jupyter notebooks give additional information and contain example code about `iceflow`.\n",
+    "\n",
+    "[NSIDC Iceflow example](./iceflow-example) provides an example of how to search for, download, and interact with `ILATM1B v1` data for a small area of interest. This notebook also illustrates how to perform [ITRF](https://itrf.ign.fr/) transformations to facilitate comparisons across datasets. To learn more about ITRF transformations, see the [Applying Coordinate Transformations to Facilitate Data Comparison](./corrections) notebook.\n",
+    "\n",
+    "[Using iceflow with icepyx to Generate an Elevation Timeseries](./iceflow-with-icepyx) shows how to search for, download, and interact with a large amount of data across many datasets supported by `iceflow`. It also illustrates how to utilize [icepyx](https://icepyx.readthedocs.io/en/latest/) to find and access ICESat-2 data. Finally, the notebook provides a simple time-series analysis for elevation change over an area of interest across `iceflow` supported datasets and ICESat-2."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## References\n",
+    "1. [Airborne Topographic Mapper Calibration Procedures and Accuracy Assessment](https://ntrs.nasa.gov/archive/nasa/casi.ntrs.nasa.gov/20120008479.pdf)\n",
+    "2. [Open Source Tools for Point Cloud Processing, Storage, Subsetting, and Visualization](https://sea.ucar.edu/sites/default/files/kbeam_seaconf18.pdf)\n",
+    "\n",
+    "## Related Tools\n",
+    "\n",
+    "* [OpenAltimetry](https://openaltimetry.earthdatacloud.nasa.gov/data/): Advanced discovery, processing, and visualization services for ICESat and ICESat-2 altimeter data\n",
+    "* [ITS_LIVE](https://its-live.jpl.nasa.gov/): A NASA MEaSUREs project to provide automated, low latency, global glacier flow and elevation change data sets.\n",
+    "\n",
+    "## Next steps\n",
+    "\n",
+    "With the knowledge gained in this notebook, users should be prepared for the [NSIDC Iceflow example](./iceflow-example) notebook, which provides an example of how to search for, download, and interact with `ILATM1B v1` data for a small area of interest with the `iceflow` library."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}