From f68b9afba85c018ed08a32b9a96ab74a342b09ef Mon Sep 17 00:00:00 2001 From: Simone Basso Date: Sat, 10 Mar 2018 13:02:18 +0100 Subject: [PATCH 1/2] DOC: Improved the docstring of pandas.Series.truncate --- pandas/core/generic.py | 26 +++++++++++++++----------- 1 file changed, 15 insertions(+), 11 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a893b2ba1a189..44b997cf0766b 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -6888,29 +6888,33 @@ def tshift(self, periods=1, freq=None, axis=0): def truncate(self, before=None, after=None, axis=None, copy=True): """ - Truncates a sorted DataFrame/Series before and/or after some - particular index value. If the axis contains only datetime values, + Truncate a DataFrame/Series before/after some index value. + + If the axis contains only datetime values, before/after parameters are converted to datetime values. Parameters ---------- before : date, string, int - Truncate all rows before this index value + Truncate all rows before this index value. after : date, string, int - Truncate all rows after this index value + Truncate all rows after this index value. axis : {0 or 'index', 1 or 'columns'} - - * 0 or 'index': apply truncation to rows - * 1 or 'columns': apply truncation to columns - Default is stat axis for given data type (0 for Series and - DataFrames, 1 for Panels) + DataFrames). copy : boolean, default is True, - return a copy of the truncated section + Return a copy of the truncated section. Returns ------- - truncated : type of caller + type of caller + The truncated DataFrame/Series. + + See Also + -------- + DataFrame.truncate : Truncate a DataFrame before/after some index + value. + Series.truncate : Truncate a Series before/after some index value. Examples -------- From 1058daece0b9265368cf82e4322af528804a228f Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Thu, 15 Mar 2018 16:26:25 -0500 Subject: [PATCH 2/2] Updated [ci skip] * reword summaries * standard `axis` * show df * added series * reword datetime coercion [ci skip] --- pandas/core/generic.py | 90 +++++++++++++++++++++++++++++++----------- 1 file changed, 67 insertions(+), 23 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 44b997cf0766b..c056d160e91bf 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -6888,10 +6888,10 @@ def tshift(self, periods=1, freq=None, axis=0): def truncate(self, before=None, after=None, axis=None, copy=True): """ - Truncate a DataFrame/Series before/after some index value. + Truncate a Series or DataFrame before and after some index value. - If the axis contains only datetime values, - before/after parameters are converted to datetime values. + This is a useful shorthand for boolean indexing based on index + values above or below certain thresholds. Parameters ---------- @@ -6899,22 +6899,26 @@ def truncate(self, before=None, after=None, axis=None, copy=True): Truncate all rows before this index value. after : date, string, int Truncate all rows after this index value. - axis : {0 or 'index', 1 or 'columns'} - Default is stat axis for given data type (0 for Series and - DataFrames). + axis : {0 or 'index', 1 or 'columns'}, optional + Axis to truncate. Truncates the index (rows) by default. copy : boolean, default is True, Return a copy of the truncated section. Returns ------- type of caller - The truncated DataFrame/Series. + The truncated Series or DataFrame. See Also -------- - DataFrame.truncate : Truncate a DataFrame before/after some index - value. - Series.truncate : Truncate a Series before/after some index value. + DataFrame.loc : Select a subset of a DataFrame by label. + DataFrame.iloc : Select a subset of a DataFrame by position. + + Notes + ----- + If the index being truncated contains only datetime values, + `before` and `after` may be specified as strings instead of + Timestamps. Examples -------- @@ -6922,28 +6926,63 @@ def truncate(self, before=None, after=None, axis=None, copy=True): ... 'B': ['f', 'g', 'h', 'i', 'j'], ... 'C': ['k', 'l', 'm', 'n', 'o']}, ... index=[1, 2, 3, 4, 5]) + >>> df + A B C + 1 a f k + 2 b g l + 3 c h m + 4 d i n + 5 e j o + >>> df.truncate(before=2, after=4) A B C 2 b g l 3 c h m 4 d i n - >>> df = pd.DataFrame({'A': [1, 2, 3, 4, 5], - ... 'B': [6, 7, 8, 9, 10], - ... 'C': [11, 12, 13, 14, 15]}, - ... index=['a', 'b', 'c', 'd', 'e']) - >>> df.truncate(before='b', after='d') - A B C - b 2 7 12 - c 3 8 13 - d 4 9 14 - The index values in ``truncate`` can be datetimes or string - dates. Note that ``truncate`` assumes a 0 value for any unspecified - date component in a ``DatetimeIndex`` in contrast to slicing which - returns any partially matching dates. + The columns of a DataFrame can be truncated. + + >>> df.truncate(before="A", after="B", axis="columns") + A B + 1 a f + 2 b g + 3 c h + 4 d i + 5 e j + + For Series, only rows can be truncated. + + >>> df['A'].truncate(before=2, after=4) + 2 b + 3 c + 4 d + Name: A, dtype: object + The index values in ``truncate`` can be datetimes or string + dates. >>> dates = pd.date_range('2016-01-01', '2016-02-01', freq='s') >>> df = pd.DataFrame(index=dates, data={'A': 1}) + >>> df.tail() + A + 2016-01-31 23:59:56 1 + 2016-01-31 23:59:57 1 + 2016-01-31 23:59:58 1 + 2016-01-31 23:59:59 1 + 2016-02-01 00:00:00 1 + + >>> df.truncate(before=pd.Timestamp('2016-01-05'), + ... after=pd.Timestamp('2016-01-10')).tail() + A + 2016-01-09 23:59:56 1 + 2016-01-09 23:59:57 1 + 2016-01-09 23:59:58 1 + 2016-01-09 23:59:59 1 + 2016-01-10 00:00:00 1 + + Because the index is a DatetimeIndex containing only dates, we can + specify `before` and `after` as strings. They will be coerced to + Timestamps before truncation. + >>> df.truncate('2016-01-05', '2016-01-10').tail() A 2016-01-09 23:59:56 1 @@ -6951,6 +6990,11 @@ def truncate(self, before=None, after=None, axis=None, copy=True): 2016-01-09 23:59:58 1 2016-01-09 23:59:59 1 2016-01-10 00:00:00 1 + + Note that ``truncate`` assumes a 0 value for any unspecified time + component (midnight). This differs from partial string slicing, which + returns any partially matching dates. + >>> df.loc['2016-01-05':'2016-01-10', :].tail() A 2016-01-10 23:59:55 1