Merge pull request #3 from ahuang11/refactor_notebooks

Refactor notebooks and add NASA GIBS explorer

Author: ahuang11

_toc.yml

@@ -6,3 +6,6 @@ parts:
       - file: notebooks/introduction.ipynb
       - file: notebooks/web_map_services.ipynb
       - file: notebooks/web_feature_services.ipynb
+  - caption: Example Workflows
+    chapters:
+      - file: notebooks/nasa_earthdata_gibs_explorer.ipynb

environment.yml

@@ -14,4 +14,5 @@ dependencies:
       - geoviews
       - panel
       - geopandas
-      - hvplot
+      - hvplot
+      - owslib

notebooks/images/gibs.png

@@ -0,0 +1,355 @@
+{
+ "cells": [
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "<img src=\"images/gibs.png\" alt=\"NASA GIBS Logo\"></img>\n",
+    "\n",
+    "Image from [NASA Global Imagery Browse Services (GIBS) GitHub](https://github.com/nasa-gibs)"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# NASA Earthdata GIBS Explorer\n",
+    "\n",
+    "Global Imagery Browse Services (GIBS) provides quick access to over 1,000 satellite imagery products, covering every part of the world. Most imagery is updated daily—available within a few hours after satellite observation, and some products span almost 30 years.\n",
+    "\n",
+    "Below demos how to use OWSLib, Geoviews, and Panel effectively to create our own GIBS explorer.\n",
+    "\n",
+    "## Prerequisites\n",
+    "\n",
+    "The following packages are good to know, but not required.\n",
+    "\n",
+    "| Concepts | Importance | Notes |\n",
+    "| --| --| --- |\n",
+    "| [Intro to GeoViews](https://geoviews.org/) | Helpful | Geographic visualizations |\n",
+    "| [Intro to Panel](https://panel.holoviz.org/) | Helpful | Dashboard creations |\n",
+    "| [Intro to OWSLib](https://owslib.readthedocs.io/en/latest/usage.html) | Helpful | WMS URLs |\n",
+    "\n",
+    "- **Time to learn**: 15 minutes\n",
+    "\n",
+    "---"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Imports\n",
+    "\n",
+    "Let’s first import a few packages.\n",
+    "\n",
+    "GeoViews is a Python library that facilitates the integration of WMS and other geospatial data sources with your own datasets. It provides a high-level interface for working with geographic data and simplifies the process of creating interactive visualizations.\n",
+    "\n",
+    "Pandas is a powerful Python library for data manipulation and analysis. It offers versatile data structures, such as Series and DataFrame, for working with structured data. However, here, we will only be using it to generate date time ranges.\n",
+    "\n",
+    "Panel is a Python library that offers a set of flexible and powerful tools for creating interactive dashboards and apps. It allows you to build custom user interfaces with interactive controls, widgets, and layout components, enabling rich interactivity for your visualizations and data analysis workflows.\n",
+    "\n",
+    "OWSLib is a Python library designed for client-side programming using the interface standards of the Open Geospatial Consortium (OGC) web services and their associated content models. Specifically, in this scenario, OWSLib will be utilized solely for the purpose of constructing URLs for WMS.\n",
+    "\n",
+    "The next line, `gv.extension(\"bokeh\")`, enables the Bokeh (interactive) plotting backend for GeoViews. GeoViews supports multiple plotting backends, such as Bokeh and Matplotlib, which allow you to choose the one that best suits your needs.\n",
+    "\n",
+    "Finally, `pn.extension()` initializes the panel library and sets up the necessary environment for creating interactive panels and dashboards. You may specify configurations like `sizing_mode=\"stretch_width\"` within `pn.extension()`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import panel as pn\n",
+    "import pandas as pd\n",
+    "import geoviews as gv\n",
+    "from owslib.wms import WebMapService\n",
+    "\n",
+    "gv.extension(\"bokeh\")\n",
+    "pn.extension(sizing_mode=\"stretch_width\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Accessing GIBS\n",
+    "\n",
+    "Accessing NASA's GIBS (Global Imagery Browse Services) is well-documented, and you can find the documentation [here](https://nasa-gibs.github.io/gibs-api-docs/access-basics/).\n",
+    "\n",
+    "To access GIBS through the WMS (Web Map Service) endpoints, you can follow these steps:\n",
+    "\n",
+    "1. Find the WMS service endpoints by referring to the [service endpoints section](https://nasa-gibs.github.io/gibs-api-docs/access-basics/#service-endpoints_1) of the documentation. Look for the row that corresponds to the EPSG:3857 projection, as GeoViews currently supports that projection for tile services.\n",
+    "\n",
+    "2. Once you have identified the WMS service endpoint, copy one of the versions' [GetCapabilities URLs](https://gibs.earthdata.nasa.gov/wms/epsg3857/best/wms.cgi?SERVICE=WMS&REQUEST=GetCapabilities&VERSION=1.3.0). This URL provides information about the available layers and operations supported by the WMS service.\n",
+    "\n",
+    "3. Pass the GetCapabilities URL to the `WebMapService` class, which is a part of the `OWSLib` library. This class allows you to interact with the WMS service and retrieve the desired data.\n",
+    "\n",
+    "By following these steps, you will be able to access and work with the NASA GIBS data using the WMS service endpoints."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "base_resource_url = \"https://gibs.earthdata.nasa.gov/wms/epsg3857/best/wms.cgi?SERVICE=WMS&REQUEST=GetCapabilities&VERSION=1.3.0\"\n",
+    "\n",
+    "wms = WebMapService(base_resource_url)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If we examine the contents, we can see that there are over a 1,000 layers (products) available!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "wms_contents = pd.Series(wms.contents)\n",
+    "print(len(wms_contents))\n",
+    "wms_contents.index"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "With a myriad of captivating options within your reach, why not embark on a journey of exploration and create your own interactive explorer?\n",
+    "\n",
+    "Now, you might be wondering, since there already exists an online explorer called [WorldView](https://worldview.earthdata.nasa.gov/), why bother reinventing the wheel? Well, here's the catch: by building your own explorer, you have the freedom to incorporate your own datasets into the mix!\n",
+    "\n",
+    "Not only does this provide a unique opportunity to personalize your exploration experience, but it's also a fantastic way to explore all the exciting options available while showcasing the incredible power of Python packages working in harmony!"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "No such comm: 90be3a54996442ad9c86f9abc1f60f70\n"
+     ]
+    }
+   ],
+   "source": [
+    "BASE_URL = \"https://gibs.earthdata.nasa.gov/wms/epsg3857/best/wms.cgi?SERVICE=WMS\"\n",
+    "XMIN = -20037507.539400\n",
+    "YMIN = 1638517.444800\n",
+    "XMAX = 20037260.918700\n",
+    "YMAX = 7714669.39460\n",
+    "\n",
+    "\n",
+    "class NasaEarthDataWmsExplorer:\n",
+    "    def __init__(self):\n",
+    "        self.wms = WebMapService(BASE_URL)\n",
+    "        layers = list(self.wms.contents)\n",
+    "\n",
+    "        # create widgets\n",
+    "        self.layer_input = pn.widgets.Select(\n",
+    "            name=\"Layer\",\n",
+    "            options=layers,\n",
+    "        )\n",
+    "        self.time_slider = pn.widgets.DiscreteSlider(name=\"Time\", margin=(5, 16))\n",
+    "        self.coastline_feature = gv.feature.coastline().opts(\n",
+    "            global_extent=True, responsive=True\n",
+    "        )\n",
+    "        self.static_text = pn.widgets.StaticText()\n",
+    "        self.image_pane = pn.pane.Image()\n",
+    "        self.holoviews_pane = pn.pane.HoloViews(\n",
+    "            object=self.coastline_feature, min_height=500, sizing_mode=\"stretch_both\"\n",
+    "        )\n",
+    "\n",
+    "        # add interactivity\n",
+    "        self.layer_input.param.watch(self.update_time, \"value\")\n",
+    "        self.time_slider.param.watch(self.update_web_map, \"value_throttled\")\n",
+    "\n",
+    "    def update_time(self, event):\n",
+    "        layer = event.new\n",
+    "        time_positions = self.wms.contents[layer].timepositions\n",
+    "        if not time_positions:\n",
+    "            # use N/A instead of None to circumvent Panel from crashing\n",
+    "            # when going from time-dependent layer to time-independent layer\n",
+    "            options = [\"N/A\"]\n",
+    "            value = \"N/A\"\n",
+    "        else:\n",
+    "            ini, end, step = time_positions[0].split(\"/\")\n",
+    "            options = (\n",
+    "                pd.date_range(ini, end, freq=pd.Timedelta(step))\n",
+    "                .strftime(\"%Y-%m-%dT%H:%M:%SZ\")\n",
+    "                .tolist()\n",
+    "            )\n",
+    "            value = options[0]\n",
+    "        self.time_slider.param.set_param(options=options, value=value)\n",
+    "        self.update_web_map()\n",
+    "\n",
+    "    def update_web_map(self, event=None):\n",
+    "        try:\n",
+    "            self.holoviews_pane.loading = True\n",
+    "            layer = self.layer_input.value\n",
+    "            time = self.time_slider.value\n",
+    "            if time == \"N/A\":\n",
+    "                time = None\n",
+    "\n",
+    "            url = wms.getmap(\n",
+    "                layers=[layer],\n",
+    "                srs=\"EPSG:3857\",\n",
+    "                bbox=(XMIN, YMIN, XMAX, YMAX),\n",
+    "                size=(256, 256),\n",
+    "                format=\"image/png\",\n",
+    "                transparent=True,\n",
+    "                time=time,\n",
+    "            ).geturl()\n",
+    "            url_template = (\n",
+    "                url.replace(str(XMIN), \"{XMIN}\")\n",
+    "                .replace(str(YMIN), \"{YMIN}\")\n",
+    "                .replace(str(XMAX), \"{XMAX}\")\n",
+    "                .replace(str(YMAX), \"{YMAX}\")\n",
+    "            )\n",
+    "\n",
+    "            layer_meta = self.wms[layer]\n",
+    "            self.image_pane.object = layer_meta.styles.get(\"default\", {}).get(\"legend\")\n",
+    "            self.static_text.value = layer_meta.abstract\n",
+    "            layer_imagery = gv.WMTS(url_template).opts(title=layer_meta.title)\n",
+    "\n",
+    "            self.holoviews_pane.object = self.coastline_feature * layer_imagery\n",
+    "        finally:\n",
+    "            self.holoviews_pane.loading = False\n",
+    "\n",
+    "    def view(self):\n",
+    "        widget_box = pn.WidgetBox(\n",
+    "            self.layer_input,\n",
+    "            self.time_slider,\n",
+    "            self.image_pane,\n",
+    "            self.static_text,\n",
+    "            pn.Spacer(sizing_mode=\"stretch_height\"),\n",
+    "            sizing_mode=\"stretch_both\",\n",
+    "        )\n",
+    "        return pn.Row(\n",
+    "            widget_box,\n",
+    "            self.holoviews_pane,\n",
+    "        )\n",
+    "\n",
+    "\n",
+    "nasa_earth_data_wms_explorer = NasaEarthDataWmsExplorer()\n",
+    "nasa_earth_data_wms_explorer.view()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The provided code allows users to interactively explore various layers of NASA Earth Data imagery.\n",
+    "\n",
+    "The `NasaEarthDataWmsExplorer` uses `WebMapService` from `OWSLib` ibrary to connect to the NASA Earth Data WMS service. The available layers are retrieved and displayed in a select widget.\n",
+    "\n",
+    "The explorer provides interactivity through `panel` widgets such as the layer selection dropdown and the time slider.\n",
+    "\n",
+    "Selecting a layer updates the available time positions for that layer, while changing the time position updates the displayed imagery accordingly. Metadata from the layer is also extracted and displayed below the widgets.\n",
+    "\n",
+    "The imagery is displayed using the GeoViews library, combined with a coastline feature.\n"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Summary\n",
+    "\n",
+    "While the standalone nature of this custom-built explorer may not rival the capabilities of the existing WorldView explorer, its true potential lies in the ability to incorporate your own data. By integrating your unique datasets into this explorer, you can unlock a world of fascinating possibilities and create a truly captivating exploration experience.\n",
+    "\n",
+    "It is this integration of personal data that sets this explorer apart and makes it incredibly compelling and engaging!"
+   ]
+  }
+ ],
+ "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.4"
+  },
+  "nbdime-conflicts": {
+   "local_diff": [
+    {
+     "diff": [
+      {
+       "diff": [
+        {
+         "key": 0,
+         "op": "addrange",
+         "valuelist": [
+          "Python 3"
+         ]
+        },
+        {
+         "key": 0,
+         "length": 1,
+         "op": "removerange"
+        }
+       ],
+       "key": "display_name",
+       "op": "patch"
+      }
+     ],
+     "key": "kernelspec",
+     "op": "patch"
+    }
+   ],
+   "remote_diff": [
+    {
+     "diff": [
+      {
+       "diff": [
+        {
+         "key": 0,
+         "op": "addrange",
+         "valuelist": [
+          "Python3"
+         ]
+        },
+        {
+         "key": 0,
+         "length": 1,
+         "op": "removerange"
+        }
+       ],
+       "key": "display_name",
+       "op": "patch"
+      }
+     ],
+     "key": "kernelspec",
+     "op": "patch"
+    }
+   ]
+  },
+  "toc-autonumbering": false
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}