dim -> coord in DataArray.integrate

doc/whats-new.rst

@@ -27,6 +27,12 @@ Breaking changes
   (:pull:`3274`)
   By `Elliott Sales de Andrade <https://github.com/QuLogic>`_
 
+- New deprecations (behavior will be changed in xarray 0.17):
+  - ``dim`` argument to :py:meth:`DataArray.integrate` is being deprecated in
+    favour of a ``coord`` arg, for consistency with :py:meth:`Dataset.integrate`.
+    For now using ``dim`` issues a ``FutureWarning``.
+    By `Tom Nicholas <https://github.com/TomNicholas>`_.
+
 New Features
 ~~~~~~~~~~~~
 - Added :py:meth:`DataArray.polyfit` and :py:func:`xarray.polyval` for fitting polynomials. (:issue:`3349`)

xarray/core/dataarray.py

@@ -3188,17 +3188,20 @@ def differentiate(
         return self._from_temp_dataset(ds)
 
     def integrate(
-        self, dim: Union[Hashable, Sequence[Hashable]], datetime_unit: str = None
+        self,
+        coord: Union[Hashable, Sequence[Hashable]],
+        dim: Union[Hashable, Sequence[Hashable]] = None,
+        datetime_unit: str = None,
     ) -> "DataArray":
-        """ integrate the array with the trapezoidal rule.
+        """ Integrate along the given coordinate using the trapezoidal rule.
 
         .. note::
-            This feature is limited to simple cartesian geometry, i.e. dim
+            This feature is limited to simple cartesian geometry, i.e. coord
             must be one dimensional.
 
         Parameters
         ----------
-        dim: hashable, or a sequence of hashable
+        coord: hashable, or a sequence of hashable
             Coordinate(s) used for the integration.
         datetime_unit: str, optional
             Can be used to specify the unit if datetime coordinate is used.
@@ -3211,6 +3214,7 @@ def integrate(
 
         See also
         --------
+        Dataset.integrate
         numpy.trapz: corresponding numpy function
 
         Examples
@@ -3236,7 +3240,17 @@ def integrate(
         array([5.4, 6.6, 7.8])
         Dimensions without coordinates: y
         """
-        ds = self._to_temp_dataset().integrate(dim, datetime_unit)
+
+        if dim is not None:
+            coord = dim
+            msg = (
+                "The `dim` keyword argument to `DataArray.integrate` is "
+                "being replaced with `coord`, for consistency with "
+                "`Dataset.integrate`."
+            )
+            warnings.warn(msg, FutureWarning, stacklevel=2)
+
+        ds = self._to_temp_dataset().integrate(coord, datetime_unit)
         return self._from_temp_dataset(ds)
 
     def unify_chunks(self) -> "DataArray":

xarray/core/dataset.py

@@ -5436,16 +5436,18 @@ def differentiate(self, coord, edge_order=1, datetime_unit=None):
                 variables[k] = v
         return self._replace(variables)
 
-    def integrate(self, coord, datetime_unit=None):
-        """ integrate the array with the trapezoidal rule.
+    def integrate(
+        self, coord: Union[Hashable, Sequence[Hashable]], datetime_unit: str = None
+    ) -> "Dataset":
+        """ Integrate along the given coordinate using the trapezoidal rule.
 
         .. note::
             This feature is limited to simple cartesian geometry, i.e. coord
             must be one dimensional.
 
         Parameters
         ----------
-        coord: str, or a sequence of str
+        coord: hashable, or a sequence of hashable
             Coordinate(s) used for the integration.
         datetime_unit
             Can be specify the unit if datetime coordinate is used. One of

xarray/tests/test_dataset.py

@@ -6135,6 +6135,9 @@ def test_integrate(dask):
     with pytest.raises(ValueError):
         da.integrate("x2d")
 
+    with pytest.warns(FutureWarning):
+        da.integrate(dim="x")
+
 
 @pytest.mark.parametrize("dask", [True, False])
 @pytest.mark.parametrize("which_datetime", ["np", "cftime"])

xarray/tests/test_units.py

@@ -3473,7 +3473,7 @@ def test_stacking_reordering(self, func, dtype):
         (
             method("diff", dim="x"),
             method("differentiate", coord="x"),
-            method("integrate", dim="x"),
+            method("integrate", coord="x"),
             pytest.param(
                 method("quantile", q=[0.25, 0.75]),
                 marks=pytest.mark.xfail(reason="nanquantile not implemented"),