From 2c2329640f110b1a8731865cc7537d613210a5d0 Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Tue, 16 Oct 2018 20:35:08 +0100 Subject: [PATCH 01/16] DOC: Remove some validation errors in resample (#22894) * First iteration over some validation errors on pandas.Series.resample. * Fix multi-line examples issue. --- 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 ba050bfc8db77..1b072b8499246 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7366,6 +7366,8 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, label=None, convention='start', kind=None, loffset=None, limit=None, base=0, on=None, level=None): """ + Resample a time series by changing the frequency of the index. + Convenience method for frequency conversion and resampling of time series. Object must have a datetime-like index (DatetimeIndex, PeriodIndex, or TimedeltaIndex), or pass datetime-like values @@ -7374,8 +7376,9 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, Parameters ---------- rule : string - the offset string or object representing target conversion + The offset string or object representing target conversion. axis : int, optional, default 0 + closed : {'right', 'left'} Which side of bin interval is closed. The default is 'left' for all frequency offsets except for 'M', 'A', 'Q', 'BM', @@ -7386,17 +7389,17 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 'BA', 'BQ', and 'W' which all have a default of 'right'. convention : {'start', 'end', 's', 'e'} For PeriodIndex only, controls whether to use the start or end of - `rule` - kind: {'timestamp', 'period'}, optional + `rule`. + kind : {'timestamp', 'period'} optional Pass 'timestamp' to convert the resulting index to a ``DateTimeIndex`` or 'period' to convert it to a ``PeriodIndex``. By default the input representation is retained. loffset : timedelta - Adjust the resampled time labels + Adjust the resampled time labels. base : int, default 0 For frequencies that evenly subdivide 1 day, the "origin" of the aggregated intervals. For example, for '5min' frequency, base could - range from 0 through 4. Defaults to 0 + range from 0 through 4. Defaults to 0. on : string, optional For a DataFrame, column to use instead of index for resampling. Column must be datetime-like. @@ -7522,9 +7525,10 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, For a Series with a PeriodIndex, the keyword `convention` can be used to control whether to use the start or end of `rule`. - >>> s = pd.Series([1, 2], index=pd.period_range('2012-01-01', - freq='A', - periods=2)) + >>> s = pd.Series([1, 2], index=pd.period_range( + ... '2012-01-01', + ... freq='A', + ... periods=2)) >>> s 2012 1 2013 2 @@ -7577,9 +7581,9 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, >>> time = pd.date_range('1/1/2000', periods=5, freq='T') >>> df2 = pd.DataFrame(data=10*[range(4)], - columns=['a', 'b', 'c', 'd'], - index=pd.MultiIndex.from_product([time, [1, 2]]) - ) + ... columns=['a', 'b', 'c', 'd'], + ... index=pd.MultiIndex.from_product([time, [1, 2]]) + ... ) >>> df2.resample('3T', level=0).sum() a b c d 2000-01-01 00:00:00 0 6 12 18 From 7940cbe56b48ef07c5f672b85161fa74768bcc5b Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Wed, 17 Oct 2018 11:51:14 +0100 Subject: [PATCH 02/16] DOC: Document deprecated parameters for resample (#22894) Not too sure they were deprecated from v0.18.0. Need to point this out in the PR. --- pandas/core/generic.py | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 1b072b8499246..bfe3513a2c82c 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7377,8 +7377,19 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, ---------- rule : string The offset string or object representing target conversion. + how : string + Method for down- or re-sampling, default to ‘mean’ for downsampling. + + .. deprecated:: 0.18.0 + The new syntax is .resample(...).mean(), or .resample(...).apply() axis : int, optional, default 0 - + Which index to use for up- or down-sampling. Must be ``DatetimeIndex``, + ``TimedeltaIndex`` or ``PeriodIndex``. + fill_method : string, default None + Filling method for upsampling. + + .. deprecated:: 0.18.0 + The new syntax is .resample(...).(), e.g. .resample(...).pad() closed : {'right', 'left'} Which side of bin interval is closed. The default is 'left' for all frequency offsets except for 'M', 'A', 'Q', 'BM', @@ -7396,6 +7407,10 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, By default the input representation is retained. loffset : timedelta Adjust the resampled time labels. + limit : int, default None + Maximum size gap when reindexing with ``fill_method``. + + .. deprecated:: 0.18.0 base : int, default 0 For frequencies that evenly subdivide 1 day, the "origin" of the aggregated intervals. For example, for '5min' frequency, base could From ff8009ecc38a530c36290fdb7e6b8aa6e7dfba8b Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Wed, 17 Oct 2018 11:54:09 +0100 Subject: [PATCH 03/16] DOC: Validate PEP-8 of fixed resample docstrings (#22894) --- pandas/core/generic.py | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index bfe3513a2c82c..0ef3dac9e3d14 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7378,18 +7378,20 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, rule : string The offset string or object representing target conversion. how : string - Method for down- or re-sampling, default to ‘mean’ for downsampling. + Method for down-/re-sampling, default to ‘mean’ for downsampling. .. deprecated:: 0.18.0 - The new syntax is .resample(...).mean(), or .resample(...).apply() + The new syntax is .resample(...).mean(), or + .resample(...).apply() axis : int, optional, default 0 - Which index to use for up- or down-sampling. Must be ``DatetimeIndex``, - ``TimedeltaIndex`` or ``PeriodIndex``. + Which index to use for up- or down-sampling. Must be + ``DatetimeIndex``, ``TimedeltaIndex`` or ``PeriodIndex``. fill_method : string, default None Filling method for upsampling. .. deprecated:: 0.18.0 - The new syntax is .resample(...).(), e.g. .resample(...).pad() + The new syntax is .resample(...).(), + e.g. .resample(...).pad() closed : {'right', 'left'} Which side of bin interval is closed. The default is 'left' for all frequency offsets except for 'M', 'A', 'Q', 'BM', From f71d48f954cb9fe35bf4cd8d478213513acd5f89 Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Wed, 17 Oct 2018 12:27:06 +0100 Subject: [PATCH 04/16] DOC: Improve inline code reST display (#22894) --- pandas/core/generic.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 0ef3dac9e3d14..00d5b66cef3bc 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7369,9 +7369,9 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, Resample a time series by changing the frequency of the index. Convenience method for frequency conversion and resampling of time - series. Object must have a datetime-like index (DatetimeIndex, - PeriodIndex, or TimedeltaIndex), or pass datetime-like values - to the on or level keyword. + series. Object must have a datetime-like index (``DatetimeIndex``, + ``PeriodIndex``, or ``TimedeltaIndex``), or pass datetime-like values + to the ``on`` or ``level`` keyword. Parameters ---------- @@ -7381,8 +7381,8 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, Method for down-/re-sampling, default to ‘mean’ for downsampling. .. deprecated:: 0.18.0 - The new syntax is .resample(...).mean(), or - .resample(...).apply() + The new syntax is ``.resample(...).mean()``, or + ``.resample(...).apply()`` axis : int, optional, default 0 Which index to use for up- or down-sampling. Must be ``DatetimeIndex``, ``TimedeltaIndex`` or ``PeriodIndex``. @@ -7390,8 +7390,8 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, Filling method for upsampling. .. deprecated:: 0.18.0 - The new syntax is .resample(...).(), - e.g. .resample(...).pad() + The new syntax is ``.resample(...).()``, + e.g. ``.resample(...).pad()`` closed : {'right', 'left'} Which side of bin interval is closed. The default is 'left' for all frequency offsets except for 'M', 'A', 'Q', 'BM', @@ -7401,8 +7401,8 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, for all frequency offsets except for 'M', 'A', 'Q', 'BM', 'BA', 'BQ', and 'W' which all have a default of 'right'. convention : {'start', 'end', 's', 'e'} - For PeriodIndex only, controls whether to use the start or end of - `rule`. + For ``PeriodIndex`` only, controls whether to use the start or + end of ``rule``. kind : {'timestamp', 'period'} optional Pass 'timestamp' to convert the resulting index to a ``DateTimeIndex`` or 'period' to convert it to a ``PeriodIndex``. @@ -7425,7 +7425,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, level : string or int, optional For a MultiIndex, level (name or number) to use for - resampling. Level must be datetime-like. + resampling. ``level`` must be datetime-like. .. versionadded:: 0.19.0 From 49fbd6bf9399438a1df48304044f6b28e1eddbab Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Wed, 17 Oct 2018 12:29:31 +0100 Subject: [PATCH 05/16] DOC: Simpler short summary (#22894) --- 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 00d5b66cef3bc..939938220cd52 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7366,7 +7366,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, label=None, convention='start', kind=None, loffset=None, limit=None, base=0, on=None, level=None): """ - Resample a time series by changing the frequency of the index. + Resample time-series data. Convenience method for frequency conversion and resampling of time series. Object must have a datetime-like index (``DatetimeIndex``, From b8f8b0efd0ccdc73ad3688a04eb5f1920e216c24 Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Sat, 27 Oct 2018 15:56:06 +0100 Subject: [PATCH 06/16] DOC: Address PR changes request: string->str, missing defaults, pep8 issues... (#22894) --- pandas/core/generic.py | 33 +++++++++++++++++---------------- 1 file changed, 17 insertions(+), 16 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 939938220cd52..08272a7d72401 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7375,39 +7375,40 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, Parameters ---------- - rule : string + rule : str The offset string or object representing target conversion. - how : string + how : str Method for down-/re-sampling, default to ‘mean’ for downsampling. .. deprecated:: 0.18.0 The new syntax is ``.resample(...).mean()``, or ``.resample(...).apply()`` axis : int, optional, default 0 - Which index to use for up- or down-sampling. Must be + Which axis to use for up- or down-sampling. For ``Series`` this + will default to 0, i.e. `along the rows`. Must be ``DatetimeIndex``, ``TimedeltaIndex`` or ``PeriodIndex``. - fill_method : string, default None + fill_method : str, default None Filling method for upsampling. .. deprecated:: 0.18.0 The new syntax is ``.resample(...).()``, e.g. ``.resample(...).pad()`` - closed : {'right', 'left'} + closed : {'right', 'left'}, default None Which side of bin interval is closed. The default is 'left' for all frequency offsets except for 'M', 'A', 'Q', 'BM', 'BA', 'BQ', and 'W' which all have a default of 'right'. - label : {'right', 'left'} + label : {'right', 'left'}, default None Which bin edge label to label bucket with. The default is 'left' for all frequency offsets except for 'M', 'A', 'Q', 'BM', 'BA', 'BQ', and 'W' which all have a default of 'right'. - convention : {'start', 'end', 's', 'e'} + convention : {'start', 'end', 's', 'e'}, default 'start' For ``PeriodIndex`` only, controls whether to use the start or end of ``rule``. - kind : {'timestamp', 'period'} optional + kind : {'timestamp', 'period'}, optional, default None Pass 'timestamp' to convert the resulting index to a ``DateTimeIndex`` or 'period' to convert it to a ``PeriodIndex``. By default the input representation is retained. - loffset : timedelta + loffset : timedelta, default None Adjust the resampled time labels. limit : int, default None Maximum size gap when reindexing with ``fill_method``. @@ -7417,13 +7418,13 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, For frequencies that evenly subdivide 1 day, the "origin" of the aggregated intervals. For example, for '5min' frequency, base could range from 0 through 4. Defaults to 0. - on : string, optional + on : str, optional For a DataFrame, column to use instead of index for resampling. Column must be datetime-like. .. versionadded:: 0.19.0 - level : string or int, optional + level : str or int, optional For a MultiIndex, level (name or number) to use for resampling. ``level`` must be datetime-like. @@ -7531,7 +7532,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, Pass a custom function via ``apply`` >>> def custom_resampler(array_like): - ... return np.sum(array_like)+5 + ... return np.sum(array_like) + 5 >>> series.resample('3T').apply(custom_resampler) 2000-01-01 00:00:00 8 @@ -7542,8 +7543,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, For a Series with a PeriodIndex, the keyword `convention` can be used to control whether to use the start or end of `rule`. - >>> s = pd.Series([1, 2], index=pd.period_range( - ... '2012-01-01', + >>> s = pd.Series([1, 2], index=pd.period_range('2012-01-01', ... freq='A', ... periods=2)) >>> s @@ -7584,7 +7584,8 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, For DataFrame objects, the keyword ``on`` can be used to specify the column instead of the index for resampling. - >>> df = pd.DataFrame(data=9*[range(4)], columns=['a', 'b', 'c', 'd']) + >>> df = pd.DataFrame(data=9 * [range(4)], + ... columns=['a', 'b', 'c', 'd']) >>> df['time'] = pd.date_range('1/1/2000', periods=9, freq='T') >>> df.resample('3T', on='time').sum() a b c d @@ -7597,7 +7598,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, specify on level the resampling needs to take place. >>> time = pd.date_range('1/1/2000', periods=5, freq='T') - >>> df2 = pd.DataFrame(data=10*[range(4)], + >>> df2 = pd.DataFrame(data=10 * [range(4)], ... columns=['a', 'b', 'c', 'd'], ... index=pd.MultiIndex.from_product([time, [1, 2]]) ... ) From ad1cadab2cd4440f5d02e3e4be9f0bc6ab3f85e5 Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Wed, 7 Nov 2018 12:56:33 +0000 Subject: [PATCH 07/16] DOC: Address PR comments (I) axis type and defaults, improve resample convention examples. (#22894) --- pandas/core/generic.py | 68 +++++++++++++++++++++++------------------- 1 file changed, 38 insertions(+), 30 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 08272a7d72401..9f21198f72b64 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7383,7 +7383,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, .. deprecated:: 0.18.0 The new syntax is ``.resample(...).mean()``, or ``.resample(...).apply()`` - axis : int, optional, default 0 + axis : {0 or 'index'}, default 0 Which axis to use for up- or down-sampling. For ``Series`` this will default to 0, i.e. `along the rows`. Must be ``DatetimeIndex``, ``TimedeltaIndex`` or ``PeriodIndex``. @@ -7543,6 +7543,9 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, For a Series with a PeriodIndex, the keyword `convention` can be used to control whether to use the start or end of `rule`. + Resample a year by quarter using 'start' `convention`. Values are + assigned to the first quarter of the period. + >>> s = pd.Series([1, 2], index=pd.period_range('2012-01-01', ... freq='A', ... periods=2)) @@ -7550,35 +7553,40 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2012 1 2013 2 Freq: A-DEC, dtype: int64 - - Resample by month using 'start' `convention`. Values are assigned to - the first month of the period. - - >>> s.resample('M', convention='start').asfreq().head() - 2012-01 1.0 - 2012-02 NaN - 2012-03 NaN - 2012-04 NaN - 2012-05 NaN - Freq: M, dtype: float64 - - Resample by month using 'end' `convention`. Values are assigned to - the last month of the period. - - >>> s.resample('M', convention='end').asfreq() - 2012-12 1.0 - 2013-01 NaN - 2013-02 NaN - 2013-03 NaN - 2013-04 NaN - 2013-05 NaN - 2013-06 NaN - 2013-07 NaN - 2013-08 NaN - 2013-09 NaN - 2013-10 NaN - 2013-11 NaN - 2013-12 2.0 + >>> s.resample('Q', convention='start').asfreq() + 2012Q1 1.0 + 2012Q2 NaN + 2012Q3 NaN + 2012Q4 NaN + 2013Q1 2.0 + 2013Q2 NaN + 2013Q3 NaN + 2013Q4 NaN + Freq: Q-DEC, dtype: float64 + + Resample quarters by month using 'end' `convention`. Values are + assigned to the last month of the period. + + >>> q = pd.Series([1, 2, 3, 4], index=pd.period_range('2018-01-01', + ... freq='Q', + ... periods=4)) + >>> q + 2018Q1 1 + 2018Q2 2 + 2018Q3 3 + 2018Q4 4 + Freq: Q-DEC, dtype: int64 + >>> q.resample('M', convention='end').asfreq() + 2018-03 1.0 + 2018-04 NaN + 2018-05 NaN + 2018-06 2.0 + 2018-07 NaN + 2018-08 NaN + 2018-09 3.0 + 2018-10 NaN + 2018-11 NaN + 2018-12 4.0 Freq: M, dtype: float64 For DataFrame objects, the keyword ``on`` can be used to specify the From ceff696f7d25f094b2328252fd8bc47601b7ce5a Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Wed, 7 Nov 2018 13:18:12 +0000 Subject: [PATCH 08/16] DOC: Address PR comments (II) revamp example for the `on` parameter. (#22894) --- pandas/core/generic.py | 32 ++++++++++++++++++++++---------- 1 file changed, 22 insertions(+), 10 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 9f21198f72b64..0b1c78e2a3fcb 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7589,18 +7589,30 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2018-12 4.0 Freq: M, dtype: float64 - For DataFrame objects, the keyword ``on`` can be used to specify the + For DataFrame objects, the keyword `on` can be used to specify the column instead of the index for resampling. - >>> df = pd.DataFrame(data=9 * [range(4)], - ... columns=['a', 'b', 'c', 'd']) - >>> df['time'] = pd.date_range('1/1/2000', periods=9, freq='T') - >>> df.resample('3T', on='time').sum() - a b c d - time - 2000-01-01 00:00:00 0 3 6 9 - 2000-01-01 00:03:00 0 3 6 9 - 2000-01-01 00:06:00 0 3 6 9 + >>> d = dict({'price': [10, 11, 9, 13, 14, 18, 17, 19], + ... 'volume': [50, 60, 40, 100, 50, 100, 40, 50]}) + >>> df = pd.DataFrame(d) + >>> df['week_starting'] = pd.date_range('01/01/2018', + ... periods=8, + ... freq='W') + >>> df + price volume week_starting + 0 10 50 2018-01-07 + 1 11 60 2018-01-14 + 2 9 40 2018-01-21 + 3 13 100 2018-01-28 + 4 14 50 2018-02-04 + 5 18 100 2018-02-11 + 6 17 40 2018-02-18 + 7 19 50 2018-02-25 + >>> df.resample('M', on='week_starting').mean() + price volume + week_starting + 2018-01-31 10.75 62.5 + 2018-02-28 17.00 60.0 For a DataFrame with MultiIndex, the keyword ``level`` can be used to specify on level the resampling needs to take place. From 8cd9a892a23182c46bd52bf6cb51a5d028658e1e Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Wed, 7 Nov 2018 13:49:48 +0000 Subject: [PATCH 09/16] DOC: Address PR comments (III) revamp example for the `level` parameter and other cosmetical mods. (#22894) --- pandas/core/generic.py | 56 +++++++++++++++++++++++++++--------------- 1 file changed, 36 insertions(+), 20 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 0b1c78e2a3fcb..1222960de87f7 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7443,6 +7443,10 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, To learn more about the offset strings, please see `this link `__. + See Also + -------- + groupby : Group by mapping, function, label, or list of labels. + Examples -------- @@ -7540,10 +7544,10 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2000-01-01 00:06:00 26 Freq: 3T, dtype: int64 - For a Series with a PeriodIndex, the keyword `convention` can be + For a Series with a PeriodIndex, the keyword ``convention`` can be used to control whether to use the start or end of `rule`. - Resample a year by quarter using 'start' `convention`. Values are + Resample a year by quarter using 'start' ``convention``. Values are assigned to the first quarter of the period. >>> s = pd.Series([1, 2], index=pd.period_range('2012-01-01', @@ -7564,12 +7568,12 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2013Q4 NaN Freq: Q-DEC, dtype: float64 - Resample quarters by month using 'end' `convention`. Values are + Resample quarters by month using 'end' ``convention``. Values are assigned to the last month of the period. >>> q = pd.Series([1, 2, 3, 4], index=pd.period_range('2018-01-01', - ... freq='Q', - ... periods=4)) + ... freq='Q', + ... periods=4)) >>> q 2018Q1 1 2018Q2 2 @@ -7589,7 +7593,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2018-12 4.0 Freq: M, dtype: float64 - For DataFrame objects, the keyword `on` can be used to specify the + For DataFrame objects, the keyword ``on`` can be used to specify the column instead of the index for resampling. >>> d = dict({'price': [10, 11, 9, 13, 14, 18, 17, 19], @@ -7615,21 +7619,33 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2018-02-28 17.00 60.0 For a DataFrame with MultiIndex, the keyword ``level`` can be used to - specify on level the resampling needs to take place. - - >>> time = pd.date_range('1/1/2000', periods=5, freq='T') - >>> df2 = pd.DataFrame(data=10 * [range(4)], - ... columns=['a', 'b', 'c', 'd'], - ... index=pd.MultiIndex.from_product([time, [1, 2]]) - ... ) - >>> df2.resample('3T', level=0).sum() - a b c d - 2000-01-01 00:00:00 0 6 12 18 - 2000-01-01 00:03:00 0 4 8 12 + specify on which level the resampling needs to take place. - See also - -------- - groupby : Group by mapping, function, label, or list of labels. + >>> days = pd.date_range('1/1/2000', periods=4, freq='D') + >>> d2 = dict({'price': [10, 11, 9, 13, 14, 18, 17, 19], + ... 'volume': [50, 60, 40, 100, 50, 100, 40, 50]}) + >>> df2 = pd.DataFrame( + ... d2, + ... index=pd.MultiIndex.from_product( + ... [days, ['morning', 'afternoon']] + ... ) + ... ) + >>> df2 + price volume + 2000-01-01 morning 10 50 + afternoon 11 60 + 2000-01-02 morning 9 40 + afternoon 13 100 + 2000-01-03 morning 14 50 + afternoon 18 100 + 2000-01-04 morning 17 40 + afternoon 19 50 + >>> df2.resample('D', level=0).sum() + price volume + 2000-01-01 21 110 + 2000-01-02 22 140 + 2000-01-03 32 150 + 2000-01-04 36 90 """ from pandas.core.resample import (resample, _maybe_process_deprecations) From ce7886a96100f572634c7ddb3e0ebba53459ae9d Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Fri, 9 Nov 2018 12:15:09 +0000 Subject: [PATCH 10/16] Removing double space. --- 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 1222960de87f7..22828614df94f 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7369,7 +7369,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, Resample time-series data. Convenience method for frequency conversion and resampling of time - series. Object must have a datetime-like index (``DatetimeIndex``, + series. Object must have a datetime-like index (``DatetimeIndex``, ``PeriodIndex``, or ``TimedeltaIndex``), or pass datetime-like values to the ``on`` or ``level`` keyword. From abb2b582c5727bb4801efb6c8d58175adf549fb8 Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Fri, 9 Nov 2018 15:52:30 +0000 Subject: [PATCH 11/16] DOC: Address latest PR comments (#22894) --- pandas/core/generic.py | 36 +++++++++++++++++++----------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 22828614df94f..01b3d6bf67df3 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7369,9 +7369,9 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, Resample time-series data. Convenience method for frequency conversion and resampling of time - series. Object must have a datetime-like index (``DatetimeIndex``, - ``PeriodIndex``, or ``TimedeltaIndex``), or pass datetime-like values - to the ``on`` or ``level`` keyword. + series. Object must have a datetime-like index (`DatetimeIndex`, + `PeriodIndex`, or `TimedeltaIndex`), or pass datetime-like values + to the `on` or `level` keyword. Parameters ---------- @@ -7383,10 +7383,10 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, .. deprecated:: 0.18.0 The new syntax is ``.resample(...).mean()``, or ``.resample(...).apply()`` - axis : {0 or 'index'}, default 0 - Which axis to use for up- or down-sampling. For ``Series`` this - will default to 0, i.e. `along the rows`. Must be - ``DatetimeIndex``, ``TimedeltaIndex`` or ``PeriodIndex``. + axis : {0 or 'index', 1 or 'columns'}, default 0 + Which axis to use for up- or down-sampling. For `Series` this + will default to 0, i.e. along the rows. Must be + `DatetimeIndex`, `TimedeltaIndex` or `PeriodIndex`. fill_method : str, default None Filling method for upsampling. @@ -7402,16 +7402,16 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, for all frequency offsets except for 'M', 'A', 'Q', 'BM', 'BA', 'BQ', and 'W' which all have a default of 'right'. convention : {'start', 'end', 's', 'e'}, default 'start' - For ``PeriodIndex`` only, controls whether to use the start or - end of ``rule``. + For `PeriodIndex` only, controls whether to use the start or + end of `rule`. kind : {'timestamp', 'period'}, optional, default None Pass 'timestamp' to convert the resulting index to a - ``DateTimeIndex`` or 'period' to convert it to a ``PeriodIndex``. + `DateTimeIndex` or 'period' to convert it to a `PeriodIndex`. By default the input representation is retained. loffset : timedelta, default None Adjust the resampled time labels. limit : int, default None - Maximum size gap when reindexing with ``fill_method``. + Maximum size gap when reindexing with `fill_method`. .. deprecated:: 0.18.0 base : int, default 0 @@ -7426,7 +7426,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, level : str or int, optional For a MultiIndex, level (name or number) to use for - resampling. ``level`` must be datetime-like. + resampling. `level` must be datetime-like. .. versionadded:: 0.19.0 @@ -7446,6 +7446,8 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, See Also -------- groupby : Group by mapping, function, label, or list of labels. + Series.resample : Resample a Series. + DataFrame.resample: Resample a DataFrame. Examples -------- @@ -7544,10 +7546,10 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2000-01-01 00:06:00 26 Freq: 3T, dtype: int64 - For a Series with a PeriodIndex, the keyword ``convention`` can be + For a Series with a PeriodIndex, the keyword `convention` can be used to control whether to use the start or end of `rule`. - Resample a year by quarter using 'start' ``convention``. Values are + Resample a year by quarter using 'start' `convention`. Values are assigned to the first quarter of the period. >>> s = pd.Series([1, 2], index=pd.period_range('2012-01-01', @@ -7568,7 +7570,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2013Q4 NaN Freq: Q-DEC, dtype: float64 - Resample quarters by month using 'end' ``convention``. Values are + Resample quarters by month using 'end' `convention`. Values are assigned to the last month of the period. >>> q = pd.Series([1, 2, 3, 4], index=pd.period_range('2018-01-01', @@ -7593,7 +7595,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2018-12 4.0 Freq: M, dtype: float64 - For DataFrame objects, the keyword ``on`` can be used to specify the + For DataFrame objects, the keyword `on` can be used to specify the column instead of the index for resampling. >>> d = dict({'price': [10, 11, 9, 13, 14, 18, 17, 19], @@ -7618,7 +7620,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2018-01-31 10.75 62.5 2018-02-28 17.00 60.0 - For a DataFrame with MultiIndex, the keyword ``level`` can be used to + For a DataFrame with MultiIndex, the keyword `level` can be used to specify on which level the resampling needs to take place. >>> days = pd.date_range('1/1/2000', periods=4, freq='D') From bbddcd229d63fd4990c3483f93a3296096342ea9 Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Fri, 9 Nov 2018 17:00:08 +0000 Subject: [PATCH 12/16] DOC: Remove non-ASCII character. --- 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 01b3d6bf67df3..f1d5697a2cef1 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7378,7 +7378,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, rule : str The offset string or object representing target conversion. how : str - Method for down-/re-sampling, default to ‘mean’ for downsampling. + Method for down/re-sampling, default to ‘mean’ for downsampling. .. deprecated:: 0.18.0 The new syntax is ``.resample(...).mean()``, or From e0aef30319c1a5864af5777d20dd8f84bc29794c Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Fri, 9 Nov 2018 17:12:25 +0000 Subject: [PATCH 13/16] DOC: Remove weird quotes in resample. --- 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 f1d5697a2cef1..979803f3cc400 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7378,7 +7378,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, rule : str The offset string or object representing target conversion. how : str - Method for down/re-sampling, default to ‘mean’ for downsampling. + Method for down/re-sampling, default to 'mean' for downsampling. .. deprecated:: 0.18.0 The new syntax is ``.resample(...).mean()``, or From fab0ad04710053e886b5bb4316f68cc51ca7612e Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Sat, 10 Nov 2018 10:57:43 +0000 Subject: [PATCH 14/16] DOC: Add missing space. --- 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 bb555edb76b5f..ec655cafadbe2 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7759,7 +7759,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, >>> days = pd.date_range('1/1/2000', periods=4, freq='D') >>> d2 = dict({'price': [10, 11, 9, 13, 14, 18, 17, 19], - ... 'volume': [50, 60, 40, 100, 50, 100, 40, 50]}) + ... 'volume': [50, 60, 40, 100, 50, 100, 40, 50]}) >>> df2 = pd.DataFrame( ... d2, ... index=pd.MultiIndex.from_product( From 7567e12a91da8ff0129332130ff598de4ac6c8d8 Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Sat, 10 Nov 2018 10:58:05 +0000 Subject: [PATCH 15/16] Enable CI check on resample docs. --- ci/code_checks.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index c4b483a794c21..eba96f0c6c2fc 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -151,7 +151,7 @@ if [[ -z "$CHECK" || "$CHECK" == "doctests" ]]; then MSG='Doctests generic.py' ; echo $MSG pytest -q --doctest-modules pandas/core/generic.py \ - -k"-_set_axis_name -_xs -describe -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -resample -to_json -transpose -values -xs" + -k"-_set_axis_name -_xs -describe -droplevel -groupby -interpolate -pct_change -pipe -reindex -reindex_axis -to_json -transpose -values -xs" RET=$(($RET + $?)) ; echo $MSG "DONE" MSG='Doctests top-level reshaping functions' ; echo $MSG From 109e414bcae2b45e83ed2feba8ec38046ef3b44e Mon Sep 17 00:00:00 2001 From: Jose Rivera Date: Sat, 10 Nov 2018 12:21:57 +0000 Subject: [PATCH 16/16] DOC: Remove some flake8 errors in resample docstring. --- pandas/core/generic.py | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index ec655cafadbe2..cfdc6b34274bf 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7639,7 +7639,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, Upsample the series into 30 second bins. - >>> series.resample('30S').asfreq()[0:5] #select first 5 rows + >>> series.resample('30S').asfreq()[0:5] # Select first 5 rows 2000-01-01 00:00:00 0.0 2000-01-01 00:00:30 NaN 2000-01-01 00:01:00 1.0 @@ -7673,7 +7673,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, >>> def custom_resampler(array_like): ... return np.sum(array_like) + 5 - + ... >>> series.resample('3T').apply(custom_resampler) 2000-01-01 00:00:00 8 2000-01-01 00:03:00 17 @@ -7760,12 +7760,11 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, >>> days = pd.date_range('1/1/2000', periods=4, freq='D') >>> d2 = dict({'price': [10, 11, 9, 13, 14, 18, 17, 19], ... 'volume': [50, 60, 40, 100, 50, 100, 40, 50]}) - >>> df2 = pd.DataFrame( - ... d2, - ... index=pd.MultiIndex.from_product( - ... [days, ['morning', 'afternoon']] - ... ) - ... ) + >>> df2 = pd.DataFrame(d2, + ... index=pd.MultiIndex.from_product([days, + ... ['morning', + ... 'afternoon']] + ... )) >>> df2 price volume 2000-01-01 morning 10 50 @@ -7783,6 +7782,7 @@ def resample(self, rule, how=None, axis=0, fill_method=None, closed=None, 2000-01-03 32 150 2000-01-04 36 90 """ + from pandas.core.resample import (resample, _maybe_process_deprecations) axis = self._get_axis_number(axis)