Merge pull request #146 from csiro-coasts/feature/select-indexes

Add `Convention.select_indexes()` method

docs/api/conventions/ugrid.rst

@@ -36,5 +36,5 @@ Topology
 Masking
 =======
 
-.. autofunction:: mask_from_face_indices
+.. autofunction:: mask_from_face_indexes
 .. autofunction:: buffer_faces

docs/developing/conventions.rst

@@ -69,9 +69,9 @@ and returns a value indicating whether this convention implementation can unders
    :pyobject: Grass.check_dataset
 
 :meth:`.DimensionConvention.unpack_index` and :meth:`.DimensionConvention.pack_index`
-transform between native index types and a grid kind and indices.
+transform between native index types and a grid kind and indexes.
 The native representation must be representable as JSON for GeoJSON export support.
-The simplest representation is a tuple of (grid_kind, indices):
+The simplest representation is a tuple of (grid_kind, indexes):
 
 .. literalinclude:: ./grass.py
    :pyobject: Grass.unpack_index

docs/developing/grass.py

@@ -41,8 +41,8 @@ def check_dataset(cls, dataset: xarray.Dataset) -> int | None:
     def unpack_index(self, index: GrassIndex) -> tuple[GrassGridKind, Sequence[int]]:
         return index[0], list(index[1])
 
-    def pack_index(self, grid_kind: GrassGridKind, indices: Sequence[int]) -> GrassIndex:
-        return (grid_kind, list(indices))
+    def pack_index(self, grid_kind: GrassGridKind, indexes: Sequence[int]) -> GrassIndex:
+        return (grid_kind, list(indexes))
 
     @cached_property
     def grid_dimensions(self) -> dict[GrassGridKind, Sequence[Hashable]]:

docs/releases/development.rst

@@ -35,3 +35,19 @@ Next release (in development)
   (:pr:`142`).
 * Add :attr:`.Convention.depth_coordinates` and :meth:`.Convention.get_depth_coordinate_for_data_array()`. Deprecate functions :meth:`.Convention.get_depth_name()`, :meth:`.Convention.get_all_depth_names()`, and :meth:`Convention.get_time_name()`. Remove deprecated functions ``Convention.get_depths()`` and ``Convention.get_times()`` (:pr:`143`).
 * Swap to using `pyproject.toml` for all project metadata (:pr:`145`).
+* Add new methods
+  :meth:`.Convention.selector_for_indexes()`,
+  :meth:`.Convention.select_indexes()`, and
+  :meth:`.Convention.select_points()`.
+  These allow for more efficient extraction of multiple points at the same time.
+  The return type of :meth:`.Convention.selector_for_index()` has been changed
+  from a `dict` to an :class:`xarray.Dataset`,
+  but this new value is also designed to be passed directly to :meth:`Dataset.isel() <xarray.Dataset.isel>`.
+  :meth:`.Convention.select_index()` and :meth:`.Convention.select_indexes()`
+  have a new `drop_geometry` flag which defaults to True.
+  Previously these methods would act as if `drop_geometry` was False,
+  but this led to convention-dependent results as to which geometry variables were returned.
+  The fragmented geometry variables from different conventions often did not contain enough data to be useful.
+  By dropping geometry the results are more consistent across all conventions
+  and do not contain potentially fragmented geometry information.
+  (:issue:`106`, :pr:`146`).

src/emsarray/cli/commands/extract_points.py

@@ -73,7 +73,7 @@ def handle(self, options: argparse.Namespace) -> None:
                 point_dimension=options.point_dimension,
                 missing_points=options.missing_points)
         except point_extraction.NonIntersectingPoints as err:
-            rows = dataframe.iloc[err.indices]
+            rows = dataframe.iloc[err.indexes]
             raise CommandException(
                 f"Error extracting points: the points in the following rows "
                 f"did not intersect the dataset geometry:\n"

src/emsarray/compat/shapely.py

@@ -49,17 +49,17 @@ def query(
         geom: BaseGeometry,
     ) -> numpy.ndarray:
         if shapely_version >= v2:
-            indices = self.index.query(geom)
+            indexes = self.index.query(geom)
         else:
-            indices = self.index._query(geom)
-        return cast(numpy.ndarray, self.items.take(indices))
+            indexes = self.index._query(geom)
+        return cast(numpy.ndarray, self.items.take(indexes))
 
     def nearest(
         self,
         geom: BaseGeometry,
     ) -> numpy.ndarray:
         if shapely_version >= v2:
-            indices = self.index.nearest(geom)
+            indexes = self.index.nearest(geom)
         else:
-            indices = self.index._nearest(geom)
-        return cast(numpy.ndarray, self.items.take(indices))
+            indexes = self.index._nearest(geom)
+        return cast(numpy.ndarray, self.items.take(indexes))