Add .cf.add_bounds to guess bounds for 1D coord. (#53)

* Add .cf.add_bounds to guess bounds for 1D coord.

Adds a bounds variable assuming equal spacing on either side of a
coordinate label. The variable is named f"{dim}_bounds" and raises
an error if there is an existing variable with the same name.

Also adds appropriate "bounds" attribute to the coordinate variable.

Fixes #35

Author: dcherian

cf_xarray/accessor.py

@@ -8,6 +8,7 @@
 from typing import (
     Callable,
     Hashable,
+    Iterable,
     List,
     Mapping,
     MutableMapping,
@@ -321,6 +322,25 @@ def _get_list_standard_names(obj: xr.Dataset) -> List[str]:
     )
 
 
+def _guess_bounds_dim(da):
+    """
+    Guess bounds values given a 1D coordinate variable.
+    Assumes equal spacing on either side of the coordinate label.
+    """
+    assert da.ndim == 1
+
+    dim = da.dims[0]
+    diff = da.diff(dim)
+    lower = da - diff / 2
+    upper = da + diff / 2
+    bounds = xr.concat([lower, upper], dim="bounds")
+
+    first = (bounds.isel({dim: 0}) - diff[0]).assign_coords({dim: da[dim][0]})
+    result = xr.concat([first, bounds], dim=dim)
+
+    return result
+
+
 def _getattr(
     obj: Union[DataArray, Dataset],
     attr: str,
@@ -805,6 +825,63 @@ def __getitem__(self, key: Union[str, List[str]]):
                 f"Use {kind}.cf.describe() to see a list of key names that can be interpreted."
             )
 
+    def _maybe_to_dataset(self, obj=None) -> xr.Dataset:
+        if obj is None:
+            obj = self._obj
+        if isinstance(self._obj, xr.DataArray):
+            return obj._to_temp_dataset()
+        else:
+            return obj
+
+    def _maybe_to_dataarray(self, obj=None):
+        if obj is None:
+            obj = self._obj
+        if isinstance(self._obj, xr.DataArray):
+            return self._obj._from_temp_dataset(obj)
+        else:
+            return obj
+
+    def add_bounds(self, dims: Union[Hashable, Iterable[Hashable]]):
+        """
+        Returns a new object with bounds variables. The bounds values are guessed assuming
+        equal spacing on either side of a coordinate label.
+
+        Parameters
+        ----------
+        dims: Hashable or Iterable[Hashable]
+            Either a single dimension name or a list of dimension names.
+
+        Returns
+        -------
+        DataArray or Dataset with bounds variables added and appropriate "bounds" attribute set.
+
+        Notes
+        -----
+
+        The bounds variables are automatically named f"{dim}_bounds" where ``dim``
+        is a dimension name.
+        """
+        if isinstance(dims, Hashable):
+            dimensions = (dims,)
+        else:
+            dimensions = dims
+
+        bad_dims: Set[Hashable] = set(dimensions) - set(self._obj.dims)
+        if bad_dims:
+            raise ValueError(
+                f"{bad_dims!r} are not dimensions in the underlying object."
+            )
+
+        obj = self._maybe_to_dataset(self._obj.copy(deep=True))
+        for dim in dimensions:
+            bname = f"{dim}_bounds"
+            if bname in obj.variables:
+                raise ValueError(f"Bounds variable name {bname!r} will conflict!")
+            obj.coords[bname] = _guess_bounds_dim(obj[dim].reset_coords(drop=True))
+            obj[dim].attrs["bounds"] = bname
+
+        return self._maybe_to_dataarray(obj)
+
 
 @xr.register_dataset_accessor("cf")
 class CFDatasetAccessor(CFAccessor):

cf_xarray/tests/test_accessor.py

@@ -1,8 +1,10 @@
 import matplotlib as mpl
+import numpy as np
+import pandas as pd
 import pytest
 import xarray as xr
 from matplotlib import pyplot as plt
-from xarray.testing import assert_identical
+from xarray.testing import assert_allclose, assert_identical
 
 import cf_xarray  # noqa
 
@@ -287,3 +289,47 @@ def test_plot_xincrease_yincrease():
 
     for lim in [ax.get_xlim(), ax.get_ylim()]:
         assert lim[0] > lim[1]
+
+
+@pytest.mark.parametrize("dims", ["lat", "time", ["lat", "lon"]])
+@pytest.mark.parametrize("obj", [airds, airds.air])
+def test_add_bounds(obj, dims):
+    expected = dict()
+    expected["lat"] = xr.concat(
+        [
+            obj.lat.copy(data=np.arange(76.25, 16.0, -2.5)),
+            obj.lat.copy(data=np.arange(73.75, 13.6, -2.5)),
+        ],
+        dim="bounds",
+    )
+    expected["lon"] = xr.concat(
+        [
+            obj.lon.copy(data=np.arange(198.75, 325 - 1.25, 2.5)),
+            obj.lon.copy(data=np.arange(201.25, 325 + 1.25, 2.5)),
+        ],
+        dim="bounds",
+    )
+    t0 = pd.Timestamp("2013-01-01")
+    t1 = pd.Timestamp("2013-01-01 18:00")
+    dt = "6h"
+    dtb2 = pd.Timedelta("3h")
+    expected["time"] = xr.concat(
+        [
+            obj.time.copy(data=pd.date_range(start=t0 - dtb2, end=t1 - dtb2, freq=dt)),
+            obj.time.copy(data=pd.date_range(start=t0 + dtb2, end=t1 + dtb2, freq=dt)),
+        ],
+        dim="bounds",
+    )
+    expected["lat"].attrs.clear()
+    expected["lon"].attrs.clear()
+    expected["time"].attrs.clear()
+
+    added = obj.cf.add_bounds(dims)
+    if isinstance(dims, str):
+        dims = (dims,)
+
+    for dim in dims:
+        name = f"{dim}_bounds"
+        assert name in added.coords
+        assert added[dim].attrs["bounds"] == name
+        assert_allclose(added[name].reset_coords(drop=True), expected[dim])

doc/whats-new.rst

@@ -1,6 +1,11 @@
 What's New
 ----------
 
+v0.1.6
+======
+
+- Added ```.cf.add_bounds`` to add guessed bounds for 1D coorindates. (:pr:`53`) `Deepak Cherian`_.
+
 v0.1.5
 ======
 - Wrap ``.sizes`` and ``.chunks``. (:pr:`42`) `Deepak Cherian`_.