augment_roc

augment_roc(data, date_column, close_column, periods=1, start_index=0, reduce_memory=False, engine='pandas')

Adds rate of change (percentage change) to a Pandas DataFrame or DataFrameGroupBy object.

Parameters

Name	Type	Description	Default
`data`	pd.DataFrame or pd.core.groupby.generic.DataFrameGroupBy	The `data` parameter is the input DataFrame or DataFrameGroupBy object that you want to add percentage differenced columns to.	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
`close_column`	str	The `close_column` parameter in the `augment_qsmomentum` function refers to the column in the input DataFrame that contains the closing prices of the financial instrument or asset for which you want to calculate the momentum.	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`
`start_index`	int	The `start_index` parameter is an integer that specifies the starting index for the percentage difference calculation. Default is 0 which is the last element in the group.	`0`
`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`	str	The `engine` parameter is used to specify the engine to use for augmenting percentage differences. It can be either “pandas” or “polars”. - The default value is “pandas”. - When “polars”, the function will internally use the `polars` library for augmenting percentage diffs. This can be faster than using “pandas” for large datasets.	`'pandas'`

Returns

Type	Description
pd.DataFrame	A Pandas DataFrame with percentage differenced columns added to it.

Notes

The rate of change (ROC) calculation is a momentum indicator that measures the percentage change in price between the current price and the price a certain number of periods ago. The ROC indicator is used to identify the speed and direction of price movements. It is calculated as follows:

ROC = [(Close - Close n periods ago) / (Close n periods ago)]

When start_index is used, the formula becomes:

ROC = [(Close start_index periods ago - Close n periods ago) / (Close n periods ago)]

Examples

import pandas as pd
import pytimetk as tk

df = tk.load_dataset("stocks_daily", parse_dates = ['date'])

df.glimpse()

<class 'pandas.core.frame.DataFrame'>: 16194 rows of 8 columns
symbol:    object            ['META', 'META', 'META', 'META', 'META', 'M ...
date:      datetime64[ns]    [Timestamp('2013-01-02 00:00:00'), Timestam ...
open:      float64           [27.440000534057617, 27.8799991607666, 28.0 ...
high:      float64           [28.18000030517578, 28.46999931335449, 28.9 ...
low:       float64           [27.420000076293945, 27.59000015258789, 27. ...
close:     float64           [28.0, 27.770000457763672, 28.7600002288818 ...
volume:    int64             [69846400, 63140600, 72715400, 83781800, 45 ...
adjusted:  float64           [28.0, 27.770000457763672, 28.7600002288818 ...

# Example 1 - Add 7 roc values for a single DataFrame object, pandas engine
roc_df = (
    df 
        .query('symbol == "GOOG"') 
        .augment_roc(
            date_column='date',
            close_column='close',
            periods=(1, 7),
            engine='pandas'
        )
)
roc_df.glimpse()

<class 'pandas.core.frame.DataFrame'>: 2699 rows of 15 columns
symbol:         object            ['GOOG', 'GOOG', 'GOOG', 'GOOG', 'GOOG ...
date:           datetime64[ns]    [Timestamp('2013-01-02 00:00:00'), Tim ...
open:           float64           [17.918338775634766, 18.05557250976562 ...
high:           float64           [18.10713005065918, 18.22991943359375, ...
low:            float64           [17.84685516357422, 17.950716018676758 ...
close:          float64           [18.013729095458984, 18.02419090270996 ...
volume:         int64             [102033017, 93075567, 110954331, 66476 ...
adjusted:       float64           [18.013729095458984, 18.02419090270996 ...
close_roc_0_1:  float64           [nan, 0.000580768545787258, 0.01976038 ...
close_roc_0_2:  float64           [nan, nan, 0.0203526286844391, 0.01531 ...
close_roc_0_3:  float64           [nan, nan, nan, 0.01590056395431705, 0 ...
close_roc_0_4:  float64           [nan, nan, nan, nan, 0.013895668345478 ...
close_roc_0_5:  float64           [nan, nan, nan, nan, nan, 0.0205600535 ...
close_roc_0_6:  float64           [nan, nan, nan, nan, nan, nan, 0.02520 ...
close_roc_0_7:  float64           [nan, nan, nan, nan, nan, nan, nan, 0. ...

# Example 2 - Add 2 ROC with start index 21 using GroupBy object, polars engine
roc_df = (
    df 
        .groupby('symbol')
        .augment_roc(
            date_column='date',
            close_column='close',
            periods=[63, 252],
            start_index=21,
            engine='polars'
        )
)
roc_df

	symbol	date	open	high	low	close	volume	adjusted	close_roc_21_63	close_roc_21_252
0	META	2013-01-02	27.440001	28.180000	27.420000	28.000000	69846400	28.000000	NaN	NaN
1	META	2013-01-03	27.879999	28.469999	27.590000	27.770000	63140600	27.770000	NaN	NaN
2	META	2013-01-04	28.010000	28.930000	27.830000	28.760000	72715400	28.760000	NaN	NaN
3	META	2013-01-07	28.690001	29.790001	28.650000	29.420000	83781800	29.420000	NaN	NaN
4	META	2013-01-08	29.510000	29.600000	28.860001	29.059999	45871300	29.059999	NaN	NaN
...	...	...	...	...	...	...	...	...	...	...
16189	GOOG	2023-09-15	138.800003	139.360001	137.179993	138.300003	48947600	138.300003	0.026393	0.219514
16190	GOOG	2023-09-18	137.630005	139.929993	137.630005	138.960007	16233600	138.960007	0.051588	0.255630
16191	GOOG	2023-09-19	138.250000	139.175003	137.500000	138.830002	15479100	138.830002	0.034396	0.236225
16192	GOOG	2023-09-20	138.830002	138.839996	134.520004	134.589996	21473500	134.589996	0.063252	0.241502
16193	GOOG	2023-09-21	132.389999	133.190002	131.089996	131.360001	22042700	131.360001	0.046985	0.273593

16194 rows × 10 columns