augment_pct_change

augment_pct_change(
    data,
    date_column,
    value_column,
    periods=1,
    reduce_memory=False,
    engine='auto',
)

Adds percentage difference (percentage change) columns to pandas or polars data.

Parameters

Name Type Description Default
data DataFrame or GroupBy(pandas or polars) Input data to augment with percentage change columns. required
date_column str The date_column parameter is a string that specifies the name of the column in the DataFrame that contains the dates. This column will be used to sort the data before adding the percentage differenced values. required
value_column str or list The value_column parameter is the column(s) in the DataFrame that you want to add percentage differences values for. It can be either a single column name (string) or a list of column names. required
periods int or tuple or list The periods parameter is an integer, tuple, or list that specifies the periods to shift values when percentage differencing. - If it is an integer, the function will add that number of percentage differences values for each column specified in the value_column parameter. - If it is a tuple, it will generate percentage differences from the first to the second value (inclusive). - If it is a list, it will generate percentage differences based on the values in the list. 1
reduce_memory bool The reduce_memory parameter is used to specify whether to reduce the memory usage of the DataFrame by converting int, float to smaller bytes and str to categorical data. This reduces memory for large data but may impact resolution of float and will change str to categorical. Default is True. False
engine (auto, pandas, polars, cudf) Execution engine. When β€œauto” (default) the backend is inferred from the input data type. Use β€œpandas”, β€œpolars”, or β€œcudf” to force a specific backend. "auto"

Returns

Name Type Description
DataFrame DataFrame with percentage differenced columns added, matching the backend of the input data.

Examples

import pandas as pd
import polars as pl
import pytimetk as tk


df = tk.load_dataset('m4_daily', parse_dates=['date'])
df
id date value
0 D10 2014-07-03 2076.2
1 D10 2014-07-04 2073.4
2 D10 2014-07-05 2048.7
3 D10 2014-07-06 2048.9
4 D10 2014-07-07 2006.4
... ... ... ...
9738 D500 2012-09-19 9418.8
9739 D500 2012-09-20 9365.7
9740 D500 2012-09-21 9445.9
9741 D500 2012-09-22 9497.9
9742 D500 2012-09-23 9545.3

9743 rows Γ— 3 columns

# Example 1 - Add 7 pctdiff values for a single DataFrame object (pandas)
pctdiff_df_single = (
    df
        .query('id == "D10"')
        .augment_pct_change(
            date_column='date',
            value_column='value',
            periods=(1, 7)
        )
)
pctdiff_df_single.glimpse()
<class 'pandas.core.frame.DataFrame'>: 674 rows of 10 columns
id:               object            ['D10', 'D10', 'D10', 'D10', 'D10',  ...
date:             datetime64[ns]    [Timestamp('2014-07-03 00:00:00'), T ...
value:            float64           [2076.2, 2073.4, 2048.7, 2048.9, 200 ...
value_pctdiff_1:  float64           [nan, -0.0013486176668913163, -0.011 ...
value_pctdiff_2:  float64           [nan, nan, -0.013245352085540896, -0 ...
value_pctdiff_3:  float64           [nan, nan, nan, -0.01314902225219138 ...
value_pctdiff_4:  float64           [nan, nan, nan, nan, -0.033619111838 ...
value_pctdiff_5:  float64           [nan, nan, nan, nan, nan, -0.0282246 ...
value_pctdiff_6:  float64           [nan, nan, nan, nan, nan, nan, -0.02 ...
value_pctdiff_7:  float64           [nan, nan, nan, nan, nan, nan, nan,  ...
# Example 2 - Add percentage differences via the polars accessor
pctdiff_df = (
    pl.from_pandas(df)
    .group_by('id')
    .tk.augment_pct_change(
        date_column='date',
        value_column='value',
        periods=2,
    )
)
pctdiff_df
shape: (9_743, 4)
id date value value_pctdiff_2
str datetime[ns] f64 f64
"D10" 2014-07-03 00:00:00 2076.2 null
"D10" 2014-07-04 00:00:00 2073.4 null
"D10" 2014-07-05 00:00:00 2048.7 -0.013245
"D10" 2014-07-06 00:00:00 2048.9 -0.011816
"D10" 2014-07-07 00:00:00 2006.4 -0.020647
… … … …
"D500" 2012-09-19 00:00:00 9418.8 -0.002003
"D500" 2012-09-20 00:00:00 9365.7 -0.007019
"D500" 2012-09-21 00:00:00 9445.9 0.002877
"D500" 2012-09-22 00:00:00 9497.9 0.014115
"D500" 2012-09-23 00:00:00 9545.3 0.010523 
# Example 3 add 2 percent differenced values, 2 and 4, for a single DataFrame object (pandas)
pctdiff_df_single_two = (
    df
        .query('id == "D10"')
        .augment_pct_change(
            date_column='date',
            value_column='value',
            periods=[2, 4]
        )
)
pctdiff_df_single_two
id date value value_pctdiff_2 value_pctdiff_4
0 D10 2014-07-03 2076.2 NaN NaN
1 D10 2014-07-04 2073.4 NaN NaN
2 D10 2014-07-05 2048.7 -0.013245 NaN
3 D10 2014-07-06 2048.9 -0.011816 NaN
4 D10 2014-07-07 2006.4 -0.020647 -0.033619
... ... ... ... ... ...
669 D10 2016-05-02 2630.7 0.022465 0.019691
670 D10 2016-05-03 2649.3 0.018570 0.041392
671 D10 2016-05-04 2631.8 0.000418 0.022892
672 D10 2016-05-05 2622.5 -0.010116 0.008266
673 D10 2016-05-06 2620.1 -0.004446 -0.004029

674 rows Γ— 5 columns