Simplify "bounding box" construct

I was pretty aggressive with using pydantic everywhere with this, but
public-facing api should avoid needing imports of models just to pass params to
functions. This is also consistent with how `icepyx` and `earthaccess` handle
bounding boxes, which we should strive for.

Author: trey-stafford

CHANGELOG.md

@@ -7,6 +7,9 @@
   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.
 
 # v0.3.0
 

docs/getting-started.md

@@ -25,18 +25,13 @@ 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(
-    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)),
-    ),
+    # 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)),
 )
 ```
 

docs/notebooks/iceflow-example.ipynb

@@ -43,7 +43,6 @@
     "import matplotlib.pyplot as plt\n",
     "\n",
     "from nsidc.iceflow import (\n",
-    "    BoundingBox,\n",
     "    DatasetSearchParameters,\n",
     "    ILATM1BDataset,\n",
     "    download_iceflow_results,\n",
@@ -84,11 +83,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",

docs/notebooks/iceflow-with-icepyx.ipynb

@@ -763,7 +763,6 @@
     "import xarray as xr\n",
     "\n",
     "from nsidc.iceflow import (\n",
-    "    BoundingBox,\n",
     "    DatasetSearchParameters,\n",
     "    IceflowDataFrame,\n",
     "    download_iceflow_results,\n",
@@ -804,11 +803,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",

src/nsidc/iceflow/__init__.py

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

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

@@ -7,18 +7,19 @@
 from loguru import logger
 
 from nsidc.iceflow.data.models import (
-    BoundingBox,
+    ALL_DATASETS,
+    BoundingBoxLike,
     Dataset,
-    DatasetSearchParameters,
     IceflowSearchResult,
     IceflowSearchResults,
+    TemporalRange,
 )
 
 
 def _find_iceflow_data_for_dataset(
     *,
     dataset: Dataset,
-    bounding_box: BoundingBox,
+    bounding_box: BoundingBoxLike,
     temporal: tuple[dt.datetime | dt.date, dt.datetime | dt.date],
 ) -> IceflowSearchResult:
     earthaccess.login()
@@ -35,12 +36,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.lower_left_lon,
-                bounding_box.lower_left_lat,
-                bounding_box.upper_right_lon,
-                bounding_box.upper_right_lat,
-            ),
+            bounding_box=bounding_box,
             temporal=temporal,
         )
     except IndexError:
@@ -88,14 +84,17 @@ def _download_iceflow_search_result(
 
 def find_iceflow_data(
     *,
-    dataset_search_params: DatasetSearchParameters,
+    bounding_box: BoundingBoxLike,
+    temporal: TemporalRange,
+    datasets: list[Dataset] = ALL_DATASETS,
 ) -> IceflowSearchResults:
+    """Find iceflow-compatible data using spatial and temporal constraints."""
     iceflow_search_results = []
-    for dataset in dataset_search_params.datasets:
+    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,
+            bounding_box=bounding_box,
+            temporal=temporal,
         )
         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,13 @@ def __getitem__(self, idx):
 ]
 
 
+TemporalRange = tuple[dt.datetime | dt.date, dt.datetime | dt.date]
+
+
 class DatasetSearchParameters(pydantic.BaseModel):
     datasets: list[Dataset] = ALL_DATASETS
-    bounding_box: BoundingBox
-    temporal: tuple[dt.datetime | dt.date, dt.datetime | dt.date]
+    bounding_box: BoundingBoxLike
+    temporal: TemporalRange
 
 
 class IceflowSearchResult(pydantic.BaseModel):