properties now return dictionaries rather than lists (#110)

* properties now return dicts rather than list

* sort standard names

* no need to call dict twice

* describe uses properties

* update docs

* oops, restore sorting

* sorting in describe and update .keys

Author: malmans2

cf_xarray/accessor.py

@@ -823,31 +823,30 @@ def describe(self):
         Print a string repr to screen.
         """
         text = "Axes:\n"
+        axes = self.axes
         for key in _AXIS_NAMES:
-            axes = apply_mapper(_get_axis_coord, self._obj, key, error=False)
-            text += f"\t{key}: {axes}\n"
+            text += f"\t{key}: {axes[key] if key in axes else []}\n"
 
         text += "\nCoordinates:\n"
+        coords = self.coordinates
         for key in _COORD_NAMES:
-            coords = apply_mapper(_get_axis_coord, self._obj, key, error=False)
-            text += f"\t{key}: {coords}\n"
+            text += f"\t{key}: {coords[key] if key in coords else []}\n"
 
         text += "\nCell Measures:\n"
-        for measure in _CELL_MEASURES:
-            if isinstance(self._obj, Dataset):
-                text += f"\t{measure}: unsupported\n"
-            else:
-                measures = apply_mapper(_get_measure, self._obj, measure, error=False)
-                text += f"\t{measure}: {measures}\n"
+        if isinstance(self._obj, Dataset):
+            measures = {key: "unsupported" for key in _CELL_MEASURES}
+        else:
+            measures = self.cell_measures
+        for key in _CELL_MEASURES:
+            text += f"\t{key}: {measures[key] if key in measures else []}\n"
 
         text += "\nStandard Names:\n"
         if isinstance(self._obj, DataArray):
             text += "\tunsupported\n"
         else:
-            stdnames = sorted(self.get_standard_names())
-            for name in stdnames:
-                if name not in _COORD_NAMES:
-                    text += f"\t{name}: {_get_with_standard_name(self._obj, name)}\n"
+            for key, value in sorted(self.standard_names.items()):
+                if key not in _COORD_NAMES:
+                    text += f"\t{key}: {value}\n"
 
         print(text)
 
@@ -871,101 +870,92 @@ def keys(self) -> Set[str]:
         -------
         Set of valid key names that can be used with __getitem__ or .cf[key].
         """
-        varnames = [
-            key
-            for key in _AXIS_NAMES + _COORD_NAMES
-            if apply_mapper(_get_axis_coord, self._obj, key, error=False)
-        ]
+
+        varnames = list(self.axes) + list(self.coordinates)
         if not isinstance(self._obj, Dataset):
-            measures = [
-                key
-                for key in _CELL_MEASURES
-                if apply_mapper(_get_measure, self._obj, key, error=False)
-            ]
-            if measures:
-                varnames.extend(measures)
-
-        varnames.extend(self.get_standard_names())
+            varnames.extend(list(self.cell_measures))
+        varnames.extend(list(self.standard_names))
+
         return set(varnames)
 
     @property
-    def axes(self) -> Set[str]:
+    def axes(self) -> Dict[str, List[str]]:
         """
-        Property that returns valid Axis names for ``.cf[]``.
+        Property that returns a dictionary mapping valid Axis standard names for ``.cf[]``
+        to variable names.
 
         This is useful for checking whether a key is valid for indexing, i.e.
         that the attributes necessary to allow indexing by that key exist.
         However, it will only return the Axis names, not Coordinate names.
 
         Returns
         -------
-        Set of valid Axis names that can be used with ``__getitem__`` or ``.cf[key]``.
+        Dictionary of valid Axis names that can be used with ``__getitem__`` or ``.cf[key]``.
         Will be ("X", "Y", "Z", "T") or a subset thereof.
         """
-        varnames = [
-            key
+        vardict = {
+            key: apply_mapper(_get_axis_coord, self._obj, key, error=False)
             for key in _AXIS_NAMES
-            if apply_mapper(_get_axis_coord, self._obj, key, error=False)
-        ]
+        }
 
-        return set(varnames)
+        return {k: sorted(v) for k, v in vardict.items() if v}
 
     @property
-    def coordinates(self) -> Set[str]:
+    def coordinates(self) -> Dict[str, List[str]]:
         """
-        Property that returns valid Coordinate names for .cf[].
+        Property that returns a dictionary mapping valid Coordinate standard names for ``.cf[]``
+        to variable names.
 
         This is useful for checking whether a key is valid for indexing, i.e.
         that the attributes necessary to allow indexing by that key exist.
         However, it will only return the Coordinate names, not Axis names.
 
         Returns
         -------
-        Set of valid Coordinate names that can be used with ``__getitem__`` or ``.cf[key]``.
+        Dictionary of valid Coordinate names that can be used with ``__getitem__`` or ``.cf[key]``.
         Will be ("longitude", "latitude", "vertical", "time") or a subset thereof.
         """
-        varnames = [
-            key
+        vardict = {
+            key: apply_mapper(_get_axis_coord, self._obj, key, error=False)
             for key in _COORD_NAMES
-            if apply_mapper(_get_axis_coord, self._obj, key, error=False)
-        ]
+        }
 
-        return set(varnames)
+        return {k: sorted(v) for k, v in vardict.items() if v}
 
     @property
-    def cell_measures(self) -> Set[str]:
+    def cell_measures(self) -> Dict[str, List[str]]:
         """
-        Property that returns valid cell measure names for .cf[].
+        Property that returns a dictionary mapping valid cell measure standard names for ``.cf[]``
+        to variable names.
 
         This is useful for checking whether a key is valid for indexing, i.e.
         that the attributes necessary to allow indexing by that key exist.
         However, it will only return the cell measure names.
 
         Returns
         -------
-        Set of valid cell measure names that can be used with __getitem__ or .cf[key].
+        Dictionary of valid cell measure names that can be used with __getitem__ or .cf[key].
         """
-        assert isinstance(self._obj, DataArray), "this works with DataArrays"
+        assert isinstance(self._obj, DataArray), "this only works with DataArrays"
 
-        measures = [
-            key
+        measures = {
+            key: apply_mapper(_get_measure, self._obj, key, error=False)
             for key in _CELL_MEASURES
-            if apply_mapper(_get_measure, self._obj, key, error=False)
-        ]
+        }
 
-        return set(measures)
+        return {k: sorted(v) for k, v in measures.items() if v}
 
     def get_standard_names(self) -> List[str]:
 
         warnings.warn(
-            "Now called `standard_names` and `get_standard_names` will be removed in a future version.",
+            "`get_standard_names` will be removed in a future version in favor of `standard_names`.",
             DeprecationWarning,
         )
 
-        return self.standard_names
+        return list(self.standard_names.keys())
 
     @property
-    def standard_names(self) -> List[str]:
+    def standard_names(self) -> Dict[str, List[str]]:
         """
         Returns a sorted list of standard names in Dataset.
 
@@ -977,21 +967,20 @@ def standard_names(self) -> List[str]:
 
         Returns
         -------
-        list of standard names in dataset
+        Dictionary of standard names in dataset
         """
         if isinstance(self._obj, Dataset):
             variables = self._obj.variables
         elif isinstance(self._obj, DataArray):
             variables = self._obj.coords
-        return sorted(
-            set(
-                [
-                    v.attrs["standard_name"]
-                    for k, v in variables.items()
-                    if "standard_name" in v.attrs
-                ]
-            )
-        )
+
+        vardict: Dict[str, List[str]] = dict()
+        for k, v in variables.items():
+            if "standard_name" in v.attrs:
+                std_name = v.attrs["standard_name"]
+                vardict[std_name] = vardict.setdefault(std_name, []) + [k]
+
+        return {k: sorted(v) for k, v in vardict.items()}
 
     def get_associated_variable_names(self, name: Hashable) -> Dict[str, List[str]]:
         """

cf_xarray/tests/test_accessor.py

@@ -33,34 +33,45 @@ def test_describe(capsys):
 
 
 def test_axes():
-    expected = {"T", "X", "Y"}
+    expected = dict(T=["time"], X=["lon"], Y=["lat"])
     actual = airds.cf.axes
     assert actual == expected
 
-    expected = {"X", "Y"}
+    expected = dict(X=["nlon"], Y=["nlat"])
     actual = popds.cf.axes
     assert actual == expected
 
 
 def test_coordinates():
-    expected = {"latitude", "longitude", "time"}
+    expected = dict(latitude=["lat"], longitude=["lon"], time=["time"])
     actual = airds.cf.coordinates
     assert actual == expected
 
-    expected = {"latitude", "longitude"}
+    expected = dict(latitude=["TLAT", "ULAT"], longitude=["TLONG", "ULONG"])
     actual = popds.cf.coordinates
     assert actual == expected
 
 
+def test_cell_measures():
+    expected = dict(area=["cell_area"])
+    actual = airds["air"].cf.cell_measures
+    assert actual == expected
+
+    with pytest.raises(AssertionError, match=r"this only works with DataArrays"):
+        popds.cf.cell_measures
+
+
 def test_standard_names():
-    expected = ["air_temperature", "latitude", "longitude", "time"]
+    expected = dict(
+        air_temperature=["air"], latitude=["lat"], longitude=["lon"], time=["time"]
+    )
     actual = airds.cf.standard_names
     assert actual == expected
 
     dsnew = xr.Dataset()
     dsnew["a"] = ("a", np.arange(10), {"standard_name": "a"})
     dsnew["b"] = ("a", np.arange(10), {"standard_name": "a"})
-    assert dsnew.cf.standard_names == ["a"]
+    assert dsnew.cf.standard_names == dict(a=["a", "b"])
 
 
 def test_getitem_standard_name():

doc/whats-new.rst

@@ -4,9 +4,9 @@ What's New
 
 v0.4.0 (unreleased)
 ===================
-- Added ``.axes`` to return available Axis names for an xarray object, ``.coordinates`` for Coordinate names,
-  ``.standard_names`` for standard names, ``.cell_measures`` for cell measures,
-  and changed ``get_valid_keys()`` to ``.keys()``. `Kristen Thyng`_.
+- Added ``.axes`` to return a dictionary mapping available Axis standard names to variable names of an xarray object, ``.coordinates`` for Coordinates, 
+  ``.cell_measures`` for Cell Measures, and ``.standard_names`` for all variables. `Kristen Thyng`_ and `Mattia Almansi`_.
+- Changed ``get_valid_keys()`` to ``.keys()``. `Kristen Thyng`_.
 - Added ``.cf.decode_vertical_coords`` for decoding of parameterized vertical coordinate variables.
   (:issue:`34`, :pr:`103`). `Deepak Cherian`_.
 - Added top-level ``bounds_to_vertices`` and ``vertices_to_bounds`` as well as ``.cf.bounds_to_vertices`` 
@@ -61,6 +61,7 @@ v0.1.3
 
 - Support expanding key to multiple dimension names.
 
+.. _`Mattia Almansi`: https://github.com/malmans2
 .. _`Anderson Banihirwe`: https://github.com/andersy005
 .. _`Pascal Bourgault`: https://github.com/aulemahal
 .. _`Deepak Cherian`: https://github.com/dcherian