fix: add bounds selection support

README.md

@@ -54,6 +54,24 @@ async def main():
         data_dict = dataset_filtered.as_dict()
         print(data_dict['data'])
 
+        # Or load and select in one call.
+        western_europe, metadata = await dclimate.select_dataset(
+            request={
+                "dataset": "temperature_2m",
+                "collection": "era5",
+                "organization": "ecmwf",
+                "variant": "finalized",
+            },
+            selection={
+                # Bounds are [west, south, east, north].
+                "bounds": [-12, 35, 16, 60],
+                "time_range": {
+                    "start": datetime(2024, 1, 1),
+                    "end": datetime(2024, 1, 7, 23),
+                },
+            },
+        )
+
 # Custom IPFS endpoints (optional)
 async def main_custom_ipfs():
     async with dClimateClient(

dclimate_client_py/client.py

@@ -46,6 +46,8 @@ def geo_temporal_query(
     rectangle_kwargs: dict = None,
     polygon_kwargs: dict = None,
     multiple_points_kwargs: dict = None,
+    bounds=None,
+    bounds_options: dict = None,
     spatial_agg_kwargs: dict = None,
     temporal_agg_kwargs: dict = None,
     rolling_agg_kwargs: dict = None,
@@ -64,9 +66,9 @@ def geo_temporal_query(
 
     Return either a numpy array of data values or a NetCDF file.
 
-    Only one of point, circle, rectangle, or polygon kwargs may be provided. Only one of
-    temporal or rolling aggregation kwargs may be provided, although they can be chained
-    with spatial aggregations if desired.
+    Only one of point, circle, rectangle, bounds, or polygon kwargs may be provided. Only
+    one of temporal or rolling aggregation kwargs may be provided, although they can be
+    chained with spatial aggregations if desired.
 
     Args:
         dataset_name (str): Name used to identify the dataset within the STAC catalog (for IPFS)
@@ -82,6 +84,10 @@ def geo_temporal_query(
             circular query
         rectangle_kwargs (dict, optional): a dictionary of parameters relevant to a
             rectangular query
+        bounds (list | tuple | dict, optional): rectangular bounds in
+            ``[west, south, east, north]`` order, or a mapping with those keys.
+        bounds_options (dict, optional): optional coordinate key overrides for bounds
+            selections, using ``latitude_key`` and ``longitude_key``.
         polygon_kwargs (dict, optional): a dictionary of parameters relevant to a
             polygonal query
         multiple_points_kwargs (dict, optional): Parameters for querying multiple specific points.
@@ -118,6 +124,7 @@ def geo_temporal_query(
                     polygon_kwargs,
                     multiple_points_kwargs,
                     point_kwargs,
+                    bounds,
                 ]
                 if kwarg_dict is not None
             ]
@@ -175,6 +182,8 @@ def geo_temporal_query(
         rectangle_kwargs=rectangle_kwargs,
         polygon_kwargs=polygon_kwargs,
         multiple_points_kwargs=multiple_points_kwargs,
+        bounds=bounds,
+        bounds_options=bounds_options,
         spatial_agg_kwargs=spatial_agg_kwargs,
         temporal_agg_kwargs=temporal_agg_kwargs,
         rolling_agg_kwargs=rolling_agg_kwargs,

dclimate_client_py/dclimate_client.py

@@ -6,6 +6,8 @@
 """
 
 import typing
+from collections.abc import Mapping
+
 import requests
 import xarray as xr
 from py_hamt import KuboCAS
@@ -326,6 +328,53 @@ async def load_dataset(
         else:
             return GeotemporalData(ds, dataset_name=metadata["slug"]), metadata
 
+    async def select_dataset(
+        self,
+        *,
+        request: typing.Mapping[str, typing.Any],
+        selection: typing.Mapping[str, typing.Any],
+        return_xarray: bool = False,
+    ) -> typing.Union[
+        typing.Tuple[GeotemporalData, DatasetMetadata],
+        typing.Tuple[xr.Dataset, DatasetMetadata],
+    ]:
+        """
+        Load a dClimate dataset and apply point, bounds, and/or time selections.
+
+        Parameters
+        ----------
+        request : Mapping[str, Any]
+            Keyword arguments accepted by :meth:`load_dataset`, such as
+            ``dataset``, ``collection``, ``variant``, ``organization``, or ``cid``.
+        selection : Mapping[str, Any]
+            Selection mapping accepted by :meth:`GeotemporalData.select`.
+        return_xarray : bool, optional
+            If True, return the raw xarray dataset without applying selections.
+
+        Returns
+        -------
+        Tuple[Union[GeotemporalData, xr.Dataset], DatasetMetadata]
+            The selected dataset plus metadata.
+        """
+        if not isinstance(request, Mapping):
+            raise InvalidSelectionError("request must be a mapping.")
+        if not isinstance(selection, Mapping):
+            raise InvalidSelectionError("selection must be a mapping.")
+
+        load_kwargs = dict(request)
+        load_kwargs.pop("return_xarray", None)
+        if load_kwargs.get("cid") and "dataset" not in load_kwargs:
+            load_kwargs["dataset"] = ""
+
+        dataset_obj, metadata = await self.load_dataset(
+            **load_kwargs,
+            return_xarray=return_xarray,
+        )
+        if not isinstance(dataset_obj, GeotemporalData):
+            return dataset_obj, metadata
+
+        return dataset_obj.select(selection), metadata
+
     def list_datasets(self) -> typing.Dict[str, typing.Dict[str, typing.Any]]:
         """
         List all available datasets from the STAC catalog.