Docstring shift

pandas/core/generic.py

@@ -8012,12 +8012,12 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
                           errors=errors)
 
     _shared_docs['shift'] = ("""
-        Shift index by desired number of periods with an optional time freq
+        Shift index by desired number of periods with an optional time freq.
 
         Parameters
         ----------
         periods : int
-            Number of periods to move, can be positive or negative
+            Number of periods to move, can be positive or negative.
         freq : DateOffset, timedelta, or time rule string, optional
             Increment to use from the tseries module or time rule (e.g. 'EOM').
             See Notes.
@@ -8029,6 +8029,91 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None,
         is not realigned. That is, use freq if you would like to extend the
         index when shifting and preserve the original data.
 
+        Examples
+        --------
+
+        >>> df = pd.DataFrame({'group': ['A', 'A', 'A', 'B', 'B', 'B'],
+        ...                    'myvalue': [1, 2, 3, 4, 5, 6]},
+        ...                     index=pd.DatetimeIndex(['2016-06-06',
+        ...                                             '2016-06-08',
+        ...                                             '2016-06-09',
+        ...                                             '2016-06-10',
+        ...                                             '2016-06-12',
+        ...                                             '2016-06-13'],
+        ...                                            name='mydate'))
+
+        >>> df
+                    group	myvalue
+        mydate
+        2016-06-06	A	1
+        2016-06-08	A	2
+        2016-06-09	A	3
+        2016-06-10	B	4
+        2016-06-12	B	5
+        2016-06-13	B	6
+
+        For the groups compute the difference between current `myvalue` and
+        `myvalue` shifted forward by 1 day.
+
+        If `myvalue` is shifted then the values will simply move down.
+
+        >>> df.myvalue.shift(1)
+        mydate
+        2016-06-06    NaN
+        2016-06-08    1.0
+        2016-06-09    2.0
+        2016-06-10    3.0
+        2016-06-12    4.0
+        2016-06-13    5.0
+        Name: myvalue, dtype: float64
+
+        We only want to shift `myvalue` forward by one day before computing
+        the difference. We can do this by reindexing and filling the groups
+        first
+
+        >>> date_range = pd.date_range(df.index.min(), df.index.max())
+        >>> df = df.reindex(date_range)
+        >>> df['group'] = df['group'].ffill()
+        >>> df
+                     group  myvalue
+        2016-06-06     A      1.0
+        2016-06-07     A      NaN
+        2016-06-08     A      2.0
+        2016-06-09     A      3.0
+        2016-06-10     B      4.0
+        2016-06-11     B      NaN
+        2016-06-12     B      5.0
+        2016-06-13     B      6.0
+
+        After considering the grouping we can calculate the difference
+        as follows
+
+        >>> result = df['myvalue'] - df.groupby('group')['myvalue'].shift(1)
+        >>> result
+        2016-06-06    NaN
+        2016-06-07    NaN
+        2016-06-08    NaN
+        2016-06-09    1.0
+        2016-06-10    NaN
+        2016-06-11    NaN
+        2016-06-12    NaN
+        2016-06-13    1.0
+        Freq: D, Name: myvalue, dtype: float64
+
+        Concatenate result as a column named `delta` to the original data
+
+        >>> result.name = 'delta'
+        >>> pd.concat([df, result], axis=1)
+                   group  myvalue	delta
+        2016-06-06	 A	   1.0	     NaN
+        2016-06-07	 A	   NaN	     NaN
+        2016-06-08	 A	   2.0	     NaN
+        2016-06-09	 A	   3.0	     1.0
+        2016-06-10	 B	   4.0	     NaN
+        2016-06-11	 B	   NaN	     NaN
+        2016-06-12	 B	   5.0	     NaN
+        2016-06-13	 B	   6.0	     1.0
+
         Returns
         -------
         shifted : %(klass)s