Merge pull request #6928 from TomAugspurger/panel_shift_kwarg

API/DEPR: Match Panel.shift()'s signature to generic

Author: Tom Augspurger

doc/source/release.rst

@@ -201,6 +201,11 @@ Deprecations
 - Indexers will warn ``FutureWarning`` when used with a scalar indexer and
   a non-floating point Index (:issue:`4892`)
 
+- :meth:`Panel.shift` now has a function signature that matches :meth:`DataFrame.shift`.
+  The old positional argument ``lags`` has been changed to a keyword argument
+  ``periods`` with a default value of 1. A ``FutureWarning`` is raised if the
+  old argument ``lags`` is used by name. (:issue:`6910`)
+
 Prior Version Deprecations/Changes
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

doc/source/v0.14.0.txt

@@ -416,6 +416,11 @@ Deprecations
      In [4]: Series(1,np.arange(5.))[3.0]
      Out[4]: 1
 
+- :meth:`Panel.shift` now has a function signature that matches :meth:`DataFrame.shift`.
+  The old positional argument ``lags`` has been changed to a keyword argument
+  ``periods`` with a default value of 1. A ``FutureWarning`` is raised if the
+  old argument ``lags`` is used by name. (:issue:`6910`)
+
 .. _whatsnew_0140.enhancements:
 
 Enhancements

pandas/core/generic.py

@@ -3489,7 +3489,8 @@ def pct_change(self, periods=1, fill_method='pad', limit=None, freq=None,
         else:
             data = self.fillna(method=fill_method, limit=limit)
 
-        rs = data.div(data.shift(periods, freq=freq, axis=axis, **kwds)) - 1
+        rs = (data.div(data.shift(periods=periods, freq=freq,
+                                  axis=axis, **kwds)) - 1)
         if freq is None:
             mask = com.isnull(_values_from_object(self))
             np.putmask(rs.values, mask, np.nan)

pandas/core/panel.py

@@ -22,7 +22,8 @@
 from pandas.core.generic import NDFrame, _shared_docs
 from pandas.tools.util import cartesian_product
 from pandas import compat
-from pandas.util.decorators import deprecate, Appender, Substitution
+from pandas.util.decorators import (deprecate, Appender, Substitution,
+                                    deprecate_kwarg)
 import pandas.core.common as com
 import pandas.core.ops as ops
 import pandas.core.nanops as nanops
@@ -1150,7 +1151,8 @@ def count(self, axis='major'):
 
         return self._wrap_result(result, axis)
 
-    def shift(self, lags, freq=None, axis='major'):
+    @deprecate_kwarg(old_arg_name='lags', new_arg_name='periods')
+    def shift(self, periods=1, freq=None, axis='major'):
         """
         Shift major or minor axis by specified number of leads/lags.
 
@@ -1164,12 +1166,12 @@ def shift(self, lags, freq=None, axis='major'):
         shifted : Panel
         """
         if freq:
-            return self.tshift(lags, freq, axis=axis)
+            return self.tshift(periods, freq, axis=axis)
 
         if axis == 'items':
             raise ValueError('Invalid axis')
 
-        return super(Panel, self).shift(lags, freq=freq, axis=axis)
+        return super(Panel, self).shift(periods, freq=freq, axis=axis)
 
     def tshift(self, periods=1, freq=None, axis='major', **kwds):
         return super(Panel, self).tshift(periods, freq, axis, **kwds)

pandas/tests/test_panel.py

@@ -824,6 +824,20 @@ def setUp(self):
         self.panel.minor_axis.name = None
         self.panel.items.name = None
 
+    def test_panel_warnings(self):
+        with tm.assert_produces_warning(FutureWarning):
+            shifted1 = self.panel.shift(lags=1)
+
+        with tm.assert_produces_warning(False):
+            shifted2 = self.panel.shift(periods=1)
+
+        tm.assert_panel_equal(shifted1, shifted2)
+
+        with tm.assert_produces_warning(False):
+            shifted3 = self.panel.shift()
+
+        tm.assert_panel_equal(shifted1, shifted3)
+
     def test_constructor(self):
         # with BlockManager
         wp = Panel(self.panel._data)