Uavsar tutorial sections

book/_toc.yml

@@ -46,6 +46,12 @@ parts:
             - file: tutorials/database/5_plot_raster_example
             - file: tutorials/database/6_exporting_data
             - file: tutorials/database/7_wrap_up
+        - file: tutorials/uavsar/index
+          title: Uavsar
+          sections:
+            - file: tutorials/uavsar/1_accessing_imagery
+            - file: tutorials/uavsar/2_types_of_uavsar_images
+            - file: tutorials/uavsar/3_interferometric_swe_inversion
         - file: tutorials/core-datasets/index
           title: SnowEx Mission and Dataset Descriptions
           sections:

book/tutorials/uavsar/1_accessing_imagery.ipynb

@@ -0,0 +1,217 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# UAVSAR\n",
+    "\n",
+    ":::{figure-md} sthelens\n",
+    "<img src=\"../../img/uavsar/sthelens.jpeg\" alt=\"uavsar scene\" width=\"800px\">\n",
+    "\n",
+    "Uavsar polarimetry imagery of Mt. St Helens. Source: Jones et al. 2008\n",
+    ":::\n",
+    "\n",
+    "*Developers: \\\n",
+    "Jack Tarricone, University of Nevada, Reno \\\n",
+    "Zach Keskinen, Boise State University*\n",
+    "\n",
+    "*Other contributors: \\\n",
+    "Ross Palomaki, Montana State University\\\n",
+    "Naheem Adebisi, Boise State University*"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## What is UAVSAR?\n",
+    "\n",
+    "[UAVSAR](https://uavsar.jpl.nasa.gov/education/what-is-uavsar.html) is a low frequency plane-based synthetic aperature radar. UAVSAR stands for \"Uninhabited Aerial Vehicle Synthetic Aperature Radar\". It captures imagery using a L-band radar. This low frequency means it can penetrate into and through clouds, vegetation, and snow.\n",
+    "\n",
+    "| frequency (cm) | resolution (rng x azi m) | Swath Width (km) | Polarizations | Launch date |\n",
+    "| - | - | - | - | - |\n",
+    "| L-band 23| 1.8 x 5.5 | 16 | VV, VH, HV, HH | 2007 |\n",
+    "\n",
+    "### NASA SnowEx 2020 and 2021 UAVSAR Campaings\n",
+    "\n",
+    "During the winter of 2020 and 2021, NASA conducted an L-band InSAR timeseries across the Western US with the goal of tracking changes in SWE. Field teams in 13 different locations in 2020, and in 6 locations in 2021, deployed on the date of the flight to perform calibration and validation observations.\n",
+    "\n",
+    ":::{figure-md} UAVSAR-map\n",
+    "<img src=\"../../img/SnowEx_map.jpg\" alt=\"uavsar map\" width=\"800px\">\n",
+    "\n",
+    "Map of the UAVSAR flight locations for NASA SnowEx. Note that the Montana site (Central Agricultral Research Center) is not on this map. Source: Chris Hiemstra\n",
+    ":::\n",
+    "\n",
+    "---\n",
+    "\n",
+    "The site locations from the above map along with the [Uavsar defined campaign name](https://api.daac.asf.alaska.edu/services/utils/mission_list) and currently processed pairs of InSAR images for each site. Note that the image pair count may contain multiple versions of the same image and may increase as more pairs of images are processed by JPL. Also note that the Lowman campaign name is the wrong state when searching.\n",
+    "\n",
+    "| Site Location | Campaign Name | Image Pairs |\n",
+    "| - | - | - |\n",
+    "| Grand Mesa | Grand Mesa, CO | 13 |\n",
+    "| Boise River Basin | Lowman, CO | 17 |\n",
+    "| Frazier Experimental Forest | Fraser, CO | 16 |\n",
+    "| Senator Beck Basin | Ironton, CO | 9 |\n",
+    "| East River | Peeler Peak, CO | 4 |\n",
+    "| Cameron Pass | Rocky Mountains NP, CO | 15 |\n",
+    "| Reynold Creek | Silver City, ID | 1 |\n",
+    "| Central Agricultral Research Center | Utica, MT | 2 |\n",
+    "| Little Cottonwoody Canyon | Salt Lake City, UT | 21 |\n",
+    "| Jemez River | Los Alamos, NM | 3 |\n",
+    "| American River Basin | Eldorado National Forest, CA | 4 |\n",
+    "| Sagehen Creek | Donner Memorial State Park, CA | 4 |\n",
+    "| Lakes Basin | Sierra National Forest, CA | 3 |"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Why would I use UAVSAR?\n",
+    "\n",
+    "UAVSAR works with low frequency radar waves. This means it is unaffected by clouds, maintains coherence, a measure of radar image quality, over long periods, and a time series was captured over 13 sites as part of the winter of 2019-2020 and 2020-2021. Additionally the uavsar is awesome."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Accessing Uavsar Images\n",
+    "\n",
+    "Uavsar imagery can be downloaded from both the [JPL](https://uavsar.jpl.nasa.gov/cgi-bin/data.pl) and [Alaska Satellite Facility](https://search.asf.alaska.edu/#/?dataset=UAVSAR). However both provide the imagery in a binary format that is not readily usable or readable by GIS software or python libraries. \n",
+    "\n",
+    "## Data Download and Conversion with ```uavsar_pytools```\n",
+    "```uavsar_pytools``` ([github](https://github.com/SnowEx/uavsar_pytools))is a Python package developed out of work started at SnowEx Hackweek 2021. It nativiely downloads, formats, and converts this data in analysis ready rasters projected in WSG-84 Lat/Lon (maybe more information here). The data traditionally comes in a binary format, which is not injestible by traditional geospatial analysis software (Python, R, QGIS, ArcGIS). It can download and convert either individual images - `UavsarScene` or entire collections of images - `UavsarCollection`.\n",
+    "\n",
+    "### Netrc Authorization\n",
+    "\n",
+    "In order to download uavsar images you will need a [netrc file](https://www.gnu.org/software/inetutils/manual/html_node/The-_002enetrc-file.html) that contains your earthdata username and password. If you need to register for a NASA earthdata account use this [link](https://urs.earthdata.nasa.gov/). A netrc file is a hidden file, it won't appear in the your file explorer, that is in your home directory and that programs can access to get the appropriate usernames and passwords. While you won't need to use this for this demonstration uavsar_pytools has a tool to create this netrc file on a local computer. You only need to create this file once and then it should be permanently stored on your computer."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# ## Creating .netrc file with Earthdata login information\n",
+    "# from uavsar_pytools.uavsar_tools import create_netrc\n",
+    "\n",
+    "# # This will prompt you for your username and password and save this\n",
+    "# # information into a .netrc file in your home directory. You only need to run\n",
+    "# # this command once per computer. Then it will be saved.\n",
+    "# create_netrc()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Downloading and converting a single Uavsar interferogram scene\n",
+    "\n",
+    "You can find urls for Uavsar images at the [ASF vertex website](https://search.asf.alaska.edu/#/?dataset=UAVSAR). Make sure to change the platform to Uavsar and you may also want to filter to  ground projected interferograms.\n",
+    "\n",
+    ":::{figure-md} vertexexample\n",
+    "<img src=\"../../img/uavsar/vertex_example.png\" alt=\"vertex example\" width=\"800px\">\n",
+    "\n",
+    "Example of getting the uavsar URL from vertex.\n",
+    ":::\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "try:\n",
+    "    from uavsar_pytools import UavsarScene\n",
+    "except ModuleNotFoundError:\n",
+    "    print('Install uavsar_pytools with `pip install uavsar_pytools`')\n",
+    "\n",
+    "## This is the directory you want to download and convert the images in.\n",
+    "work_dir = '/tmp/uavsar_data'\n",
+    "\n",
+    "## This is a url you want to download. Can be obtained from vertex\n",
+    "url = 'https://datapool.asf.alaska.edu/INTERFEROMETRY_GRD/UA/\\\n",
+    "lowman_23205_21009-004_21012-000_0007d_s01_L090_01_int_grd.zip'\n",
+    "\n",
+    "## clean = True will delete the binary and zip files leaving only the tiffs\n",
+    "scene = UavsarScene(url = url, work_dir=work_dir, clean= True)\n",
+    "\n",
+    "## After running url_to_tiffs() you will download the zip file, unzip the binary \n",
+    "## files, and convert them to geotiffs in the directory with the scene name in\n",
+    "## the work directory. It also generate a .csv pandas dictionary of metadata.\n",
+    "# scene.url_to_tiffs()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Downloading and converting a full Uavsar collection\n",
+    "\n",
+    "If you want to download and convert an entire Uavsar collection for a larger analysis you can use `UavsarCollection`. The collection names for the SnowEx campaign are listed in the table in the introduction. The `UavsarCollection` only downloads interferometric image pairs, but will soon be able to select between InSAR pairs and PolSAR images."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from uavsar_pytools import UavsarCollection\n",
+    "## Collection name, the SnowEx Collection names are listed above. These are case \n",
+    "## and space sensitive.\n",
+    "collection_name = 'Grand Mesa, CO'\n",
+    "\n",
+    "## Directory to save collection into. This will be filled with directory with \n",
+    "## scene names and tiffs inside of them.\n",
+    "out_dir = '/tmp/collection_ex/'\n",
+    "\n",
+    "## This is optional, but you will generally want to at least limit the date\n",
+    "## range between 2019 and today.\n",
+    "date_range = ('2019-11-01', 'today')\n",
+    "\n",
+    "# Keywords: to download incidence angles with each image use `inc = True`\n",
+    "# For only certain pols use `pols = ['VV','HV']`\n",
+    "collection = UavsarCollection(collection = collection_name, work_dir = out_dir, dates = date_range)\n",
+    "\n",
+    "## You can use this to check how many image pairs have at least one image in\n",
+    "## the date range.\n",
+    "collection.find_urls()\n",
+    "\n",
+    "## When you are ready to download all the images run:\n",
+    "# collection.collection_to_tiffs()\n",
+    "## This will take a long time and a lot of space, ~1-5 gB and 10 minutes per \n",
+    "## image pair depending on which scene, so run it if you have the space and time."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3.10.5 ('hackweek')",
+   "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"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "485426853efb45fbcac7604c62a774e4eca2d162588db5a3cdf8fcb52b528869"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}