{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "1e29ff05",
   "metadata": {},
   "source": [
    "# Visualizing ICESat-2 Elevations\n",
    "\n",
    "This notebook ({nb-download}`download <IS2_data_visualization.ipynb>`) demonstrates interactive ICESat-2 elevation visualization by requesting data from [OpenAltimetry](https://www.openaltimetry.org/) based on metadata provided by [icepyx](https://icepyx.readthedocs.io/en/latest/). We will show how to plot spatial extent and elevation interactively.\n",
    "\n",
    "> ⚠️ **Some of this notebook is currently non-functional**\n",
    ">\n",
    "> Visualizations requiring the\n",
    "> [OpenAltimetry API](https://openaltimetry.earthdatacloud.nasa.gov/data/openapi/swagger-ui/index.html)\n",
    "> are currently unavailable (since ~October 2023).\n",
    "> The API changed and we haven't yet updated this notebook correspondingly."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6333399a",
   "metadata": {},
   "source": [
    "Import packages"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "157dfbe8",
   "metadata": {},
   "outputs": [],
   "source": [
    "import icepyx as ipx"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "57f2cfd8",
   "metadata": {},
   "source": [
    "## Create an ICESat-2 query object\n",
    "\n",
    "Set the desired parameters for your data visualization.\n",
    "\n",
    "For details on minimum required inputs, please refer to [IS2_data_access](https://icepyx.readthedocs.io/en/latest/example_notebooks/IS2_data_access.html). If you are using a spatial extent input other than a bounding box for your search, it will automatically be converted to a bounding box for the purposes of visualization ONLY (your query object will not be affected)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "926496ad",
   "metadata": {},
   "outputs": [],
   "source": [
    "#bounding box\n",
    "#Larsen C Ice Shelf\n",
    "short_name = 'ATL06'\n",
    "date_range = ['2020-7-1', '2020-8-1']\n",
    "spatial_extent = [-67, -70, -59, -65] \n",
    "cycles = ['03']\n",
    "tracks = ['0948', '0872', '1184', '0186', '1123', '1009', '0445', '0369']"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "71142c20",
   "metadata": {},
   "outputs": [],
   "source": [
    "# # polygon vertices\n",
    "# short_name = 'ATL06'\n",
    "# date_range = ['2019-02-20','2019-02-28']\n",
    "# spatial_extent = [(-55, 68), (-55, 71), (-48, 71), (-48, 68), (-55, 68)]"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "119dbcb0",
   "metadata": {},
   "outputs": [],
   "source": [
    "# # polygon geospatial file\n",
    "# short_name = 'ATL06'\n",
    "# date_range = ['2019-10-01','2019-10-05']\n",
    "# spatial_extent = './supporting_files/data-access_PineIsland/glims_polygons.shp'"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bbece76a-1776-489f-9ef5-78a704057bb4",
   "metadata": {},
   "outputs": [],
   "source": [
    "region = ipx.Query(short_name, spatial_extent, date_range)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8fbae0e7",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(region.product)\n",
    "print(region.dates)\n",
    "print(region.start_time)\n",
    "print(region.end_time)\n",
    "print(region.product_version)\n",
    "print(list(set(region.avail_granules(cycles=True)[0]))) #region.cycles\n",
    "print(list(set(region.avail_granules(tracks=True)[0]))) #region.tracks"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b178836",
   "metadata": {},
   "source": [
    "## Visualize spatial extent \n",
    "By calling function `visualize_spatial_extent`, it will plot the spatial extent in red outline overlaid on a basemap, try zoom-in/zoom-out to see where is your interested region and what the geographic features look like in this region."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ec9777b0-b3e5-4cb5-85a3-35ad1ff982ac",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "region.visualize_spatial_extent()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "71ca513d",
   "metadata": {},
   "source": [
    "## Visualize ICESat-2 elevation using OpenAltimetry API\n",
    "\n",
    "**Note: this function currently only supports products `ATL06, ATL07, ATL08, ATL10, ATL12, ATL13`**\n",
    "\n",
    "Now that we have produced an interactive map showing the spatial extent of ICESat-2 data to be requested from NSIDC using icepyx, what if we want to have a quick check on the ICESat-2 elevations we plan to download from NSIDC? [OpenAltimetry API](https://openaltimetry.org/data/swagger-ui/#/) provides a nice way to achieve this. By sending metadata (product, date, bounding box, trackId) of each ICESat-2 file to the API, it can return elevation data almost instantaneously. The major drawback is requests are limited to 5x5 degree spatial bounding box selection for most of the ICESat-2 L3A products [ATL06, ATL07, ATL08, ATL10, ATL12, ATL13](https://icesat-2.gsfc.nasa.gov/science/data-products). To solve this issue, if you input spatial extent exceeds the 5 degree maximum in either horizontal dimension, your input spatial extent will be split into 5x5 degree lat/lon grids first, use icepyx to query the metadata of ICESat-2 files located in each grid, and send each request to OpenAltimetry. Data sampling rates are 1/50 for ATL06 and 1/20 for other products.\n",
    "\n",
    "There are multiple ways to access icepyx's visualization module. This option assumes you are visualizing the data as part of a workflow that will result in a data download. Alternative options for accessing the OpenAltimetry-based visualization module directly are provided at the end of this example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "93a712af-ab1f-4d79-834d-c2735a5677a8",
   "metadata": {
    "scrolled": true,
    "tags": []
   },
   "outputs": [],
   "source": [
    "cyclemap, rgtmap = region.visualize_elevation()\n",
    "cyclemap"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9ee72a5c",
   "metadata": {},
   "source": [
    "#### Plot elevation for individual RGT\n",
    "\n",
    "The visualization tool also provides the option to view elevation data by latitude for each ground track."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "802e5c6e",
   "metadata": {},
   "outputs": [],
   "source": [
    "rgtmap"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b7082edd",
   "metadata": {},
   "source": [
    "### Move on to data downloading from NSIDC if these are the products of interest\n",
    "\n",
    "For more details on the data ordering and downloading process, see [ICESat-2_DAAC_DataAccess_Example](https://github.com/icesat2py/icepyx/blob/main/examples/ICESat-2_DAAC_DataAccess_Example.ipynb)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "05f91e82",
   "metadata": {},
   "outputs": [],
   "source": [
    "region.order_granules()\n",
    "\n",
    "#view a short list of order IDs\n",
    "region.granules.orderIDs\n",
    "\n",
    "path = 'your data directory'\n",
    "region.download_granules(path)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "textile-casting",
   "metadata": {},
   "source": [
    "### Alternative Access Options to Visualize ICESat-2 elevation using OpenAltimetry API\n",
    "\n",
    "You can also view elevation data by importing the visualization module directly and initializing it with your query object or a list of parameters:\n",
    " ```python\n",
    " from icepyx.core.visualization import Visualize\n",
    " ```\n",
    " - passing your query object directly to the visualization module\n",
    " ```python\n",
    " region2 = ipx.Query(short_name, spatial_extent, date_range)\n",
    " vis = Visualize(region2)\n",
    " ```\n",
    " - creating a visualization object directly without first creating a query object\n",
    " ```python\n",
    " vis = Visualize(product=short_name, spatial_extent=spatial_extent, date_range=date_range)\n",
    " ```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "55d18a37",
   "metadata": {},
   "source": [
    "#### Credits\n",
    "* Notebook by: [Tian Li](https://github.com/icetianli), [Jessica Scheick](https://github.com/JessicaS11) and \n",
    "[Wei Ji](https://github.com/weiji14)\n",
    "* Source material: [READ_ATL06_DEM Notebook](https://github.com/ICESAT-2HackWeek/Assimilation/blob/master/contributors/icetianli/READ_ATL06_DEM.ipynb) by Tian Li and [Friedrich Knuth](https://github.com/friedrichknuth)"
   ]
  }
 ],
 "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.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}