Docstring shift

pandas/core/generic.py

@@ -7793,12 +7793,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.
@@ -7810,6 +7810,86 @@ 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
+        --------
+        Compute the difference between a column in a dataframe
+        with grouped data, and its shifted version.
+
+        >>> data = pd.DataFrame({'myvalue': [1, 2, 3, 4, 5, 6],
+        ...                      'group': ['A', 'A', 'A', 'B', 'B', 'B']},
+        ...                     index=pd.DatetimeIndex(['2016-06-06',
+        ...                                             '2016-06-08',
+        ...                                             '2016-06-09',
+        ...                                             '2016-06-10',
+        ...                                             '2016-06-12',
+        ...                                             '2016-06-13'],
+        ...                                            name='mydate'))
+
+        >>> data
+                    myvalue group
+        mydate
+        2016-06-06        1     A
+        2016-06-08        2     A
+        2016-06-09        3     A
+        2016-06-10        4     B
+        2016-06-12        5     B
+        2016-06-13        6     B
+
+        For the groups compute the difference between current `myvalue` and
+        `myvalue` shifted forward by 1 day.
+
+        If the dataframe is shifted without passing a freq argument than the
+        values simply move down
+
+        >>> data[data.group=='A'].myvalue.shift(1)
+        mydate
+        2016-06-06    NaN
+        2016-06-08    1.0
+        2016-06-09    2.0
+        Name: myvalue, dtype: float64
+
+        What we want however, is to shift myvalue forward by one day in order
+        to compute the difference.
+
+        >>> data[data.group=='A'].myvalue.shift(1, freq=pd.Timedelta('1 days'))
+        mydate
+        2016-06-07    1
+        2016-06-09    2
+        2016-06-10    3
+        Name: myvalue, dtype: int64
+
+        After considering the grouping we can calculate the difference
+        as follows
+
+        >>> result = data.groupby('group').myvalue.apply(
+        ...             lambda x: x - x.shift(1, pd.Timedelta('1 days')))
+        >>> result
+        group  mydate
+        A      2016-06-06    NaN
+               2016-06-07    NaN
+               2016-06-08    NaN
+               2016-06-09    1.0
+               2016-06-10    NaN
+        B      2016-06-10    NaN
+               2016-06-11    NaN
+               2016-06-12    NaN
+               2016-06-13    1.0
+               2016-06-14    NaN
+        Name: myvalue, dtype: float64
+
+        Merge result as a column named `delta` to the original data
+
+        >>> result.name = 'delta'
+        >>> pd.merge(data, result.to_frame(), on=['mydate', 'group'])
+                    myvalue group delta
+        mydate
+        2016-06-06        1     A    NaN
+        2016-06-08        2     A    NaN
+        2016-06-09        3     A    1.0
+        2016-06-10        4     B    NaN
+        2016-06-12        5     B    NaN
+        2016-06-13        6     B    1.0
+
         Returns
         -------
         shifted : %(klass)s