augment_atr

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

Calculate Average True Range (ATR) or Normalised ATR for pandas or polars data.

Parameters

Name	Type	Description	Default
data	DataFrame or GroupBy(pandas or polars)	Input financial data. Grouped inputs are processed per group before the indicators are appended.	required
date_column	str	Name of the column containing date information.	required
high_column	str	Column names used to compute the true range and ATR.	required
low_column	str	Column names used to compute the true range and ATR.	required
close_column	str	Column names used to compute the true range and ATR.	required
periods	int, tuple, or list	Rolling window lengths. Accepts an integer, an inclusive tuple range, or an explicit list. Defaults to 20.	20
normalize	bool	When True, report the normalised ATR (ATR / close * 100). Defaults to False.	False
reduce_memory	bool	Attempt to reduce memory usage when operating on pandas data. If a polars input is supplied a warning is emitted and no conversion occurs.	False
engine	(auto, pandas, polars)	Execution engine. "auto" (default) infers the backend from the input data while allowing explicit overrides.	"auto"

Returns

Name	Type	Description
	DataFrame	DataFrame with {close_column}_atr_{period} (or _natr_ when normalize=True) columns appended for each requested period. The return type matches the input backend.

Notes

The Average True Range (ATR) follows Wilder’s definition, using the maximum of the intra-period range, the high-to-previous-close distance, and the low-to-previous-close distance. When normalize=True the ATR is scaled by the close price and expressed as a percentage (often called NATR). Both pandas and polars implementations guard against division by zero by returning NaN when the denominator is zero.

Examples

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


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

# Pandas example (engine inferred)
atr_pd = (
    df.groupby("symbol")
    .augment_atr(
        date_column="date",
        high_column="high",
        low_column="low",
        close_column="close",
        periods=[14, 28],
        normalize=False,
    )
)

# Polars example using the tk accessor
atr_pl = (
    pl.from_pandas(df.query("symbol == 'AAPL'"))
    .tk.augment_atr(
        date_column="date",
        high_column="high",
        low_column="low",
        close_column="close",
        periods=14,
        normalize=True,
    )
)