Add "get_bounds_dim_name" (#159)

Author: aulemahal

cf_xarray/accessor.py

@@ -1378,6 +1378,27 @@ def get_bounds(self, key: str) -> DataArray:
         obj = self._maybe_to_dataset()
         return obj[bounds]
 
+    def get_bounds_dim_name(self, key: str) -> str:
+        """
+        Get bounds dim name for variable corresponding to key.
+
+        Parameters
+        ----------
+        key : str
+            Name of variable whose bounds dimension name is desired.
+
+        Returns
+        -------
+        str
+        """
+        crd = self[key]
+        bounds = self.get_bounds(key)
+        bounds_dims = set(bounds.dims) - set(crd.dims)
+        assert len(bounds_dims) == 1
+        bounds_dim = bounds_dims.pop()
+        assert self._obj.sizes[bounds_dim] in [2, 4]
+        return bounds_dim
+
     def add_bounds(self, dims: Union[Hashable, Iterable[Hashable]]):
         """
         Returns a new object with bounds variables. The bounds values are guessed assuming

cf_xarray/tests/test_accessor.py

@@ -9,7 +9,16 @@
 
 import cf_xarray  # noqa
 
-from ..datasets import airds, anc, ds_no_attrs, forecast, multiple, popds, romsds
+from ..datasets import (
+    airds,
+    anc,
+    ds_no_attrs,
+    forecast,
+    mollwds,
+    multiple,
+    popds,
+    romsds,
+)
 from . import raise_if_dask_computes
 
 mpl.use("Agg")
@@ -522,6 +531,15 @@ def test_bounds_to_vertices():
     assert "time_bounds" in dsc
 
 
+def test_get_bounds_dim_name():
+    ds = airds.copy(deep=True).cf.add_bounds("lat")
+    assert ds.cf.get_bounds_dim_name("latitude") == "bounds"
+    assert ds.cf.get_bounds_dim_name("lat") == "bounds"
+
+    assert mollwds.cf.get_bounds_dim_name("longitude") == "bounds"
+    assert mollwds.cf.get_bounds_dim_name("lon") == "bounds"
+
+
 def test_docstring():
     assert "One of ('X'" in airds.cf.groupby.__doc__
     assert "One or more of ('X'" in airds.cf.mean.__doc__

doc/api.rst

@@ -81,6 +81,7 @@ Methods
     Dataset.cf.decode_vertical_coords
     Dataset.cf.describe
     Dataset.cf.get_bounds
+    Dataset.cf.get_bounds_dim_name
     Dataset.cf.guess_coord_axis
     Dataset.cf.keys
     Dataset.cf.rename_like

doc/whats-new.rst

@@ -15,7 +15,8 @@ v0.4.1 (unreleased)
   by :py:meth:`Dataset.cf.__getitem__`. This allows extraction of DataArrays when there are clashes
   between DataArray names and "special" CF names like ``T``.
   (:issue:`129`, :pr:`130`). By `Deepak Cherian`_
-- Fix iteration and arithemtic with ``GroupBy`` objects. By `Deepak Cherian`_.
+- Retrieve bounds dimension name with :py:meth:`Dataset.cf.get_bounds_dim_name`. By `Pascal Bourgault`_.
+- Fix iteration and arithmetic with ``GroupBy`` objects. By `Deepak Cherian`_.
 
 v0.4.0 (Jan 22, 2021)
 =====================