From 41cb90fb3fa70a3a1e17b1fda2e3c854830db50a Mon Sep 17 00:00:00 2001 From: Myles Braithwaite Date: Sat, 10 Mar 2018 13:20:53 -0500 Subject: [PATCH 1/9] :bulb: Fix some basic stuff from the validator script. --- pandas/core/generic.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index d5bdeb7fe1a4d..cccd0b5360e94 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7520,13 +7520,13 @@ def _check_percentile(self, q): Parameters ---------- periods : int, default 1 - Periods to shift for forming percent change + Periods to shift for forming percent change. fill_method : str, default 'pad' - How to handle NAs before computing percent changes + How to handle NAs before computing percent changes. limit : int, default None - The number of consecutive NAs to fill before stopping + The number of consecutive NAs to fill before stopping. freq : DateOffset, timedelta, or offset alias string, optional - Increment to use from time series API (e.g. 'M' or BDay()) + Increment to use from time series API (e.g. 'M' or BDay()). Returns ------- From f818921106d7867162559e3e3982ac4e5ec7e512 Mon Sep 17 00:00:00 2001 From: Myles Braithwaite Date: Sat, 10 Mar 2018 14:38:07 -0500 Subject: [PATCH 2/9] :bulb: Add a quick example of the pct_change function. --- pandas/core/generic.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index cccd0b5360e94..86354f558d5ed 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7527,6 +7527,8 @@ def _check_percentile(self, q): The number of consecutive NAs to fill before stopping. freq : DateOffset, timedelta, or offset alias string, optional Increment to use from time series API (e.g. 'M' or BDay()). + kwargs : mapping, optional + A dictionary of keyword arguments passed into ``%(klass)s.shift``. Returns ------- @@ -7538,6 +7540,24 @@ def _check_percentile(self, q): By default, the percentage change is calculated along the stat axis: 0, or ``Index``, for ``DataFrame`` and 1, or ``minor`` for ``Panel``. You can change this with the ``axis`` keyword argument. + + Examples + -------- + >>> df = pd.DataFrame({ + ... 'FR': [4.0405, 4.0963, 4.3149], + ... 'GR': [1.7246, 1.7482, 1.8519], + ... 'IT': [804.74, 810.01, 860.13]}, + ... index=['1980-01-01', '1980-02-01', '1980-03-01']) + >>> df + FR GR IT + 1980-01-01 4.0405 1.7246 804.74 + 1980-02-01 4.0963 1.7482 810.01 + 1980-03-01 4.3149 1.8519 860.13 + >>> df.pct_change() + FR GR IT + 1980-01-01 NaN NaN NaN + 1980-02-01 0.013810 0.013684 0.006549 + 1980-03-01 0.053365 0.059318 0.061876 """ @Appender(_shared_docs['pct_change'] % _shared_doc_kwargs) From 972e3b1e953e4f1ceb8423b8a7bde2aca91144f0 Mon Sep 17 00:00:00 2001 From: Myles Braithwaite Date: Sat, 10 Mar 2018 15:29:34 -0500 Subject: [PATCH 3/9] :bulb: Add some see also topics to pct_change. --- pandas/core/generic.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 86354f558d5ed..7c76d0fae109e 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7515,7 +7515,10 @@ def _check_percentile(self, q): return q _shared_docs['pct_change'] = """ - Percent change over given number of periods. + Percentage change between the current and previous element. + + This is useful in comparing the percentage of change in a time series + of elements. Parameters ---------- @@ -7536,13 +7539,15 @@ def _check_percentile(self, q): Notes ----- - By default, the percentage change is calculated along the stat axis: 0, or ``Index``, for ``DataFrame`` and 1, or ``minor`` for ``Panel``. You can change this with the ``axis`` keyword argument. Examples -------- + Percentage change in French franc, Deutsche Mark, and Italian lira from + 1 January 1980 to 1 March 1980. + >>> df = pd.DataFrame({ ... 'FR': [4.0405, 4.0963, 4.3149], ... 'GR': [1.7246, 1.7482, 1.8519], @@ -7558,6 +7563,10 @@ def _check_percentile(self, q): 1980-01-01 NaN NaN NaN 1980-02-01 0.013810 0.013684 0.006549 1980-03-01 0.053365 0.059318 0.061876 + + See Also + -------- + pandas.%(klass)s.diff : see the difference of two columns """ @Appender(_shared_docs['pct_change'] % _shared_doc_kwargs) From 6a4c0e6450b8bdf00d5a2fdf8b01b64e26eb4ada Mon Sep 17 00:00:00 2001 From: Myles Braithwaite Date: Mon, 12 Mar 2018 13:48:44 -0400 Subject: [PATCH 4/9] :bulb: Stop showing the private method. --- pandas/core/generic.py | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 7c76d0fae109e..e9ce1c04fab64 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7531,11 +7531,12 @@ def _check_percentile(self, q): freq : DateOffset, timedelta, or offset alias string, optional Increment to use from time series API (e.g. 'M' or BDay()). kwargs : mapping, optional - A dictionary of keyword arguments passed into ``%(klass)s.shift``. + A dictionary of keyword arguments passed into + ``DataFrame.shift``/``Series.shift``. Returns ------- - chg : %(klass)s + chg : Series or DataFrame, same type as the input Notes ----- @@ -7566,7 +7567,8 @@ def _check_percentile(self, q): See Also -------- - pandas.%(klass)s.diff : see the difference of two columns + pandas.DataFrame.diff : see the difference of two columns + pandas.Series.diff : see the difference of two columns """ @Appender(_shared_docs['pct_change'] % _shared_doc_kwargs) From dc2cb5a328932cdcd2bf085fc24015cec105525d Mon Sep 17 00:00:00 2001 From: Myles Braithwaite Date: Mon, 12 Mar 2018 13:59:41 -0400 Subject: [PATCH 5/9] :bulb: Add an exmaple of Series and a Series with a fill_method. --- pandas/core/generic.py | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index e9ce1c04fab64..1063f2edf4a07 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7546,6 +7546,37 @@ def _check_percentile(self, q): Examples -------- + See the percentage change in a Series. + + >>> s = pd.Series([90, 91, 85]) + >>> s + 0 90 + 1 91 + 2 85 + dtype: int64 + >>> s.pct_change() + 0 NaN + 1 0.011111 + 2 -0.065934 + dtype: float64 + + See the percentage change in a Series where filling NAs with last + valid observation forward to next valid. + + >>> s = pd.Series([90, 91, None, 85]) + >>> s + 0 90.0 + 1 91.0 + 2 NaN + 3 85.0 + dtype: float64 + >>> s.pct_change(fill_method='ffill') + 0 NaN + 1 0.011111 + 2 -0.065934 + 3 0.000000 + dtype: float64 + Percentage change in French franc, Deutsche Mark, and Italian lira from 1 January 1980 to 1 March 1980. From ea99c67e91acef4ce74112930afe5c2b7d84c916 Mon Sep 17 00:00:00 2001 From: Myles Braithwaite Date: Mon, 12 Mar 2018 14:01:44 -0400 Subject: [PATCH 6/9] :rotating_light: Fix a mistake with the docstring. --- pandas/core/generic.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 1063f2edf4a07..e668775493041 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7573,8 +7573,8 @@ def _check_percentile(self, q): >>> s.pct_change(fill_method='ffill') 0 NaN 1 0.011111 - 2 -0.065934 - 3 0.000000 + 2 0.000000 + 3 -0.065934 dtype: float64 Percentage change in French franc, Deutsche Mark, and Italian lira from From a0d8ee71afe65699210a7d2cdd50002ad5b1f41c Mon Sep 17 00:00:00 2001 From: Myles Braithwaite Date: Mon, 12 Mar 2018 14:15:25 -0400 Subject: [PATCH 7/9] :bulb: Update based off feedback from @jorisvandenbossche. --- pandas/core/generic.py | 44 +++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index e668775493041..a3acd6349394a 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7530,13 +7530,13 @@ def _check_percentile(self, q): The number of consecutive NAs to fill before stopping. freq : DateOffset, timedelta, or offset alias string, optional Increment to use from time series API (e.g. 'M' or BDay()). - kwargs : mapping, optional - A dictionary of keyword arguments passed into + **kwargs : mapping, optional + Additional keyword arguments are passed into ``DataFrame.shift``/``Series.shift``. Returns ------- - chg : Series or DataFrame, same type as the input + chg : Series or DataFrame, same type as the calling object Notes ----- @@ -7544,6 +7544,25 @@ def _check_percentile(self, q): axis: 0, or ``Index``, for ``DataFrame`` and 1, or ``minor`` for ``Panel``. You can change this with the ``axis`` keyword argument. + Percentage change in French franc, Deutsche Mark, and Italian lira from + 1 January 1980 to 1 March 1980. + + >>> df = pd.DataFrame({ + ... 'FR': [4.0405, 4.0963, 4.3149], + ... 'GR': [1.7246, 1.7482, 1.8519], + ... 'IT': [804.74, 810.01, 860.13]}, + ... index=['1980-01-01', '1980-02-01', '1980-03-01']) + >>> df + FR GR IT + 1980-01-01 4.0405 1.7246 804.74 + 1980-02-01 4.0963 1.7482 810.01 + 1980-03-01 4.3149 1.8519 860.13 + >>> df.pct_change() + FR GR IT + 1980-01-01 NaN NaN NaN + 1980-02-01 0.013810 0.013684 0.006549 + 1980-03-01 0.053365 0.059318 0.061876 + Examples -------- See the percentage change in a Series. @@ -7577,25 +7596,6 @@ def _check_percentile(self, q): 3 -0.065934 dtype: float64 - Percentage change in French franc, Deutsche Mark, and Italian lira from - 1 January 1980 to 1 March 1980. - - >>> df = pd.DataFrame({ - ... 'FR': [4.0405, 4.0963, 4.3149], - ... 'GR': [1.7246, 1.7482, 1.8519], - ... 'IT': [804.74, 810.01, 860.13]}, - ... index=['1980-01-01', '1980-02-01', '1980-03-01']) - >>> df - FR GR IT - 1980-01-01 4.0405 1.7246 804.74 - 1980-02-01 4.0963 1.7482 810.01 - 1980-03-01 4.3149 1.8519 860.13 - >>> df.pct_change() - FR GR IT - 1980-01-01 NaN NaN NaN - 1980-02-01 0.013810 0.013684 0.006549 - 1980-03-01 0.053365 0.059318 0.061876 - See Also -------- pandas.DataFrame.diff : see the difference of two columns From 4ecaf62d98612501258ed9755e2e3d77d1f6c0ed Mon Sep 17 00:00:00 2001 From: Myles Braithwaite Date: Mon, 12 Mar 2018 14:54:29 -0400 Subject: [PATCH 8/9] :bulb: Update based off feedback from @TomAugspurger. --- pandas/core/generic.py | 69 ++++++++++++++++++++++++------------------ 1 file changed, 40 insertions(+), 29 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index a3acd6349394a..d966714b917bf 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7532,36 +7532,12 @@ def _check_percentile(self, q): Increment to use from time series API (e.g. 'M' or BDay()). **kwargs : mapping, optional Additional keyword arguments are passed into - ``DataFrame.shift``/``Series.shift``. + `DataFrame.shift` or `Series.shift`. Returns ------- - chg : Series or DataFrame, same type as the calling object - - Notes - ----- - By default, the percentage change is calculated along the stat - axis: 0, or ``Index``, for ``DataFrame`` and 1, or ``minor`` for - ``Panel``. You can change this with the ``axis`` keyword argument. - - Percentage change in French franc, Deutsche Mark, and Italian lira from - 1 January 1980 to 1 March 1980. - - >>> df = pd.DataFrame({ - ... 'FR': [4.0405, 4.0963, 4.3149], - ... 'GR': [1.7246, 1.7482, 1.8519], - ... 'IT': [804.74, 810.01, 860.13]}, - ... index=['1980-01-01', '1980-02-01', '1980-03-01']) - >>> df - FR GR IT - 1980-01-01 4.0405 1.7246 804.74 - 1980-02-01 4.0963 1.7482 810.01 - 1980-03-01 4.3149 1.8519 860.13 - >>> df.pct_change() - FR GR IT - 1980-01-01 NaN NaN NaN - 1980-02-01 0.013810 0.013684 0.006549 - 1980-03-01 0.053365 0.059318 0.061876 + chg : Series or DataFrame + The same type as the calling object. Examples -------- @@ -7596,10 +7572,45 @@ def _check_percentile(self, q): 3 -0.065934 dtype: float64 + Percentage change in French franc, Deutsche Mark, and Italian lira from + 1 January 1980 to 1 March 1980. + + >>> df = pd.DataFrame({ + ... 'FR': [4.0405, 4.0963, 4.3149], + ... 'GR': [1.7246, 1.7482, 1.8519], + ... 'IT': [804.74, 810.01, 860.13]}, + ... index=['1980-01-01', '1980-02-01', '1980-03-01']) + >>> df + FR GR IT + 1980-01-01 4.0405 1.7246 804.74 + 1980-02-01 4.0963 1.7482 810.01 + 1980-03-01 4.3149 1.8519 860.13 + >>> df.pct_change() + FR GR IT + 1980-01-01 NaN NaN NaN + 1980-02-01 0.013810 0.013684 0.006549 + 1980-03-01 0.053365 0.059318 0.061876 + + Percentage of change in GOOG and APPL stock volume. + + >>> df = pd.DataFrame({ + ... '2016': [1769950, 30586265], + ... '2015': [1500923, 40912316], + ... '2014': [1371819, 41403351]}, + ... index=['GOOG', 'APPL']) + >>> df + 2016 2015 2014 + GOOG 1769950 1500923 1371819 + APPL 30586265 40912316 41403351 + >>> df.pct_change(axis='columns') + 2016 2015 2014 + GOOG NaN -0.151997 -0.086016 + APPL NaN 0.337604 0.012002 + See Also -------- - pandas.DataFrame.diff : see the difference of two columns - pandas.Series.diff : see the difference of two columns + DataFrame.diff : see the difference of two columns + Series.diff : see the difference of two columns """ @Appender(_shared_docs['pct_change'] % _shared_doc_kwargs) From a0dcac29b07bb377ccae463692163fb3385860b1 Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Mon, 12 Mar 2018 15:17:54 -0500 Subject: [PATCH 9/9] Previous to prior Note that it's immedate, but configurable. no type on kwargs. Example with periods. Moved See Also. --- pandas/core/generic.py | 40 ++++++++++++++++++++++++++++------------ 1 file changed, 28 insertions(+), 12 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index d966714b917bf..b1326b84cefcd 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -7515,10 +7515,11 @@ def _check_percentile(self, q): return q _shared_docs['pct_change'] = """ - Percentage change between the current and previous element. + Percentage change between the current and a prior element. - This is useful in comparing the percentage of change in a time series - of elements. + Computes the percentage change from the immediately previous row by + default. This is useful in comparing the percentage of change in a time + series of elements. Parameters ---------- @@ -7530,7 +7531,7 @@ def _check_percentile(self, q): The number of consecutive NAs to fill before stopping. freq : DateOffset, timedelta, or offset alias string, optional Increment to use from time series API (e.g. 'M' or BDay()). - **kwargs : mapping, optional + **kwargs Additional keyword arguments are passed into `DataFrame.shift` or `Series.shift`. @@ -7539,9 +7540,16 @@ def _check_percentile(self, q): chg : Series or DataFrame The same type as the calling object. + See Also + -------- + Series.diff : Compute the difference of two elements in a Series. + DataFrame.diff : Compute the difference of two elements in a DataFrame. + Series.shift : Shift the index by some number of periods. + DataFrame.shift : Shift the index by some number of periods. + Examples -------- - See the percentage change in a Series. + **Series** >>> s = pd.Series([90, 91, 85]) >>> s @@ -7549,12 +7557,19 @@ def _check_percentile(self, q): 1 91 2 85 dtype: int64 + >>> s.pct_change() 0 NaN 1 0.011111 2 -0.065934 dtype: float64 + >>> s.pct_change(periods=2) + 0 NaN + 1 NaN + 2 -0.055556 + dtype: float64 + See the percentage change in a Series where filling NAs with last valid observation forward to next valid. @@ -7565,6 +7580,7 @@ def _check_percentile(self, q): 2 NaN 3 85.0 dtype: float64 + >>> s.pct_change(fill_method='ffill') 0 NaN 1 0.011111 @@ -7572,8 +7588,10 @@ def _check_percentile(self, q): 3 -0.065934 dtype: float64 + **DataFrame** + Percentage change in French franc, Deutsche Mark, and Italian lira from - 1 January 1980 to 1 March 1980. + 1980-01-01 to 1980-03-01. >>> df = pd.DataFrame({ ... 'FR': [4.0405, 4.0963, 4.3149], @@ -7585,13 +7603,15 @@ def _check_percentile(self, q): 1980-01-01 4.0405 1.7246 804.74 1980-02-01 4.0963 1.7482 810.01 1980-03-01 4.3149 1.8519 860.13 + >>> df.pct_change() FR GR IT 1980-01-01 NaN NaN NaN 1980-02-01 0.013810 0.013684 0.006549 1980-03-01 0.053365 0.059318 0.061876 - Percentage of change in GOOG and APPL stock volume. + Percentage of change in GOOG and APPL stock volume. Shows computing + the percentage change between columns. >>> df = pd.DataFrame({ ... '2016': [1769950, 30586265], @@ -7602,15 +7622,11 @@ def _check_percentile(self, q): 2016 2015 2014 GOOG 1769950 1500923 1371819 APPL 30586265 40912316 41403351 + >>> df.pct_change(axis='columns') 2016 2015 2014 GOOG NaN -0.151997 -0.086016 APPL NaN 0.337604 0.012002 - - See Also - -------- - DataFrame.diff : see the difference of two columns - Series.diff : see the difference of two columns """ @Appender(_shared_docs['pct_change'] % _shared_doc_kwargs)