Pass-through search kwargs to earthaccess.search_data.

Author: trey-stafford

CHANGELOG.md

@@ -7,9 +7,11 @@
   Generate an Elevation Timeseries" notebook.
 - Filter for cloud-hosted data, avoiding duplicate granule results from
   `fetch.find_iceflow_data`
-- Make "bounding box" construct consistent with `icepyx` and `earthaccess`. This
-  simplifies the api, and means the user no longer needs to import `BoundingBox`
-  to query for data.
+- Pass through search kwargs to `earthaccess` without any type validation. This
+  allows earthaccess to do watever validation it needs to, and then it passes
+  those on to CMR. This provides much greater flexibility over data search and
+  makes the interface more consistent with `icepyx` and `earthaccess`.
+  https://github.com/nsidc/iceflow/issues/51.
 
 # v0.3.0
 

docs/getting-started.md

@@ -35,6 +35,27 @@ search_results = find_iceflow_data(
 )
 ```
 
+By default, all iceflow-supported datasets are searched. To search for a
+specific subset of iceflow-supported datasets, use the `datasets` kwarg:
+
+```
+from nsidc.iceflow import ILATM1BDataset
+
+
+search_results = find_iceflow_data(
+    datasets=[ILATM1BDataset(version="1")],
+    # Lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat
+    bounding_box=(-103.125559, -75.180563, -102.677327, -74.798063),
+    temporal=(dt.date(2009, 11, 1), dt.date(2009, 12, 31)),
+)
+```
+
+All other keyword arguments to this function (e.g,. `bounding_box`, `temporal`)
+map to [CMR](https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html)
+search parameters, and are passed un-modified to
+[earthaccess.search_data](https://earthaccess.readthedocs.io/en/latest/user-reference/api/api/#earthaccess.api.search_data)
+to perform the search.
+
 ### Downloading data
 
 Once search results have been found, download data with

docs/notebooks/iceflow-example.ipynb

@@ -43,7 +43,6 @@
     "import matplotlib.pyplot as plt\n",
     "\n",
     "from nsidc.iceflow import (\n",
-    "    DatasetSearchParameters,\n",
     "    ILATM1BDataset,\n",
     "    download_iceflow_results,\n",
     "    find_iceflow_data,\n",
@@ -121,11 +120,9 @@
    ],
    "source": [
     "search_results = find_iceflow_data(\n",
-    "    dataset_search_params=DatasetSearchParameters(\n",
-    "        datasets=[atm1b_v1_dataset],\n",
-    "        bounding_box=BBOX,\n",
-    "        temporal=date_range,\n",
-    "    ),\n",
+    "    datasets=[atm1b_v1_dataset],\n",
+    "    bounding_box=BBOX,\n",
+    "    temporal=date_range,\n",
     ")\n",
     "len(search_results)"
    ]

docs/notebooks/iceflow-with-icepyx.ipynb

@@ -763,7 +763,6 @@
     "import xarray as xr\n",
     "\n",
     "from nsidc.iceflow import (\n",
-    "    DatasetSearchParameters,\n",
     "    IceflowDataFrame,\n",
     "    download_iceflow_results,\n",
     "    find_iceflow_data,\n",
@@ -821,7 +820,7 @@
    "source": [
     "Next we will use the `find_iceflow_data` function from the `iceflow` API to find data matching our area of interest.\n",
     "\n",
-    "By default, `DatasetSearchParameters` will include all `iceflow` supported datasets, unless one or more are specified as a filter with the `datasets` kwarg. There may be warnings raised about there not being search results for specific datasets supported by `iceflow`."
+    "By default, `find_iceflow_data` will include all `iceflow` supported datasets, unless one or more are specified as a filter with the `datasets` kwarg. There may be warnings raised about there not being search results for specific datasets supported by `iceflow`."
    ]
   },
   {
@@ -850,10 +849,8 @@
    ],
    "source": [
     "search_results = find_iceflow_data(\n",
-    "    dataset_search_params=DatasetSearchParameters(\n",
-    "        bounding_box=BBOX,\n",
-    "        temporal=DATE_RANGE,\n",
-    "    ),\n",
+    "    bounding_box=BBOX,\n",
+    "    temporal=DATE_RANGE,\n",
     ")\n",
     "len(search_results)"
    ]

src/nsidc/iceflow/__init__.py

@@ -22,7 +22,6 @@
 from nsidc.iceflow.data.models import (
     ALL_DATASETS,
     BLATM1BDataset,
-    DatasetSearchParameters,
     GLAH06Dataset,
     IceflowDataFrame,
     ILATM1BDataset,
@@ -37,7 +36,6 @@
 __all__ = [
     "ALL_DATASETS",
     "BLATM1BDataset",
-    "DatasetSearchParameters",
     "GLAH06Dataset",
     "ILATM1BDataset",
     "ILVIS2Dataset",

src/nsidc/iceflow/data/fetch.py

@@ -1,32 +1,26 @@
 from __future__ import annotations
 
-import datetime as dt
 from pathlib import Path
 
 import earthaccess
 from loguru import logger
 
 from nsidc.iceflow.data.models import (
     ALL_DATASETS,
-    BoundingBoxLike,
     Dataset,
     IceflowSearchResult,
     IceflowSearchResults,
-    TemporalRange,
 )
 
 
 def _find_iceflow_data_for_dataset(
     *,
     dataset: Dataset,
-    bounding_box: BoundingBoxLike,
-    temporal: tuple[dt.datetime | dt.date, dt.datetime | dt.date],
+    **search_kwargs,
 ) -> IceflowSearchResult:
     earthaccess.login()
 
-    ctx_string = (
-        f"{dataset.short_name=} {dataset.version=} with {bounding_box=} {temporal=}"
-    )
+    ctx_string = f"{dataset.short_name=} {dataset.version=} with {search_kwargs=}"
 
     try:
         granules_list = earthaccess.search_data(
@@ -36,8 +30,7 @@ def _find_iceflow_data_for_dataset(
             # non-cloud, we may get duplicate granules as long as the ECS copy
             # remains.
             cloud_hosted=True,
-            bounding_box=bounding_box,
-            temporal=temporal,
+            **search_kwargs,
         )
     except IndexError:
         # There's no data matching the given parameters.
@@ -84,17 +77,20 @@ def _download_iceflow_search_result(
 
 def find_iceflow_data(
     *,
-    bounding_box: BoundingBoxLike,
-    temporal: TemporalRange,
     datasets: list[Dataset] = ALL_DATASETS,
+    **search_kwargs,
 ) -> IceflowSearchResults:
-    """Find iceflow-compatible data using spatial and temporal constraints."""
+    """Find iceflow-compatible data using search kwargs.
+
+    `search_kwargs` are passed to `earthaccess.search_data`, allowing for
+    CMR-supported filters (see
+    https://cmr.earthdata.nasa.gov/search/site/docs/search/api.html)
+    """
     iceflow_search_results = []
     for dataset in datasets:
         iceflow_search_result = _find_iceflow_data_for_dataset(
             dataset=dataset,
-            bounding_box=bounding_box,
-            temporal=temporal,
+            **search_kwargs,
         )
         iceflow_search_results.append(iceflow_search_result)
 

src/nsidc/iceflow/data/models.py

@@ -248,12 +248,6 @@ class GLAH06Dataset(Dataset):
 TemporalRange = tuple[dt.datetime | dt.date, dt.datetime | dt.date]
 
 
-class DatasetSearchParameters(pydantic.BaseModel):
-    datasets: list[Dataset] = ALL_DATASETS
-    bounding_box: BoundingBoxLike
-    temporal: TemporalRange
-
-
 class IceflowSearchResult(pydantic.BaseModel):
     dataset: Dataset
     granules: list[DataGranule]