notebooks/iceflow/1_widget.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "<center>\n",
    "<img src='./img/nsidc_logo.png'/>\n",
    "\n",
    "# **IceFlow**\n",
    "### Point Cloud Data Access\n",
    "</center>\n",
    "\n",
    "# Accessing Data with the IceFlow Widget\n",
    "\n",
    "\n",
    "### NASA's Earthdata Credentials\n",
    "\n",
    "To access data using the *IceFlow* library it is necessary to log into [Earthdata Login](https://urs.earthdata.nasa.gov/). To do this, enter your NASA Earthdata credentials in the next step after executing the following code cell.\n",
    "\n",
    "**Note**: If you don't have NASA Earthdata credentials you have to register first at the link above. You don't need to be a NASA employee to register with NASA Earthdata!\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# Importing IceFlow client library\n",
    "from iceflow.ui import IceFlowUI\n",
    "from iceflow.client import IceflowClient\n",
    "import earthaccess\n",
    "# Instantiateing the client\n",
    "ui = IceFlowUI()\n",
    "ifc = IceflowClient()\n",
    "# You need to use your NASA Earthdata Credentials and verify that they work.\n",
    "# Please click on set credentials and then see if authentication is successful by executing the next cell.\n",
    "auth = earthaccess.login()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# This cell will verify if your credentials are valid. \n",
    "# This may take a little while, if it fails for some reason try again.\n",
    "# NOTE: Wednesday mornings are usually downtime for NSIDC services and you might experience difficulties accessing data.\n",
    "authorized = ifc.authenticate(auth.username, auth.password, auth.user_profile[\"email_address\"])\n",
    "if authorized:\n",
    "    print(\"We are logged into NSIDC's data ordering system\")\n",
    "    ui.iceflow  = ifc"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Note:** To view the widget output you need to enable Jupyter's log console. You can activate the console by clicking the right-most icon at the bottom of your browser <img src='./img/log-icons.png'> or by slecting “View” >> “Show log console” on the menu bar.\n",
    "\n",
    "Let's start loading the user interface. Next, we will explain all options and user interface components.\n",
    "vertical = Sidecar widget, horizontal = render the widget in this notebook. Note that depending on your screen size and resolution the 'vertical' display option may not work correctly. This is a current bug in the jupyter-widget that can not be solved within the scope of IceFlow."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "ui.display_map('horizontal', extra_layers=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "#### IceFlow user interface (UI) components\n",
    "\n",
    "\n",
    "This user interface uses [*ipyleaflet*](https://blog.jupyter.org/interactive-gis-in-jupyter-with-ipyleaflet-52f9657fa7a) which allows us to draw\n",
    "polygons or bounding boxes to delimit our area of interest. We can also edit and delete these geometries using the widget controls in the map.\n",
    "<br> \n",
    "<br>**The following list describes all user interface data selection options:**\n",
    "\n",
    "- **Hemisphere**: Choose which map projection you are going to use, you can pick global, north or south.\n",
    "\n",
    "- **Data sets**: Choose one ore more data sets from the selection. For more than one data set use \"CTRL+Space\" or \"CTRL+Click\" on Windows and Linux or \"command+click\" on a Mac. Note: ATM1B includes the 3 different ATM products (BLATM L1B, ILATM L1B v1, ILATM L1B V2), see the above table for more details.\n",
    "\n",
    "- **ITRF (optional)**: Choose an International Terrestrial Reference Frame for more details see [ITRF](corrections.ipynb).\n",
    "\n",
    "- **Epoch (optional)**: Populate this field with the epoch value in which you want the coordinate reference systems to be based. This can only be applied if a ITRF is selected. (e.g. if you use 2010.1 and ITRF 2014 then all the points will be shifted to match the best ground representation as if they were in January 2010. This is compensating for plate tectonic motion.)\n",
    "\n",
    "- **ICESat-2**: If you additionally want to place a data order for ICESat-2 data (using icepyx) utilizing the current parameters you need to select the short name code of the desired data set i.e. ATL06. \n",
    "\n",
    "- **Date Range**: This slider control allows you to select a start and end date of interest.\n",
    "\n",
    "- **Inside Map options**: In the map part of the widget, you can zoom in and out, draw a polygon or bounding boxes and edit them to select an area of interest.  You can also turn on and off the layers that show IceBridge flights and Ice Velocities.\n",
    "\n",
    "**The following list describes all user interface buttons:**\n",
    "\n",
    "- The **Get Raw Granule Count** button will query [NASA's CMR](https://earthdata.nasa.gov/eosdis/science-system-description/eosdis-components/cmr) to get a granule count for the current parameters, you need to have a geometry and one or more data sets selected. The result of the query gets displayed in the log window. **Important:** Check the selected raw granule count before placing an order. As a rule of thumb, you can expect a wait time of approximately 10 minutes each 1 Gigabyte of data selected. Keep in mind to run this notebook locally (not with the Binder) if you have large data orders as the Binder will time out after approximately 10 minutes.\n",
    "\n",
    "- The **Print Current Parameter** button displays the selected start and end time, bounding box and data set(s) in the log window.\n",
    "\n",
    "- The **Place Data Order** button will submit an *IceFlow* order using the current user interface parameters, this is an **asynchronous** process, you will have to wait until the order is completed before you can work with the data or place a new order but this does not block you from exploring the rest of the notebook while waiting for the order to complete.\n",
    "\n",
    "- The **Check Order Status** button will output the status of the order in the log window.\n",
    "\n",
    "- The **Download Data Order** button will download the data from an order that has been completed.\n",
    "\n",
    "**Notes**: \n",
    "* If you use the bounding box geometry in a polar projection, you'll notice a distortion due the nature of polar coordinates, if you prefer, you can use the global Mercator map to draw a bounding box without apparent distortion. The better option is to draw a polygon or enter your exact desired coordinates. [How to do that will be covered later in this tutorial.] \n",
    "* The calculated download size of these granules is an upper bound since *IceFlow* allows us to subset the data. \n"
   ]
  }
 ],
 "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.9.16"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}