Add lag parameter to autocorrelation, default to lag-1 autocorrelation

so existing code will work unchanged (GH9339)

Author: omtinez

doc/source/whatsnew/v0.16.0.txt

@@ -104,6 +104,7 @@ Enhancements
 - Added ``Series.str.slice_replace()``, which previously raised NotImplementedError (:issue:`8888`)
 - Added ``Timestamp.to_datetime64()`` to complement ``Timedelta.to_timedelta64()`` (:issue:`9255`)
 - ``tseries.frequencies.to_offset()`` now accepts ``Timedelta`` as input (:issue:`9064`)
+- Lag parameter was added to the autocorrelation method of Series, defaults to lag-1 autocorrelation (:issue:`9192`)
 - ``Timedelta`` will now accept nanoseconds keyword in constructor (:issue:`9273`)
 - SQL code now safely escapes table and column names (:issue:`8986`)
 

pandas/core/series.py

@@ -1336,15 +1336,20 @@ def diff(self, periods=1):
         result = com.diff(_values_from_object(self), periods)
         return self._constructor(result, index=self.index).__finalize__(self)
 
-    def autocorr(self):
+    def autocorr(self, lag=1):
         """
-        Lag-1 autocorrelation
+        Lag-N autocorrelation
+
+        Parameters
+        ----------
+        lag : int, default 1
+            Number of lags to apply before performing autocorrelation.
 
         Returns
         -------
         autocorr : float
         """
-        return self.corr(self.shift(1))
+        return self.corr(self.shift(lag))
 
     def dot(self, other):
         """

pandas/tests/test_series.py

@@ -6323,7 +6323,30 @@ def test_pct_change_shift_over_nas(self):
 
     def test_autocorr(self):
         # Just run the function
-        self.ts.autocorr()
+        corr1 = self.ts.autocorr()
+        
+        # Now run it with the lag parameter
+        corr2 = self.ts.autocorr(lag=1)
+        
+        # corr() with lag needs Series of at least length 2
+        if len(self.ts) <= 2:
+            self.assertTrue(np.isnan(corr1))
+            self.assertTrue(np.isnan(corr2))
+        else:
+            self.assertEqual(corr1, corr2)
+        
+        # Choose a random lag between 1 and length of Series - 2
+        # and compare the result with the Series corr() function
+        n = 1 + np.random.randint(max(1, len(self.ts) - 2))
+        corr1 = self.ts.corr(self.ts.shift(n))
+        corr2 = self.ts.autocorr(lag=n)
+
+        # corr() with lag needs Series of at least length 2
+        if len(self.ts) <= 2:
+            self.assertTrue(np.isnan(corr1))
+            self.assertTrue(np.isnan(corr2))
+        else:
+            self.assertEqual(corr1, corr2)
 
     def test_first_last_valid(self):
         ts = self.ts.copy()