Fix pydata#1040: diff dim argument should be optional

* {Dataset,DataArray}.diff dim argument defaults to last dimension

* add test cases

* add changelog

Author: smartass101

doc/whats-new.rst

@@ -137,6 +137,11 @@ Bug fixes
 - Fixed sub-optimal performance in certain operations with object arrays (:issue:`1121`).
   By `Yves Delley <https://github.com/burnpanck>`_.
 
+- Fixed default dim argument in ``.diff()`` methods to be truly optional (as in
+  docstring), defaults to last dimension (convenient for 1D arrays and
+  consistent with ``diff`` in numpy (:issue:`1040`).
+  By `Ondřej Grover <https://github.com/smartass101>`_.
+
 .. _whats-new.0.8.2:
 
 v0.8.2 (18 August 2016)

xarray/core/dataarray.py

@@ -1460,13 +1460,14 @@ def _title_for_slice(self, truncate=50):
 
         return title
 
-    def diff(self, dim, n=1, label='upper'):
+    def diff(self, dim=None, n=1, label='upper'):
         """Calculate the n-th order discrete difference along given axis.
 
         Parameters
         ----------
         dim : str, optional
-            Dimension over which to calculate the finite difference.
+            Dimension over which to calculate the finite difference. Defaults
+            to last dimension (like in ``diff`` in numpy).
         n : int, optional
             The number of times values are differenced.
         label : str, optional

xarray/core/dataset.py

@@ -2111,13 +2111,14 @@ def _copy_attrs_from(self, other):
         for v in other.variables:
             self.variables[v].attrs = other.variables[v].attrs
 
-    def diff(self, dim, n=1, label='upper'):
+    def diff(self, dim=None, n=1, label='upper'):
         """Calculate the n-th order discrete difference along given axis.
 
         Parameters
         ----------
         dim : str, optional
-            Dimension over which to calculate the finite difference.
+            Dimension over which to calculate the finite difference. Defaults
+            to last dimension (like in ``diff`` in numpy).
         n : int, optional
             The number of times values are differenced.
         label : str, optional
@@ -2156,6 +2157,10 @@ def diff(self, dim, n=1, label='upper'):
             raise ValueError('order `n` must be non-negative but got {0}'
                              ''.format(n))
 
+        # get default last dim if not specified
+        if dim is None:
+            dim = self.dims[-1]
+
         # prepare slices
         kwargs_start = {dim: slice(None, -1)}
         kwargs_end = {dim: slice(1, None)}

xarray/test/test_dataarray.py

@@ -2175,6 +2175,14 @@ def test_dataarray_diff_n1(self):
                              ['x', 'y'])
         self.assertDataArrayEqual(expected, actual)
 
+    def test_dataarray_diff_default_dim(self):
+        da = self.ds['foo']
+        actual = da.diff()
+        expected = DataArray(np.diff(da.values, axis=1),
+                             [da['x'].values, da['y'].values[1:]],
+                             ['x', 'y'])
+        self.assertDataArrayEqual(expected, actual)
+
     def test_coordinate_diff(self):
         # regression test for GH634
         arr = DataArray(range(0, 20, 2), dims=['lon'], coords=[range(10)])

xarray/test/test_dataset.py

@@ -2878,6 +2878,13 @@ def test_dataset_diff_exception_label_str(self):
         with self.assertRaisesRegexp(ValueError, '\'label\' argument has to'):
             ds.diff('dim2', label='raise_me')
 
+    def test_dataset_diff_default_dim(self):
+        ds = Dataset({'foo': ('x', [5, 5, 6, 6])})
+        actual = ds.diff()
+        expected = Dataset({'foo': ('x', [0, 1, 0])})
+        expected.coords['x'].values = [1, 2, 3]
+        self.assertDatasetEqual(expected, actual)
+
     def test_shift(self):
         coords = {'bar': ('x', list('abc')), 'x': [-4, 3, 2]}
         attrs = {'meta': 'data'}