ENH: pct change for Series and DataFrame #1271

Author: Chang She

pandas/core/generic.py

@@ -367,6 +367,33 @@ def tshift(self, periods=1, freq=None, **kwds):
 
         return self.shift(periods, freq, **kwds)
 
+    def pct_change(self, periods=1, fill_method='pad', limit=None, freq=None,
+                   **kwds):
+        """
+        Percent change over given number of periods
+
+        Parameters
+        ----------
+        periods : int, default 1
+            Periods to shift for forming percent change
+        fill_method : str, default 'pad'
+            How to handle NAs before computing percent changes
+        limit : int, default None
+            The number of consecutive NAs to fill before stopping
+        freq : DateOffset, timedelta, or offset alias string, optional
+            Increment to use from time series API (e.g. 'M' or BDay())
+
+        Returns
+        -------
+        chg : Series or DataFrame
+        """
+        if fill_method is None:
+            data = self
+        else:
+            data = self.fillna(method=fill_method, limit=limit)
+        rs = data / data.shift(periods=periods, freq=freq, **kwds) - 1
+        return rs
+
 
 class NDFrame(PandasObject):
     """

pandas/core/series.py

@@ -2354,7 +2354,7 @@ def shift(self, periods=1, freq=None, **kwds):
         ----------
         periods : int
             Number of periods to move, can be positive or negative
-        freq : DateOffset, timedelta, or time rule string, optional
+        freq : DateOffset, timedelta, or offset alias string, optional
             Increment to use from datetools module or time rule (e.g. 'EOM')
 
         Returns

pandas/tests/test_frame.py

@@ -4116,6 +4116,23 @@ def test_diff(self):
         assert_series_equal(the_diff['A'],
                             self.tsframe['A'] - self.tsframe['A'].shift(1))
 
+    def test_pct_change(self):
+        rs = self.tsframe.pct_change(fill_method=None)
+        assert_frame_equal(rs, self.tsframe / self.tsframe.shift(1) - 1)
+
+        rs = self.tsframe.pct_change(2)
+        filled = self.tsframe.fillna(method='pad')
+        assert_frame_equal(rs, filled / filled.shift(2) - 1)
+
+        rs = self.tsframe.pct_change(fill_method='bfill', limit=1)
+        filled = self.tsframe.fillna(method='bfill', limit=1)
+        assert_frame_equal(rs, filled / filled.shift(1) - 1)
+
+        rs = self.tsframe.pct_change(freq='M')
+        filled = self.tsframe.fillna(method='pad')
+        assert_frame_equal(rs, filled / filled.shift(freq='M') - 1)
+
+
     def test_shift(self):
         # naive shift
         shiftedFrame = self.tsframe.shift(5)

pandas/tests/test_series.py

@@ -2606,6 +2606,22 @@ def test_diff(self):
         # Just run the function
         self.ts.diff()
 
+    def test_pct_change(self):
+        rs = self.ts.pct_change(fill_method=None)
+        assert_series_equal(rs, self.ts / self.ts.shift(1) - 1)
+
+        rs = self.ts.pct_change(2)
+        filled = self.ts.fillna(method='pad')
+        assert_series_equal(rs, filled / filled.shift(2) - 1)
+
+        rs = self.ts.pct_change(fill_method='bfill', limit=1)
+        filled = self.ts.fillna(method='bfill', limit=1)
+        assert_series_equal(rs, filled / filled.shift(1) - 1)
+
+        rs = self.ts.pct_change(freq='M')
+        filled = self.ts.fillna(method='pad')
+        assert_series_equal(rs, filled / filled.shift(freq='M') - 1)
+
     def test_autocorr(self):
         # Just run the function
         self.ts.autocorr()