Merge pull request #71 from nsidc/51-bbox-consistent-icepyx-earthaccess

51 bbox consistent icepyx earthaccess

Author: trey-stafford

.github/workflows/ci.yml

@@ -22,7 +22,7 @@ jobs:
 
       - uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: Install package
         run: python -m pip install .[dev]

CHANGELOG.md

@@ -7,6 +7,11 @@
   Generate an Elevation Timeseries" notebook.
 - Filter for cloud-hosted data, avoiding duplicate granule results from
   `fetch.find_iceflow_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

@@ -25,21 +25,37 @@ To find `iceflow`-supported data for an area of interest and timeframe, use
 ```
 import datetime as dt
 
-from nsidc.iceflow import (
-    find_iceflow_data,
-    DatasetSearchParameters,
-    BoundingBox,
+from nsidc.iceflow import find_iceflow_data
+
+
+search_results = find_iceflow_data(
+    # 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)),
 )
+```
+
+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(
-    dataset_search_params=DatasetSearchParameters(
-        bounding_box=BoundingBox(lower_left_lon=-103.125559, lower_left_lat=-75.180563, upper_right_lon=-102.677327, upper_right_lat=-74.798063),
-        temporal=(dt.date(2009, 11, 1), dt.date(2009, 12, 31)),
-    ),
+    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,8 +43,6 @@
     "import matplotlib.pyplot as plt\n",
     "\n",
     "from nsidc.iceflow import (\n",
-    "    BoundingBox,\n",
-    "    DatasetSearchParameters,\n",
     "    ILATM1BDataset,\n",
     "    download_iceflow_results,\n",
     "    find_iceflow_data,\n",
@@ -84,11 +82,11 @@
     "# Define the dataset that we want to search for.\n",
     "atm1b_v1_dataset = ILATM1BDataset(version=\"1\")\n",
     "# Define a bounding box for our area of interest.\n",
-    "BBOX = BoundingBox(\n",
-    "    lower_left_lon=-103.125559,\n",
-    "    lower_left_lat=-75.180563,\n",
-    "    upper_right_lon=-102.677327,\n",
-    "    upper_right_lat=-74.798063,\n",
+    "BBOX = (\n",
+    "    -103.125559,\n",
+    "    -75.180563,\n",
+    "    -102.677327,\n",
+    "    -74.798063,\n",
     ")\n",
     "\n",
     "# We will define a short date range in 2009 to search for data.\n",
@@ -122,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,8 +763,6 @@
     "import xarray as xr\n",
     "\n",
     "from nsidc.iceflow import (\n",
-    "    BoundingBox,\n",
-    "    DatasetSearchParameters,\n",
     "    IceflowDataFrame,\n",
     "    download_iceflow_results,\n",
     "    find_iceflow_data,\n",
@@ -804,11 +802,11 @@
     "ICESAT2_ITRF = \"ITRF2014\"\n",
     "\n",
     "# This bounding box covers an area near Sermeq Kujalleq (Jakobshavn Isbrae)\n",
-    "BBOX = BoundingBox(\n",
-    "    lower_left_lon=-49.149,\n",
-    "    lower_left_lat=69.186,\n",
-    "    upper_right_lon=-48.949,\n",
-    "    upper_right_lat=69.238,\n",
+    "BBOX = (\n",
+    "    -49.149,\n",
+    "    69.186,\n",
+    "    -48.949,\n",
+    "    69.238,\n",
     ")\n",
     "\n",
     "# Range of dates we want to evaluate\n",
@@ -822,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`."
    ]
   },
   {
@@ -851,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)"
    ]

pyproject.toml

