Add differentiate with positive_upward flag. (#198)

* Add differentiate with follow_positive flag.

xref #190

* fix test

* Switch to 'positive_upward' + better docstring

* Also test dataset

* [skip-ci] fix whats-new

* fix docstring

* Update cf_xarray/accessor.py

Co-authored-by: Mattia Almansi <mattia.almansi@noc.ac.uk>

Co-authored-by: Mattia Almansi <mattia.almansi@noc.ac.uk>

Author: dcherian

cf_xarray/accessor.py

@@ -1482,6 +1482,46 @@ def stack(self, dimensions=None, **dimensions_kwargs):
             dimensions.update({key: tuple(itertools.chain(*updates))})
         return self._obj.stack(dimensions)
 
+    def differentiate(
+        self, coord, *xr_args, positive_upward: bool = False, **xr_kwargs
+    ):
+        """
+        Parameters
+        ----------
+        xr_args, xr_kwargs are passed directly to the underlying xarray function.
+        The following are added by cf_xarray:
+
+        positive_upward: optional, bool
+            Change sign of the derivative based on the ``"positive"`` attribute of ``coord``
+            so that positive values indicate increasing upward.
+            If ``positive=="down"``, then multiplied by -1.
+
+        See Also
+        --------
+        DataArray.cf.differentiate
+        Dataset.cf.differentiate
+        xarray.DataArray.differentiate: underlying xarray function
+        xarray.Dataset.differentiate: underlying xarray function
+        """
+        coord = apply_mapper(
+            (_single(_get_coords),), self._obj, coord, error=False, default=[coord]
+        )[0]
+        result = self._obj.differentiate(coord, *xr_args, **xr_kwargs)
+        if positive_upward:
+            coord = self._obj[coord]
+            attrs = coord.attrs
+            if "positive" not in attrs:
+                raise ValueError(
+                    f"positive_upward=True and 'positive' attribute not present on {coord.name}"
+                )
+            if attrs["positive"] not in ["up", "down"]:
+                raise ValueError(
+                    f"positive_upward=True and received attrs['positive']={attrs['positive']}. Expected one of ['up', 'down'] "
+                )
+            if attrs["positive"] == "down":
+                result *= -1
+        return result
+
 
 @xr.register_dataset_accessor("cf")
 class CFDatasetAccessor(CFAccessor):

cf_xarray/tests/test_accessor.py

@@ -1091,3 +1091,54 @@ def test_stack(obj):
 
     actual = obj.cf.stack({"latlon": ["latitude", "longitude"]})
     assert_identical(expected, actual)
+
+
+da = xr.DataArray(
+    np.arange(10)[::-1],  # like ocean temperature
+    dims="z",
+    coords={"z": ("z", np.arange(10))},
+    name="test",
+)
+
+
+@pytest.mark.parametrize("obj", [da, da.to_dataset()])
+def test_differentiate_positive_upward(obj):
+    obj.z.attrs["positive"] = "down"
+    expected = obj.differentiate("z", 2)
+    actual = obj.cf.differentiate("z", 2)
+    assert_identical(expected, actual)
+
+    obj.z.attrs["positive"] = "up"
+    expected = obj.differentiate("z", 2)
+    actual = obj.cf.differentiate("z", 2, positive_upward=True)
+    assert_identical(expected, actual)
+
+    obj.z.attrs["positive"] = "down"
+    expected = -1 * obj.differentiate("z", 2)
+    actual = obj.cf.differentiate("z", 2, positive_upward=True)
+    assert_identical(expected, actual)
+
+    obj = obj.isel(z=slice(None, None, -1))
+    expected = -1 * obj.differentiate("z", 2)
+    actual = obj.cf.differentiate("z", 2, positive_upward=True)
+    assert_identical(expected, actual)
+    obj = obj.isel(z=slice(None, None, -1))
+
+    with xr.set_options(keep_attrs=True):
+        da["z"] = obj.z * -1
+    expected = -1 * obj.differentiate("z", 2)
+    actual = obj.cf.differentiate("z", 2, positive_upward=True)
+    assert_identical(expected, actual)
+
+    obj = obj.isel(z=slice(None, None, -1))
+    expected = -1 * obj.differentiate("z", 2)
+    actual = obj.cf.differentiate("z", 2, positive_upward=True)
+    assert_identical(expected, actual)
+
+    del obj.z.attrs["positive"]
+    with pytest.raises(ValueError):
+        obj.cf.differentiate("z", positive_upward=True)
+
+    obj.z.attrs["positive"] = "zzz"
+    with pytest.raises(ValueError):
+        obj.cf.differentiate("z", positive_upward=True)

doc/api.rst

@@ -45,6 +45,7 @@ Methods
 
     DataArray.cf.__getitem__
     DataArray.cf.__repr__
+    DataArray.cf.differentiate
     DataArray.cf.guess_coord_axis
     DataArray.cf.keys
     DataArray.cf.rename_like
@@ -80,6 +81,7 @@ Methods
     Dataset.cf.add_bounds
     Dataset.cf.bounds_to_vertices
     Dataset.cf.decode_vertical_coords
+    Dataset.cf.differentiate
     Dataset.cf.get_bounds
     Dataset.cf.get_bounds_dim_name
     Dataset.cf.guess_coord_axis

doc/whats-new.rst

@@ -3,6 +3,12 @@
 What's New
 ----------
 
+v0.5.2 (unreleased)
+===================
+
+- :py:meth:`DataArray.cf.differentiate` and :py:meth:`Dataset.cf.differentiate` can optionally correct
+  sign of the derivative by interpreting the ``"positive"`` attribute. By `Deepak Cherian`_.
+
 v0.5.1 (Feb 24, 2021)
 =====================