Merge pull request #18 from HydroSAR/fix-notebooks

HyP3 and HydroSAR notebook updates

CHANGELOG.md

@@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [PEP 440](https://www.python.org/dev/peps/pep-0440/)
 and uses [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.1.0]
+
+### Added
+- The [hydrosar.ipynb](notebooks/hydrosar.ipynb) provides a walkthrough of generating HYDRO30 products from RTC30 products locally using the `hydrosar` package 
+- The [hydrosar-on-demand.ipynb](notebooks/hydrosar-on-demand.ipynb) provides a walkthrough of requesting the RTC30 and HYDRO30 products from the <https://hyp3-watermap.asf.alaska.edu/> deployment
+- [OSL_README.md](docs/OSL_README.md) describing how to setup a development environment in ASF's OpenScienceLab.
+
+### Removed
+- The `water-extent-map.ipynb` and the `water-extent-map-on-demand.ipynb` notebooks carried over `asf_tools`.
+
 ## [1.0.1]
 
 ### Fixed

docs/OSL_README.md

@@ -0,0 +1,70 @@
+# Creating a `hydrosar` prototype environment in OpenScienceLab
+
+<https://opensciencelab.asf.alaska.edu/>
+
+## Initial (one-time) setup of an `hydrosar` development environment
+
+When you log into your server on OpenScienceLab (OSL), launch a terminal and run these commands to set up a development environment:
+
+```bash
+git clone https://github.com/HydroSAR/HydroSAR
+cd HydroSAR
+
+conda env create -f environment.yml
+conda activate hydrosar
+
+# install an editable/develop version of the `hydrosar` python package
+python -m pip install -e .
+
+# test `hydrosar` is installed:
+python -c 'import hydrosar; print(hydrosar.__version__)'
+```
+
+To run the on demand notebook and make this environment discoverable in OpenSienceLab, you'll need to also install some additional packages:
+```bash
+conda install --file docs/hydrosar-on-demand-requirements.txt
+```
+
+Refresh your browser and the new environment should be available!
+
+Now you can:
+* Create a new notebook using the `hydrosar` kernel
+
+  ![new_notebook_kernel](https://github.com/HydroSAR/HydroSAR/assets/7882693/b0395e7d-d056-4e20-bb5a-5154adfbe61c)
+
+* Change the kernel of an existing notebook to the `hydrosar` kernel
+
+  ![change_kernel](https://github.com/HydroSAR/HydroSAR/assets/7882693/e008a252-80a5-480e-b8af-9d057b79c138)
+
+
+### Keeping in sync with changes upstream
+
+*Note:* These instructions assume you're working from the head/root of the HydroSAR repository.
+
+In the future, as dependencies are added or removed, you can update the conda environment with
+```bash
+conda env update -f environment.yml
+```
+and you should *not* need to restart OpenSARlab for the environment updates to take effect.
+
+As `hydrosar` itself is developed, you may need to reinstall the editable version
+if the package structure has significantly changed, or entrypoints have been added/removed.
+```bash
+python -m pip install -e .
+```
+
+In general, any time you pull changes it's a good idea to run both of the above commands.
+
+## Run the example `water-extent-map.ipynb`
+
+Once you've completed the above one-time setup, you can run through the example notebook,
+which will be located in the `notebooks/` directory:
+* `water-extent-map.ipynb` -- Run the water map code directly. This allows you to
+  edit the code and see the changes reflected.
+* `water-extent-map-on-demand.ipynb` -- Request water map products from the custom HyP3-watermap deployment
+   using either ASF Search Vertex or the `asf_search` Python package, and the HyP3 SDK.
+
+  ![prototype notebooks](https://github.com/HydroSAR/HydroSAR/assets/7882693/58ffb315-59b2-4dbf-b100-457b78a0a36e)
+
+
+*Note: Make sure you change the notebook kernel for each of these notebooks to the `hydrosar` kernel!*

docs/hydrosar-on-demand-requirements.txt

@@ -0,0 +1,3 @@
+jupyter
+hyp3_sdk
+asf_search

environment.yml

@@ -17,7 +17,7 @@ dependencies:
   - pytest-console-scripts
   - pytest-cov
   # For running
-  - asf_tools
+  - asf_tools>=0.6
   - astropy
   - boto3
   - fiona

notebooks/water-extent-map.ipynb → notebooks/hydrosar.ipynb

@@ -4,11 +4,11 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# HyP3 prototype water extent map product\n",
+    "# HYDRO30 Surface water extent map product\n",
     "\n",
-    "This notebook mimics the workflow a HyP3 Water Map plugin will follow to create an On Demand surface water extent map. It is intended demonstrate *how* HyP3 goes from an On Demand request to a product as well as provide a platform for testing/tuning/refinement ot the water extent map product.\n",
+    "This notebook mimics the workflow the HyP3 HydroSAR plugin will follow to create an On Demand surface water extent map product. It is intended demonstrate *how* HyP3 goes from an On Demand request to a product, as well as provide a platform for testing/tuning/refinement ot the water extent map product.\n",
     "\n",
-    "Importantly, step 2 will become the plugin's primary interface, and the options provided to the `make_water_map` function are able to be exposed to users. Step 1 is a required data marshaling step that will be handled transparently inside the container.\n",
+    "Importantly, step 2 will become the plugin's primary interface, and the options provided to the `make_water_map` function can be exposed to users. Step 1 is a required data marshaling step that will be handled transparently inside the container.\n",
     "\n",
     "If you'd like an overview of the water extent mapping process, run the following cell to get the `make_water_map` documentation, otherwise, skip to step 1."
    ]
@@ -19,7 +19,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from asf_tools.water_map import make_water_map\n",
+    "from hydrosar.water_map import make_water_map\n",
     "\n",
     "make_water_map?"
    ]
@@ -32,7 +32,7 @@
     "\n",
     "Water extent mapping requires Radiometrically Terrain Corrected (RTC) Sentinel-1 scenes in order to accurately connect backscatter features to the input HAND data. The next few cells will use HyP3's Python SDK to request an RTC product from HyP3 for the Sentinel-1 granule (scene):\n",
     "\n",
-    "[S1A_IW_GRDH_1SDV_20210413T235641_20210413T235706_037439_0469D0_3F2B](https://search.asf.alaska.edu/#/?zoom=6.964&center=-90.509,40.296&resultsLoaded=true&granule=S1A_IW_GRDH_1SDV_20210413T235641_20210413T235706_037439_0469D0_3F2B-METADATA_GRD_HD&searchType=List%20Search&searchList=S1A_IW_GRDH_1SDV_20210413T235641_20210413T235706_037439_0469D0_3F2B)\n",
+    "[S1A_IW_GRDH_1SDV_20210413T235641_20210413T235706_037439_0469D0_3F2B](https://search.asf.alaska.edu/#/?zoom=6.964&center=-90.385,37.312&resultsLoaded=true&granule=S1A_IW_GRDH_1SDV_20210413T235641_20210413T235706_037439_0469D0_3F2B-METADATA_GRD_HD&searchType=List%20Search&searchList=S1A_IW_GRDH_1SDV_20210413T235641_20210413T235706_037439_0469D0_3F2B)\n",
     "\n",
     "### 1.1 Connect to HyP3"
    ]
@@ -43,12 +43,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import logging\n",
-    "import shutil\n",
     "import hyp3_sdk as sdk\n",
     "\n",
-    "logging.basicConfig(level=logging.INFO)\n",
-    "\n",
     "hyp3 = sdk.HyP3(prompt=True)"
    ]
   },
