From 8854ee3f7482f36e7a42723c47cfd9a833eed379 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sat, 3 Nov 2018 06:27:17 +0000 Subject: [PATCH 1/4] Original PR changes to shift docstring --- pandas/core/generic.py | 92 +++++++++++++++++++++++++++++++++++++----- 1 file changed, 81 insertions(+), 11 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 6ca8f6731bbb8..565803b09e947 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8361,22 +8361,24 @@ 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`. + + When `freq` is not passed, shift the index without realigning the data. + If `freq` is passed (in this case, the index must be date or datetime, + or it will raises a `NotImplementedError`), the index will be + increased using the periods and the `freq`. Parameters ---------- periods : int - Number of periods to move, can be positive or negative. + Number of periods to shift; 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. - axis : %(axes_single_arg)s - - See Also - -------- - Index.shift : Shift values of Index. - DatetimeIndex.shift : Shift values of DatetimeIndex. - PeriodIndex.shift : Shift values of PeriodIndex. + If `freq` is specified then the index values are shifted but the + data is not realigned. That is, use `freq` if you would like to + extend the index when shifting and preserve the original data. + axis : {0 or ‘index’, 1 or ‘columns’, None}, default None + Shift direction. Notes ----- @@ -8386,7 +8388,75 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None, Returns ------- - shifted : %(klass)s + %(klass)s + Copy of input object, shifted. + + See Also + -------- + Index.shift : Shift values of Index. + DatetimeIndex.shift : Shift values of DatetimeIndex. + PeriodIndex.shift : Shift values of PeriodIndex. + tshift : Shift the time index, using the index’s frequency if + available. + + Examples + -------- + >>> df = pd.DataFrame({'Col1': [10, 20, 15, 30, 45], + ... 'Col2': [13, 23, 18, 33, 48], + ... 'Col3': [17, 27, 22, 37, 52]}) + + >>> df.shift(periods=3) + Col1 Col2 Col3 + 0 NaN NaN NaN + 1 NaN NaN NaN + 2 NaN NaN NaN + 3 10.0 13.0 17.0 + 4 20.0 23.0 27.0 + + >>> df.shift(periods=1, axis=1) + Col1 Col2 Col3 + 0 NaN 10.0 13.0 + 1 NaN 20.0 23.0 + 2 NaN 15.0 18.0 + 3 NaN 30.0 33.0 + 4 NaN 45.0 48.0 + + **freq parameter** + + When using the freq parameter with a :class:pandas.DateTimeIndex + the index values are shifted but the data is not realigned. + + >>> names = ['Joaquim', 'Maria', 'Emanuel', 'Jussara', 'Geraldo'] + >>> dates = pd.date_range(start='2018-03-05 11:15:00', + ... freq='5D', periods=5) + >>> df = pd.DataFrame(data={'names': names}, index=dates) + >>> df + names + 2018-03-05 11:15:00 Joaquim + 2018-03-10 11:15:00 Maria + 2018-03-15 11:15:00 Emanuel + 2018-03-20 11:15:00 Jussara + 2018-03-25 11:15:00 Geraldo + + Shift the index by 2 days (offset-alias 'D'). + + >>> df.shift(periods=2, freq='D') + names + 2018-03-07 11:15:00 Joaquim + 2018-03-12 11:15:00 Maria + 2018-03-17 11:15:00 Emanuel + 2018-03-22 11:15:00 Jussara + 2018-03-27 11:15:00 Geraldo + + Shift the index by 75 minutes (offset-alias 'min'). + + >>> df.shift(periods=75, freq='min') + names + 2018-03-05 12:30:00 Joaquim + 2018-03-10 12:30:00 Maria + 2018-03-15 12:30:00 Emanuel + 2018-03-20 12:30:00 Jussara + 2018-03-25 12:30:00 Geraldo """) @Appender(_shared_docs['shift'] % _shared_doc_kwargs) From 0e0970da84213769cd6f2c249beee30c4adbc57d Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sat, 3 Nov 2018 06:36:04 +0000 Subject: [PATCH 2/4] Minor fixes and removing some examples --- pandas/core/generic.py | 47 +++++------------------------------------- 1 file changed, 5 insertions(+), 42 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 565803b09e947..b9cb1272bfdd8 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8365,15 +8365,15 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None, When `freq` is not passed, shift the index without realigning the data. If `freq` is passed (in this case, the index must be date or datetime, - or it will raises a `NotImplementedError`), the index will be + or it will raise a `NotImplementedError`), the index will be increased using the periods and the `freq`. Parameters ---------- periods : int - Number of periods to shift; 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'). + Number of periods to shift. Can be positive or negative. + freq : DateOffset, timedelta, or str, optional + Offset to use from the tseries module or time rule (e.g. 'EOM'). If `freq` is specified then the index values are shifted but the data is not realigned. That is, use `freq` if you would like to extend the index when shifting and preserve the original data. @@ -8413,50 +8413,13 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None, 3 10.0 13.0 17.0 4 20.0 23.0 27.0 - >>> df.shift(periods=1, axis=1) + >>> df.shift(periods=1, axis='columns') Col1 Col2 Col3 0 NaN 10.0 13.0 1 NaN 20.0 23.0 2 NaN 15.0 18.0 3 NaN 30.0 33.0 4 NaN 45.0 48.0 - - **freq parameter** - - When using the freq parameter with a :class:pandas.DateTimeIndex - the index values are shifted but the data is not realigned. - - >>> names = ['Joaquim', 'Maria', 'Emanuel', 'Jussara', 'Geraldo'] - >>> dates = pd.date_range(start='2018-03-05 11:15:00', - ... freq='5D', periods=5) - >>> df = pd.DataFrame(data={'names': names}, index=dates) - >>> df - names - 2018-03-05 11:15:00 Joaquim - 2018-03-10 11:15:00 Maria - 2018-03-15 11:15:00 Emanuel - 2018-03-20 11:15:00 Jussara - 2018-03-25 11:15:00 Geraldo - - Shift the index by 2 days (offset-alias 'D'). - - >>> df.shift(periods=2, freq='D') - names - 2018-03-07 11:15:00 Joaquim - 2018-03-12 11:15:00 Maria - 2018-03-17 11:15:00 Emanuel - 2018-03-22 11:15:00 Jussara - 2018-03-27 11:15:00 Geraldo - - Shift the index by 75 minutes (offset-alias 'min'). - - >>> df.shift(periods=75, freq='min') - names - 2018-03-05 12:30:00 Joaquim - 2018-03-10 12:30:00 Maria - 2018-03-15 12:30:00 Emanuel - 2018-03-20 12:30:00 Jussara - 2018-03-25 12:30:00 Geraldo """) @Appender(_shared_docs['shift'] % _shared_doc_kwargs) From f6afea05b6ee4ed99212e9ea644be6c20185451e Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sun, 4 Nov 2018 04:31:25 +0000 Subject: [PATCH 3/4] Addressing comments from code review, and removing notes, as it's duplicate content with the freq param description --- pandas/core/generic.py | 10 ++-------- 1 file changed, 2 insertions(+), 8 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index b9cb1272bfdd8..0a0c15d589283 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8372,20 +8372,14 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None, ---------- periods : int Number of periods to shift. Can be positive or negative. - freq : DateOffset, timedelta, or str, optional + freq : DateOffset, tseries.offsets, timedelta, or str, optional Offset to use from the tseries module or time rule (e.g. 'EOM'). If `freq` is specified then the index values are shifted but the data is not realigned. That is, use `freq` if you would like to extend the index when shifting and preserve the original data. - axis : {0 or ‘index’, 1 or ‘columns’, None}, default None + axis : {0 or 'index', 1 or 'columns', None}, default None Shift direction. - Notes - ----- - If freq is specified then the index values are shifted but the data - is not realigned. That is, use freq if you would like to extend the - index when shifting and preserve the original data. - Returns ------- %(klass)s From 4d9c3c00089bb40236600583d4143392385efd04 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Sun, 4 Nov 2018 05:14:34 +0000 Subject: [PATCH 4/4] Fixing non-ascii quote --- pandas/core/generic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 0a0c15d589283..096abd4255779 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8390,7 +8390,7 @@ def mask(self, cond, other=np.nan, inplace=False, axis=None, level=None, Index.shift : Shift values of Index. DatetimeIndex.shift : Shift values of DatetimeIndex. PeriodIndex.shift : Shift values of PeriodIndex. - tshift : Shift the time index, using the index’s frequency if + tshift : Shift the time index, using the index's frequency if available. Examples