augment_atr

augment_atr(data, date_column, high_column, low_column, close_column, periods=20, normalize=False, reduce_memory=False, engine='pandas')

The augment_atr function is used to calculate Average True Range (ATR) and Normalized Average True Range (NATR) for a given dataset and return the augmented dataset. Set the normalize parameter to True to calculate NATR.

Parameters

Name	Type	Description	Default
data	Union[pd.DataFrame, pd.core.groupby.generic.DataFrameGroupBy]	The data parameter is the input data that can be either a pandas DataFrame or a pandas DataFrameGroupBy object. It contains the data on which the Bollinger Bands will be calculated.	required
date_column	str	The date_column parameter is a string that specifies the name of the column in the data DataFrame that contains the dates.	required
high_column	str	The high_column parameter is a string that specifies the name of the column in the data DataFrame that contains the high prices of the asset.	required
low_column	str	The low_column parameter is a string that specifies the name of the column in the data DataFrame that contains the low prices of the asset.	required
close_column	str	The close_column parameter is a string that specifies the name of the column in the data DataFrame that contains the closing prices of the asset.	required
periods	Union[int, Tuple[int, int], List[int]]	The periods parameter in the augment_atr function can be specified as an integer, a tuple, or a list. This parameter specifies the number of rolling periods to use when calculating the ATR.	20
normalize	bool	The normalize parameter is a boolean flag that indicates whether or not to normalize the ATR values. If set to True, the function will normalize the ATR values to express this volatility as a percentage of the closing price.	False
reduce_memory	bool	The reduce_memory parameter is a boolean flag that indicates whether or not to reduce the memory usage of the input data before performing the calculation. If set to True, the function will attempt to reduce the memory usage of the input data using techniques such as downcasting numeric columns and converting object columns	False
engine	str	The engine parameter specifies the computation engine to use for calculating the Bollinger Bands. It can take two values: ‘pandas’ or ‘polars’. If ‘pandas’ is selected, the function will use the pandas library for computation. If ‘polars’ is selected,	'pandas'

Returns

Type	Description
pd.DataFrame	The function augment_atr returns a pandas DataFrame.

Notes

ATR (Average True Range)

The Average True Range (ATR) is a technical analysis indicator used to measure market volatility. It was introduced by J. Welles Wilder Jr. in his 1978 book “New Concepts in Technical Trading Systems.”

The ATR is calculated as follows:

1. True Range: For each period (typically a day), the True Range is the greatest of the following:

   • The current high minus the current low.
   • The absolute value of the current high minus the previous close.
   • The absolute value of the current low minus the previous close.

2. Average True Range: The ATR is an average of the True Range over a specified number of periods (commonly 14 days).

NATR (Normalized Average True Range)

The NATR (Normalized Average True Range) is a variation of the ATR that normalizes the ATR values to express this volatility as a percentage of the closing price.

The NATR (normalize = True) is calculated as follows: NATR = (ATR / Close) * 100

Examples

import pandas as pd
import pytimetk as tk

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

df

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

16194 rows × 8 columns

# ATR pandas engine
df_atr = (
    df
        .groupby('symbol')
        .augment_atr(
            date_column = 'date', 
            high_column='high',
            low_column='low',
            close_column='close', 
            periods = [14, 28],
            normalize = False, # True for NATR
            engine = "pandas"
        )
)

df_atr.glimpse()

<class 'pandas.core.frame.DataFrame'>: 16194 rows of 10 columns
symbol:        object            ['META', 'META', 'META', 'META', 'META' ...
date:          datetime64[ns]    [Timestamp('2013-01-02 00:00:00'), Time ...
open:          float64           [27.440000534057617, 27.8799991607666,  ...
high:          float64           [28.18000030517578, 28.46999931335449,  ...
low:           float64           [27.420000076293945, 27.59000015258789, ...
close:         float64           [28.0, 27.770000457763672, 28.760000228 ...
volume:        int64             [69846400, 63140600, 72715400, 83781800 ...
adjusted:      float64           [28.0, 27.770000457763672, 28.760000228 ...
close_atr_14:  float64           [nan, nan, nan, nan, nan, nan, nan, nan ...
close_atr_28:  float64           [nan, nan, nan, nan, nan, nan, nan, nan ...

# ATR polars engine
df_atr = (
    df
        .groupby('symbol')
        .augment_atr(
            date_column = 'date', 
            high_column='high',
            low_column='low',
            close_column='close', 
            periods = [14, 28],
            normalize = False, # True for NATR
            engine = "polars"
        )
)

df_atr.glimpse()

<class 'pandas.core.frame.DataFrame'>: 16194 rows of 10 columns
symbol:        object            ['META', 'META', 'META', 'META', 'META' ...
date:          datetime64[ns]    [Timestamp('2013-01-02 00:00:00'), Time ...
open:          float64           [27.440000534057617, 27.8799991607666,  ...
high:          float64           [28.18000030517578, 28.46999931335449,  ...
low:           float64           [27.420000076293945, 27.59000015258789, ...
close:         float64           [28.0, 27.770000457763672, 28.760000228 ...
volume:        int64             [69846400, 63140600, 72715400, 83781800 ...
adjusted:      float64           [28.0, 27.770000457763672, 28.760000228 ...
close_atr_14:  float64           [nan, nan, nan, nan, nan, nan, nan, nan ...
close_atr_28:  float64           [nan, nan, nan, nan, nan, nan, nan, nan ...