Add support for accessing and visualizing ECOSTRESS data (#37)

* Add support for searching and downloading ECOSTRESS data * Add ECOSTRESS notebook
opengeos · Jun 1, 2024 · 0f59737 · 0f59737
1 parent 0936aec
commit 0f59737
Show file tree

Hide file tree

Showing 6 changed files with 348 additions and 2 deletions.
diff --git a/.gitignore b/.gitignore
@@ -27,6 +27,9 @@ wheels/
 *.egg-info/
 .installed.cfg
 *.egg
+*.tif
+*.nc
+*.aux.xml
 
 # PyInstaller
 #  Usually these files are written by a python script from a template

diff --git a/docs/examples/ecostress.ipynb b/docs/examples/ecostress.ipynb
@@ -0,0 +1,204 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "[![image](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/opengeos/HyperCoast/blob/main/docs/examples/ecostress.ipynb)\n",
+    "\n",
+    "# Search and download NASA ECOSTRESS data with HyperCoast\n",
+    "\n",
+    "This notebook demonstrates how to search and visualize NASA [ECOSTRESS](https://ecostress.jpl.nasa.gov/) temperature data with HyperCoast."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hypercoast"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hypercoast.nasa_earth_login()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Search for ECOSTRESS data programmatically"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results, gdf = hypercoast.search_ecostress(\n",
+    "    bbox=(-120.522, 34.4266, -120.2665, 34.5653),\n",
+    "    temporal=(\"2023-04-01\", \"2023-04-02\"),\n",
+    "    count=-1,  # use -1 to return all datasets\n",
+    "    return_gdf=True,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf.explore()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![](https://i.imgur.com/wEGSm5r.png)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download ECOSTRESS data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hypercoast.download_ecostress(results[:5], out_dir=\"data\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Search for ECOSTRESS data interactively"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m = hypercoast.Map(center=[34.5014, -120.4032], zoom=11)\n",
+    "m.search_ecostress()\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![](https://i.imgur.com/JhAEyDC.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# m._NASA_DATA_GDF.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# hypercoast.download_ecostress(m._NASA_DATA_RESULTS[:2], out_dir=\"data\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Visualize ECOSTRESS data\n",
+    "\n",
+    "Download a sample ECOSTRESS data file and visualize it with HyperCoast."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "url = \"https://github.com/opengeos/datasets/releases/download/raster/ECOv002_L2T_LSTE_26860_001_10SGD_20230401T203733_0710_01_LST.tif\""
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "filepath = \"data/ECOv002_L2T_LSTE_26860_001_10SGD_20230401T203733_0710_01_LST.tif\"\n",
+    "hypercoast.download_file(url, filepath)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Viusalize the data with HyperCoast."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m = hypercoast.Map()\n",
+    "m.add_basemap(\"HYBRID\")\n",
+    "m.add_raster(filepath, colormap=\"jet\", layer_name=\"LST\")\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![](https://i.imgur.com/SnKXnaw.png)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "hyper",
+   "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.10.14"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}
diff --git a/docs/examples/search_data.ipynb b/docs/examples/search_data.ipynb
@@ -8,7 +8,7 @@
     "\n",
     "# Search and download NASA hyperspectral data with HyperCoast\n",
     "\n",
-    "This notebook demonstrates how to search and download NASA hyperspectral data (e.g., EMIT, [](https://pace.gsfc.nasa.gov) with HyperCoast."
+    "This notebook demonstrates how to search and download NASA hyperspectral data (e.g., [EMIT](https://earth.jpl.nasa.gov/emit), [PACE](https://pace.gsfc.nasa.gov)) and [ECOSTRESS](https://ecostress.jpl.nasa.gov/) temperature data with HyperCoast."
    ]
   },
   {
@@ -155,6 +155,45 @@
     "hypercoast.download_emit(results[:2], out_dir=\"data\")"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Download ECOSTRESS data"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "results, gdf = hypercoast.search_ecostress(\n",
+    "    bbox=(-120.522, 34.4266, -120.2665, 34.5653),\n",
+    "    temporal=(\"2023-04-01\", \"2023-04-02\"),\n",
+    "    count=-1,  # use -1 to return all datasets\n",
+    "    return_gdf=True,\n",
+    ")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "gdf.explore()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "hypercoast.download_ecostress(results[:5], out_dir=\"data\")"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},
@@ -228,6 +267,42 @@
    "source": [
     "# hypercoast.download_emit(m._NASA_DATA_RESULTS[:2], out_dir=\"data\")"
    ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    " Search for ECOSTRESS data interactively."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "m = hypercoast.Map(center=[34.5014, -120.4032], zoom=11)\n",
+    "m.search_ecostress()\n",
+    "m"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# m._NASA_DATA_GDF.head()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# hypercoast.download_ecostress(m._NASA_DATA_RESULTS[:2], out_dir=\"data\")"
+   ]
   }
  ],
  "metadata": {

diff --git a/hypercoast/common.py b/hypercoast/common.py
@@ -287,6 +287,44 @@ def search_emit(
     )
 
 
+def search_ecostress(
+    bbox: Optional[List[float]] = None,
+    temporal: Optional[str] = None,
+    count: int = -1,
+    short_name: Optional[str] = "ECO_L2T_LSTE",
+    output: Optional[str] = None,
+    crs: str = "EPSG:4326",
+    return_gdf: bool = False,
+    **kwargs,
+) -> Union[List[dict], tuple]:
+    """Searches for NASA ECOSTRESS granules.
+
+    Args:
+        bbox (List[float], optional): The bounding box coordinates [xmin, ymin, xmax, ymax].
+        temporal (str, optional): The temporal extent of the data.
+        count (int, optional): The number of granules to retrieve. Defaults to -1 (retrieve all).
+        short_name (str, optional): The short name of the dataset. Defaults to "ECO_L2T_LSTE".
+        output (str, optional): The output file path to save the GeoDataFrame as a file.
+        crs (str, optional): The coordinate reference system (CRS) of the GeoDataFrame. Defaults to "EPSG:4326".
+        return_gdf (bool, optional): Whether to return the GeoDataFrame in addition to the granules. Defaults to False.
+        **kwargs: Additional keyword arguments for the earthaccess.search_data() function.
+
+    Returns:
+        Union[List[dict], tuple]: The retrieved granules. If return_gdf is True, also returns the resulting GeoDataFrame.
+    """
+
+    return search_nasa_data(
+        count=count,
+        short_name=short_name,
+        bbox=bbox,
+        temporal=temporal,
+        output=output,
+        crs=crs,
+        return_gdf=return_gdf,
+        **kwargs,
+    )
+
+
 def download_pace(
     granules: List[dict],
     out_dir: Optional[str] = None,
@@ -319,6 +357,22 @@ def download_emit(
     download_nasa_data(granules=granules, out_dir=out_dir, threads=threads)
 
 
+def download_ecostress(
+    granules: List[dict],
+    out_dir: Optional[str] = None,
+    threads: int = 8,
+) -> None:
+    """Downloads NASA ECOSTRESS granules.
+
+    Args:
+        granules (List[dict]): The granules to download.
+        out_dir (str, optional): The output directory where the granules will be downloaded. Defaults to None (current directory).
+        threads (int, optional): The number of threads to use for downloading. Defaults to 8.
+    """
+
+    download_nasa_data(granules=granules, out_dir=out_dir, threads=threads)
+
+
 def nasa_earth_login(strategy: str = "all", persist: bool = True, **kwargs) -> None:
     """Logs in to NASA Earthdata.
 

diff --git a/hypercoast/hypercoast.py b/hypercoast/hypercoast.py
@@ -66,6 +66,15 @@ def search_pace(self, default_dataset="PACE_OCI_L2_AOP_NRT"):
         """
         self.add("nasa_earth_data", default_dataset=default_dataset)
 
+    def search_ecostress(self, default_dataset="ECO_L2T_LSTE"):
+        """
+        Adds a NASA Earth Data search tool to the map with a default dataset for ECOSTRESS.
+
+        Args:
+            default_dataset (str, optional): The default dataset to search for. Defaults to "ECO_L2T_LSTE".
+        """
+        self.add("nasa_earth_data", default_dataset=default_dataset)
+
     def add_raster(
         self,
         source,