@@ -48,7 +48,7 @@ Changelog = "https://github.com/NSIDC/iceflow/releases"
 dev = [
   "bump-my-version",
   "invoke",
-  "mypy >=1.15.0",
+  "mypy >=1.16.0",
   "pandas-stubs >=2.2",
   "pre-commit",
   "pytest",

src/nsidc/iceflow/__init__.py

@@ -22,8 +22,6 @@
 from nsidc.iceflow.data.models import (
     ALL_DATASETS,
     BLATM1BDataset,
-    BoundingBox,
-    DatasetSearchParameters,
     GLAH06Dataset,
     IceflowDataFrame,
     ILATM1BDataset,
@@ -32,16 +30,12 @@
 from nsidc.iceflow.data.read import read_iceflow_datafiles
 from nsidc.iceflow.itrf.converter import transform_itrf
 
-# TODO: add bumpversion config to control this version number, and the conda
-# recipe/meta.yaml.
 __version__ = "v1.0.0"
 
 
 __all__ = [
     "ALL_DATASETS",
     "BLATM1BDataset",
-    "BoundingBox",
-    "DatasetSearchParameters",
     "GLAH06Dataset",
     "ILATM1BDataset",
     "ILVIS2Dataset",

src/nsidc/iceflow/api.py

@@ -11,16 +11,20 @@
 from nsidc.iceflow.data.fetch import download_iceflow_results, find_iceflow_data
 from nsidc.iceflow.data.models import (
     ALL_DATASETS,
-    DatasetSearchParameters,
+    BoundingBoxLike,
+    Dataset,
     IceflowDataFrame,
+    TemporalRange,
 )
 from nsidc.iceflow.data.read import read_iceflow_datafiles
 from nsidc.iceflow.itrf.converter import transform_itrf
 
 
 def fetch_iceflow_df(
     *,
-    dataset_search_params: DatasetSearchParameters,
+    bounding_box: BoundingBoxLike,
+    temporal: TemporalRange,
+    datasets: list[Dataset] = ALL_DATASETS,
     output_dir: Path,
     # TODO: also add option for target epoch!!
     output_itrf: str | None = None,
@@ -38,7 +42,9 @@ def fetch_iceflow_df(
     """
 
     iceflow_search_reuslts = find_iceflow_data(
-        dataset_search_params=dataset_search_params,
+        bounding_box=bounding_box,
+        temporal=temporal,
+        datasets=datasets,
     )
 
     downloaded_files = download_iceflow_results(

src/nsidc/iceflow/data/fetch.py

@@ -1,31 +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 (
-    BoundingBox,
+    ALL_DATASETS,
     Dataset,
-    DatasetSearchParameters,
     IceflowSearchResult,
     IceflowSearchResults,
 )
 
 
-def _find_iceflow_data(
+def _find_iceflow_data_for_dataset(
     *,
     dataset: Dataset,
-    bounding_box: BoundingBox,
-    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(
@@ -35,13 +30,7 @@ def _find_iceflow_data(
             # non-cloud, we may get duplicate granules as long as the ECS copy
             # remains.
             cloud_hosted=True,
-            bounding_box=(
-                bounding_box.lower_left_lon,
-                bounding_box.lower_left_lat,
-                bounding_box.upper_right_lon,
-                bounding_box.upper_right_lat,
-            ),
-            temporal=temporal,
+            **search_kwargs,
         )
     except IndexError:
         # There's no data matching the given parameters.
@@ -88,14 +77,20 @@ def _download_iceflow_search_result(
 
 def find_iceflow_data(
     *,
-    dataset_search_params: DatasetSearchParameters,
+    datasets: list[Dataset] = ALL_DATASETS,
+    **search_kwargs,
 ) -> IceflowSearchResults:
+    """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 dataset_search_params.datasets:
-        iceflow_search_result = _find_iceflow_data(
+    for dataset in datasets:
+        iceflow_search_result = _find_iceflow_data_for_dataset(
             dataset=dataset,
-            bounding_box=dataset_search_params.bounding_box,
-            temporal=dataset_search_params.temporal,
+            **search_kwargs,
         )
         iceflow_search_results.append(iceflow_search_result)
 

src/nsidc/iceflow/data/models.py

@@ -229,60 +229,10 @@ class GLAH06Dataset(Dataset):
     version: Literal["034"] = "034"
 
 
-class BoundingBox(pydantic.BaseModel):
-    lower_left_lon: float
-    lower_left_lat: float
-    upper_right_lon: float
-    upper_right_lat: float
-
-    def __init__(self, *args, **kwargs):
-        """Accept either named args, one arg for each coord, or an iterable of
-        `(lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)`."""
-        if args:
-            if len(args) == 1 and isinstance(args[0], list | tuple):
-                # The first arg should be treated like a tuple of
-                # (lower_left_lon, lower_left_lat, upper_right_lon,
-                # upper_right_lat)
-                args = tuple(args[0])
-            # Each arg should be treated as one of (lower_left_lon,
-            # lower_left_lat, upper_right_lon, upper_right_lat).
-            if len(args) != 4:
-                raise ValueError(
-                    "Expected four values for bounding box:"
-                    " (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)"
-                )
-            # Set kwargs if args are given.
-            kwargs = {
-                "lower_left_lon": args[0],
-                "lower_left_lat": args[1],
-                "upper_right_lon": args[2],
-                "upper_right_lat": args[3],
-            }
-
-        # Initialize the model.
-        super().__init__(**kwargs)
-
-    def __iter__(self):
-        """Return bounding box as a iter (list/tuple)."""
-        return iter(
-            (
-                self.lower_left_lon,
-                self.lower_left_lat,
-                self.upper_right_lon,
-                self.upper_right_lat,
-            )
-        )
-
-    def __getitem__(self, idx):
-        if isinstance(idx, int):
-            return list(self.__iter__())[idx]
-        elif isinstance(idx, str):
-            return getattr(self, idx)
-        else:
-            raise TypeError(
-                "Getitem on BoundingBox must be int (e.g. 0)"
-                " or str (e.g., 'lower_left_lon')."
-            )
+# This mirrors the bounding box construct in `earthaccess` and `icepyx`: a
+# list/float of len 4:
+# (lower_left_lon, lower_left_lat, upper_right_lon, upper_right_lat)
+BoundingBoxLike = list[float] | tuple[float, float, float, float]
 
 
 ALL_DATASETS: list[Dataset] = [
@@ -295,10 +245,7 @@ def __getitem__(self, idx):
 ]
 
 
-class DatasetSearchParameters(pydantic.BaseModel):
-    datasets: list[Dataset] = ALL_DATASETS
-    bounding_box: BoundingBox
-    temporal: tuple[dt.datetime | dt.date, dt.datetime | dt.date]
+TemporalRange = tuple[dt.datetime | dt.date, dt.datetime | dt.date]
 
 
 class IceflowSearchResult(pydantic.BaseModel):