From a83acff00c496b11450471059df894624dc5acaa Mon Sep 17 00:00:00 2001 From: Arpad Fulop Date: Mon, 5 Mar 2018 17:31:56 +0100 Subject: [PATCH 1/3] DOC: updating docstring of Index.shift --- pandas/core/indexes/base.py | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 0813c12d573d5..5143c40cb83d1 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2211,13 +2211,32 @@ def sortlevel(self, level=None, ascending=True, sort_remaining=None): return self.sort_values(return_indexer=True, ascending=ascending) def shift(self, periods=1, freq=None): - """ - Shift Index containing datetime objects by input number of periods and - DateOffset + """Shift index by desired number of time frequency increments. - Returns - ------- - shifted : Index + This method is for shifting the values of datetime-like indexes + by a specified time increment a given number of times. + + Parameters + ---------- + periods : int + Number of periods (or increments) to shift by, + can be positive or negative (default is 1). + freq : pandas.DateOffset, pandas.Timedelta or string + Frequency increment to shift by (default is None). + Offset aliases are valid strings, e.g., 'EOM'. + + See Also + -------- + DatetimeIndex.shift : an implementation of shift. + PeriodIndex.shift : an implementation of shift. + TimedeltaIndex.shift : an implementation of shift. + + Notes + ----- + Must be overridden in child classes. + h + Implemented in datetime-like index classes, + e.g., DatetimeIndex, PeriodIndex and TimedeltaIndex. """ raise NotImplementedError("Not supported for type %s" % type(self).__name__) From 1523ba8ec245f98f0a1df9c24df988d133ce1c03 Mon Sep 17 00:00:00 2001 From: Arpad Fulop Date: Tue, 6 Mar 2018 14:54:38 +0100 Subject: [PATCH 2/3] Removing See Also section, adding Returns and Examples sections --- pandas/core/indexes/base.py | 35 ++++++++++++++++++++++++++--------- 1 file changed, 26 insertions(+), 9 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 5143c40cb83d1..12dfc84418237 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2223,20 +2223,37 @@ def shift(self, periods=1, freq=None): can be positive or negative (default is 1). freq : pandas.DateOffset, pandas.Timedelta or string Frequency increment to shift by (default is None). - Offset aliases are valid strings, e.g., 'EOM'. + If None, the index is shifted by its own `freq` attribute. + Offset aliases are valid strings, e.g., 'D', 'W', 'M' etc. - See Also + Returns + ------- + pandas.Index + shifted index + + Examples -------- - DatetimeIndex.shift : an implementation of shift. - PeriodIndex.shift : an implementation of shift. - TimedeltaIndex.shift : an implementation of shift. + >>> month_starts = pd.date_range('1/1/2011', periods=5, freq='MS') + + Shift by 10 days. + + >>> month_starts.shift(10, freq='D') + DatetimeIndex(['2011-01-11', '2011-02-11', '2011-03-11', '2011-04-11', + '2011-05-11'], + dtype='datetime64[ns]', freq=None) + + The default value of `freq` is the `freq` attribute of the index; + in this example it is 'MS' (month start). + + >>> month_starts.shift(10) + DatetimeIndex(['2011-11-01', '2011-12-01', '2012-01-01', '2012-02-01', + '2012-03-01'], + dtype='datetime64[ns]', freq='MS') Notes ----- - Must be overridden in child classes. - h - Implemented in datetime-like index classes, - e.g., DatetimeIndex, PeriodIndex and TimedeltaIndex. + This method is only implemented for datetime-like index classes, + i.e., DatetimeIndex, PeriodIndex and TimedeltaIndex. """ raise NotImplementedError("Not supported for type %s" % type(self).__name__) From ce8379fc0ae84ecd810707c5aeeaa039da8858a9 Mon Sep 17 00:00:00 2001 From: Arpad Fulop Date: Tue, 6 Mar 2018 17:42:29 +0100 Subject: [PATCH 3/3] Extending Examples section --- pandas/core/indexes/base.py | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 12dfc84418237..44a63029df0fc 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -2233,17 +2233,23 @@ def shift(self, periods=1, freq=None): Examples -------- + Put the first 5 month starts of 2011 into an index. + >>> month_starts = pd.date_range('1/1/2011', periods=5, freq='MS') + >>> month_starts + DatetimeIndex(['2011-01-01', '2011-02-01', '2011-03-01', '2011-04-01', + '2011-05-01'], + dtype='datetime64[ns]', freq='MS') - Shift by 10 days. + Shift the index by 10 days. >>> month_starts.shift(10, freq='D') DatetimeIndex(['2011-01-11', '2011-02-11', '2011-03-11', '2011-04-11', '2011-05-11'], dtype='datetime64[ns]', freq=None) - The default value of `freq` is the `freq` attribute of the index; - in this example it is 'MS' (month start). + The default value of `freq` is the `freq` attribute of the index, + which is 'MS' (month start) in this example. >>> month_starts.shift(10) DatetimeIndex(['2011-11-01', '2011-12-01', '2012-01-01', '2012-02-01',