docs/tutorials/hyp3_isce2_burst_merge.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "d20494ef",
   "metadata": {},
   "source": [
    "# Merge HyP3 ISCE2 burst InSAR products\n",
    "\n",
    "This notebook demonstrates how to use the `merge_tops_burst` workflow of the HyP3-ISCE2 plugin. This workflow merges multiple burst InSAR Products and takes a directory that includes multiple HyP3-ISCE2 Burst InSAR Products as its input. These input products can be created by the HyP3-ISCE2 on-demand service. To learn how to create HyP3 burst InSAR Products, check out our [hyp3_isce2_burst_stack_for_ts_analysis](https://github.com/ASFHyP3/hyp3-docs/blob/main/docs/tutorials/hyp3_isce2_burst_stack_for_ts_analysis.ipynb) notebook.\n",
    "\n",
    "\n",
    "**Note:** This notebook does assume you have some familiarity with InSAR processing with HyP3 already, and is a minimal example without much context or explanations. If you're new to InSAR and HyP3, we suggest checking out the following resources. Note that some of these resources may be specific to our InSAR GAMMA products, so you may need to adapt them for use with our ISCE2-based burst InSAR products.\n",
    "\n",
    "* Our [Burst Data Download Story Map](https://storymaps.arcgis.com/stories/88c8fe67933340779eddef212d76b8b8)\n",
    "\n",
    "* Our [product guide](https://hyp3-docs.asf.alaska.edu/guides/burst_insar_product_guide/) for burst InSAR products\n",
    "\n",
    "* Our [GitHub repository](https://github.com/asfhyp3/hyp3-isce2) containg the workflow used to create burst InSAR products\n",
    "\n",
    "* Our [InSAR on Demand Story Map](https://storymaps.arcgis.com/stories/68a8a3253900411185ae9eb6bb5283d3)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0a6e353",
   "metadata": {},
   "source": [
    "## 0. Initial Setup\n",
    "To run this notebook, you will need a local copy of the HyP3-ISCE2 GitHub repository and to set up a conda environment with the required dependencies. In your terminal, you can do this with the following commands:\n",
    "\n",
    "```shell\n",
    "git clone https://github.com/ASFHyP3/hyp3-isce2.git\n",
    "cd hyp3-isce2\n",
    "mamba env create -f environment.yml\n",
    "mamba activate hyp3-isce2\n",
    "python -m pip install -e .\n",
    "mamba install -c conda-forge pandas jupyter ipympl\n",
    "jupyter notebook hyp3_isce2_burst_merge.ipynb\n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7f093a40806f3ca5",
   "metadata": {},
   "source": [
    "This workflow requires an Earth Data Cloud login. If you haven't yet, you can make an [account for free](https://urs.earthdata.nasa.gov/users/new) and set up a `.netrc` file in your home directory with your personal username and password.\n",
    "\n",
    "```shell\n",
    "echo ‘machine urs.earthdata.nasa.gov login $USERNAME password $PASSWORD’ >> ~/.netrc \n",
    "```"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5cce7457-a179-448d-a139-1f9e4f72b2d3",
   "metadata": {},
   "source": [
    "## 1. Create burst InSAR prodcuts to merge\n",
    "\n",
    "Before using the [HyP3-ISCE2 merge burst workflow](https://hyp3-docs.asf.alaska.edu/guides/burst_insar_product_guide/#merge-sentinel-1-burst-insar-products), we must create burst InSAR products that are merge-compatible. This means that they must:\n",
    "- Have the same reference and secondary dates\n",
    "- Have the same polarization\n",
    "- Have the same multilooking\n",
    "- Be from the same relative orbit\n",
    "- Be contiguous\n",
    "\n",
    "In this section, we'll create two such burst InSAR products and download them to a local directory."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7aac2af4-b703-4d21-8c1f-acd6cccfcc4c",
   "metadata": {},
   "outputs": [],
   "source": [
    "from pathlib import Path\n",
    "\n",
    "\n",
    "reference_granule1 = 'S1_136231_IW2_20200604T022312_VV_7C85-BURST'\n",
    "secondary_granule1 = 'S1_136231_IW2_20200616T022313_VV_5D11-BURST'\n",
    "\n",
    "reference_granule2 = 'S1_136232_IW2_20200604T022315_VV_7C85-BURST'\n",
    "secondary_granule2 = 'S1_136232_IW2_20200616T022316_VV_5D11-BURST'\n",
    "\n",
    "project_name = 'merge_demo'\n",
    "current_dir = Path.cwd() # Make sure we preserve this in case we want to navigate back\n",
    "work_dir = Path.cwd() / project_name\n",
    "data_dir = work_dir / 'data'\n",
    "data_dir.mkdir(parents=True, exist_ok=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3f422b8c-3362-4bd2-a4e8-601797c1be15",
   "metadata": {},
   "outputs": [],
   "source": [
    "import hyp3_sdk as sdk\n",
    "\n",
    "hyp3 = sdk.HyP3(prompt=True)\n",
    "\n",
    "jobs = sdk.Batch()\n",
    "for reference, secondary in [(reference_granule1, secondary_granule1), (reference_granule2, secondary_granule2)]:\n",
    "    jobs += hyp3.submit_insar_isce_burst_job(\n",
    "        granule1 = reference,\n",
    "        granule2 = secondary, \n",
    "        apply_water_mask = False,\n",
    "        name = project_name,\n",
    "        looks = '20x4'\n",
    "    )"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a1ea4c9a-f4af-46cd-a236-da6d4d9bc79e",
   "metadata": {},
   "outputs": [],
   "source": [
    "jobs = hyp3.watch(jobs)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3bfae6e2-909d-4c02-8934-80f7dd62bb5f",
   "metadata": {},
   "outputs": [],
   "source": [
    "from datetime import datetime\n",
    "\n",
    "now = datetime.now()\n",
    "start_of_today = datetime(now.year, now.month, now.day)\n",
    "\n",
    "jobs = hyp3.find_jobs(name=project_name, start=start_of_today)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0ca16997-9159-490f-aa53-dda56dc7ec7e",
   "metadata": {},
   "outputs": [],
   "source": [
    "insar_products = jobs.download_files(data_dir)\n",
    "insar_products = [sdk.util.extract_zipped_product(ii) for ii in insar_products]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9e5c5b0b",
   "metadata": {},
   "source": [
    "## 2. Merge the products using hyp3-isce2 merge_tops_burst workflow\n",
    "\n",
    "Now we have all the data we need and can merge these two burst InSAR products! You would typically run the command below on the command line, but we'll run it through the Jupyter Notebook here."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ec6920e4-7aec-423e-9951-72c3235b62ce",
   "metadata": {},
   "outputs": [],
   "source": [
    "cd $work_dir"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e02a4de-d4b4-43f9-b861-98c9d6c64d53",
   "metadata": {},
   "outputs": [],
   "source": [
    "# Use this command to actually view the options for the merge_tops_burst workflow\n",
    "!python -m hyp3_isce2 ++process merge_tops_bursts --help"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e1dec3dd",
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "# Use this command to actually run the merge_tops_burst workflow\n",
    "!python -m hyp3_isce2 ++process merge_tops_bursts $data_dir"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9b717cb5-2895-4c1b-abfb-6e597e648d23",
   "metadata": {},
   "source": [
    "## 3. Display the merged product\n",
    "\n",
    "We've successfully run the command, now let's look at the results!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "80f7eedce43cd54c",
   "metadata": {
    "collapsed": false,
    "jupyter": {
     "outputs_hidden": false
    }
   },
   "outputs": [],
   "source": [
    "%matplotlib inline\n",
    "import numpy as np\n",
    "from osgeo import gdal\n",
    "import matplotlib\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "tifs = [f for f in work_dir.glob(\"*/*.tif\")]\n",
    "unw_file = [f for f in tifs if 'unw_phase' in f.name][0]\n",
    "wrapped_file = [f for f in tifs if 'wrapped_phase' in f.name][0]\n",
    "corr_file = [f for f in tifs if 'corr' in f.name][0]\n",
    "desired_tifs = [wrapped_file, unw_file, corr_file]\n",
    "\n",
    "f, axs = plt.subplots(len(desired_tifs), figsize=(6,10))\n",
    "for i, tif in enumerate(desired_tifs): \n",
    "    ds = gdal.Open(str(tif))\n",
    "    merged_bursts = np.ma.masked_equal(ds.GetRasterBand(1).ReadAsArray(), 0)\n",
    "    ds = None\n",
    "        \n",
    "    axs[i].imshow(merged_bursts)\n",
    "    axs[i].set_title(tif.name)\n",
    "\n",
    "    plt.setp(plt.gcf().get_axes(), xticks=[], yticks=[])\n",
    "    plt.tight_layout()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f8bc3bd2-f126-4546-8f80-c52ecab20a68",
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "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.11.6"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}