Add rename_like (#55)

Renames variables in object to match names of like-variables in ``other``.

"Likeness" is determined by variables sharing similar attributes. If
cf_xarray can identify a single "longitude" variable in both this object and
``other``, that variable will be renamed to match the "longitude" variable in
``other``.

For now, this function only matches ``("latitude", "longitude", "vertical", "time")``

Author: dcherian

cf_xarray/accessor.py

@@ -158,6 +158,8 @@ def _get_axis_coord_single(
         raise ValueError(
             f"Multiple results for {key!r} found: {results!r}. Is this valid CF? Please open an issue."
         )
+    elif len(results) == 0:
+        raise ValueError(f"No results found for {key!r}.")
     return results
 
 
@@ -276,6 +278,8 @@ def _get_measure(da: Union[xr.DataArray, xr.Dataset], key: str) -> List[Optional
 #       We need this for groupby("T.month") and groupby("latitude") for example.
 _DEFAULT_KEY_MAPPERS: Mapping[str, Mapper] = {
     "dim": _get_axis_coord,
+    "dims": _get_axis_coord,  # is this necessary?
+    "coords": _get_axis_coord,  # interp
     "indexers": _get_axis_coord,  # sel, isel
     "dims_or_levels": _get_axis_coord,  # reset_index
     "coord": _get_axis_coord_single,
@@ -883,6 +887,56 @@ def add_bounds(self, dims: Union[Hashable, Iterable[Hashable]]):
 
         return self._maybe_to_dataarray(obj)
 
+    def rename_like(
+        self, other: Union[xr.DataArray, xr.Dataset]
+    ) -> Union[xr.DataArray, xr.Dataset]:
+        """
+        Renames variables in object to match names of like-variables in ``other``.
+
+        "Likeness" is determined by variables sharing similar attributes. If
+        cf_xarray can identify a single "longitude" variable in both this object and
+        ``other``, that variable will be renamed to match the "longitude" variable in
+        ``other``.
+
+        For now, this function only matches ``("latitude", "longitude", "vertical", "time")``
+
+        Parameters
+        ----------
+        other: DataArray, Dataset
+            Variables will be renamed to match variable names in this xarray object
+
+        Returns
+        -------
+        DataArray or Dataset with renamed variables
+        """
+        ourkeys = self.get_valid_keys()
+        theirkeys = other.cf.get_valid_keys()
+
+        good_keys = set(_COORD_NAMES) & ourkeys & theirkeys
+        if not good_keys:
+            raise ValueError(
+                "No common coordinate variables between these two objects."
+            )
+
+        renamer = {}
+        for key in good_keys:
+            ours = _get_axis_coord_single(self._obj, key)[0]
+            theirs = _get_axis_coord_single(other, key)[0]
+            renamer[ours] = theirs
+
+        newobj = self._obj.rename(renamer)
+
+        # rename variable names in the coordinates attribute
+        # if present
+        ds = self._maybe_to_dataset(newobj)
+        for _, variable in ds.variables.items():
+            coordinates = variable.attrs.get("coordinates", None)
+            if coordinates:
+                for k, v in renamer.items():
+                    coordinates = coordinates.replace(k, v)
+                variable.attrs["coordinates"] = coordinates
+        return self._maybe_to_dataarray(ds)
+
 
 @xr.register_dataset_accessor("cf")
 class CFDatasetAccessor(CFAccessor):

cf_xarray/tests/test_accessor.py

@@ -96,6 +96,23 @@ def test_getitem_ancillary_variables():
         assert k not in popds.cf["UVEL"].coords
 
 
+def test_rename_like():
+    original = popds.copy(deep=True)
+
+    with pytest.raises(ValueError):
+        popds.cf.rename_like(airds)
+
+    renamed = popds.cf["TEMP"].cf.rename_like(airds)
+    for k in ["TLONG", "TLAT"]:
+        assert k not in renamed.coords
+        assert k in original.coords
+        assert original.TEMP.attrs["coordinates"] == "TLONG TLAT"
+
+    assert "lon" in renamed.coords
+    assert "lat" in renamed.coords
+    assert renamed.attrs["coordinates"] == "lon lat"
+
+
 @pytest.mark.parametrize("obj", objects)
 @pytest.mark.parametrize(
     "attr, xrkwargs, cfkwargs",

ci/doc.yml

@@ -13,6 +13,6 @@ dependencies:
   - ipython
   - ipykernel
   - pip:
-      - cf_xarray
+      - git+https://github.com/xarray-contrib/cf-xarray
       - sphinx-book-theme
       - git+https://github.com/keewis/sphinx-autosummary-accessors

doc/api.rst

@@ -19,6 +19,7 @@ DataArray
     DataArray.cf.add_bounds
     DataArray.cf.describe
     DataArray.cf.get_valid_keys
+    DataArray.cf.rename_like
 
 Dataset
 -------
@@ -34,3 +35,4 @@ Dataset
     Dataset.cf.add_bounds
     Dataset.cf.describe
     Dataset.cf.get_valid_keys
+    Dataset.cf.rename_like

doc/examples/introduction.ipynb

@@ -496,6 +496,30 @@
     "multiple.v1.cf.sizes"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Feature: Renaming coordinate variables\n",
+    "\n",
+    "`cf_xarray` lets you rewrite coordinate variables in one dataset to like\n",
+    "variables in another dataset. This can only be done when a one-to-one mapping is\n",
+    "possible\n",
+    "\n",
+    "In this example, `TLONG` and `TLAT` are renamed to `lon` and `lat` i.e. their\n",
+    "counterparts in `ds`. Note the the `coordinates` attribute is appropriately\n",
+    "changed.\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "pop.cf[\"TEMP\"].cf.rename_like(ds)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},

doc/whats-new.rst

@@ -1,10 +1,13 @@
 What's New
 ----------
 
-v0.1.6
-======
+v0.1.6 (unreleased)
+===================
 
-- Added ```.cf.add_bounds`` to add guessed bounds for 1D coorindates. (:pr:`53`) `Deepak Cherian`_.
+- Added ``.cf.rename_like`` to rename matching variables. Only coordinate variables
+  i.e. those that match the criteria for ``("latitude", "longitude", "vertical", "time")``
+  are renamed for now. (:pr:`55`) `Deepak Cherian`_.
+- Added ``.cf.add_bounds`` to add guessed bounds for 1D coordinates. (:pr:`53`) `Deepak Cherian`_.
 
 v0.1.5
 ======