@@ -123,6 +119,8 @@
    },
    "outputs": [],
    "source": [
+    "import shutil\n",
+    "\n",
     "product_zip = job.download_files()[0]\n",
     "shutil.unpack_archive(product_zip)\n",
     "vv_raster = product_zip.parent / product_zip.stem / f'{product_zip.stem}_VV.tif'\n",
@@ -148,7 +146,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from asf_tools.water_map import make_water_map\n",
+    "from hydrosar.water_map import make_water_map\n",
     "\n",
     "water_extent_raster = 'water_extent.tif'\n",
     "make_water_map(water_extent_raster, vv_raster, vh_raster, tile_shape=(100, 100),\n",
@@ -159,12 +157,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "`make_water_map` in [water_map.py](../asf_tools/water_map.py) is the primary \"science\" interface for generating the water maps. It *should* include all the necessary options for tuning the product -- if it doesn't, and you'd like other things exposed, either:\n",
-    "* Ask us to expose it by:\n",
-    "  * [Chatting with us in Gitter](https://gitter.im/ASFHyP3/community)\n",
-    "  * [Opening an issue](https://github.com/ASFHyP3/asf-tools/issues/new/choose)\n",
-    "\n",
-    "* [Fork](https://github.com/ASFHyP3/hyp3-sdk/fork) and propose changes in a Pull Request. See our [contributing guidelines](https://hyp3-docs.asf.alaska.edu/contributing/).\n",
+    "`make_water_map` in [water_map.py](../src/hydrosar/water_map.py) is the primary \"science\" interface for generating the water maps. It *should* include all the necessary options for tuning the product -- if it doesn't, and you'd like other things exposed, either:\n",
+    "* Ask us to expose it by [Opening an issue](https://github.com/HydroSAR/HydroSAR/issues/new/choose)\n",
+    "* [Fork](https://github.com/HydroSAR/HydroSAR/fork) and propose changes in a Pull Request.\n",
     "\n",
     "For more info on the `make_water_map` function, run the cell below."
    ]
@@ -175,16 +170,16 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "from asf_tools.water_map import make_water_map\n",
+    "from hydrosar.water_map import make_water_map\n",
     "make_water_map?"
    ]
   }
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "asf-tools",
+   "name": "python3",
    "language": "python",
-   "name": "conda-env-.local-asf-tools-py"
+   "display_name": "Python 3 (ipykernel)"
   },
   "language_info": {
    "codemirror_mode": {