augment_adx

augment_adx(
    data,
    date_column,
    high_column,
    low_column,
    close_column,
    periods=14,
    reduce_memory=False,
    engine='auto',
)

Calculate Average Directional Index (ADX), +DI, and -DI using pandas or polars backends.

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 Name of the column containing high prices. required
low_column str Name of the column containing low prices. required
close_column str Name of the column containing closing prices. Indicator columns are prefixed with this name. required
periods int, tuple, or list Lookback windows for smoothing. Accepts an integer, a tuple specifying an inclusive range, or a list of explicit periods. Defaults to 14. 14
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 the following columns appended for each period: - {close_column}_plus_di_{period} - {close_column}_minus_di_{period} - {close_column}_adx_{period} The return type matches the input backend.

Notes

The implementation follows Wilder’s smoothing approach using exponential moving averages with alpha = 1 / period for the true range (TR) and directional movement (+DM, -DM) components. Division by zero is guarded by returning NaN when the denominator is zero.

Examples

import pytimetk as tk

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

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

adx_df.glimpse()
<class 'pandas.core.frame.DataFrame'>: 16194 rows of 14 columns
symbol:             object            ['META', 'META', 'META', 'META', ' ...
date:               datetime64[ns]    [Timestamp('2013-01-02 00:00:00'), ...
open:               float64           [27.440000534057617, 27.8799991607 ...
high:               float64           [28.18000030517578, 28.46999931335 ...
low:                float64           [27.420000076293945, 27.5900001525 ...
close:              float64           [28.0, 27.770000457763672, 28.7600 ...
volume:             int64             [69846400, 63140600, 72715400, 837 ...
adjusted:           float64           [28.0, 27.770000457763672, 28.7600 ...
close_plus_di_14:   float64           [0.0, 0.02144804429181467, 0.05803 ...
close_minus_di_14:  float64           [99.74023064164554, 99.67531582849 ...
close_adx_14:       float64           [26.110865164149793, 31.3855871838 ...
close_plus_di_28:   float64           [0.0, 0.010330322334796915, 0.0273 ...
close_minus_di_28:  float64           [99.74023064164554, 99.70896480989 ...
close_adx_28:       float64           [21.4952142144854, 24.298216606705 ...
# Polars example (method chaining)
import polars as pl

pl_df = pl.from_pandas(df.query("symbol == 'AAPL'"))

adx_pl = pl_df.tk.augment_adx(
    date_column="date",
    high_column="high",
    low_column="low",
    close_column="close",
    periods=14,
)

adx_pl.glimpse()
Rows: 2699
Columns: 11
$ symbol                     <str> 'AAPL', 'AAPL', 'AAPL', 'AAPL', 'AAPL', 'AAPL', 'AAPL', 'AAPL', 'AAPL', 'AAPL'
$ date              <datetime[ns]> 2013-01-02 00:00:00, 2013-01-03 00:00:00, 2013-01-04 00:00:00, 2013-01-07 00:00:00, 2013-01-08 00:00:00, 2013-01-09 00:00:00, 2013-01-10 00:00:00, 2013-01-11 00:00:00, 2013-01-14 00:00:00, 2013-01-15 00:00:00
$ open                       <f64> 19.779285430908203, 19.567142486572266, 19.177499771118164, 18.64285659790039, 18.90035629272461, 18.66071319580078, 18.876785278320312, 18.60714340209961, 17.952856063842773, 17.796428680419922
$ high                       <f64> 19.821428298950195, 19.63107109069824, 19.236785888671875, 18.9035701751709, 18.996070861816406, 18.750356674194336, 18.882856369018555, 18.761428833007812, 18.125, 17.82107162475586
$ low                        <f64> 19.343929290771484, 19.321428298950195, 18.77964210510254, 18.399999618530273, 18.616071701049805, 18.428213119506836, 18.41142845153809, 18.53642845153809, 17.80392837524414, 17.26357078552246
$ close                      <f64> 19.608213424682617, 19.36071395874023, 18.821428298950195, 18.71071434020996, 18.761070251464844, 18.467857360839844, 18.696786880493164, 18.582143783569336, 17.91964340209961, 17.354286193847656
$ volume                     <i64> 560518000, 352965200, 594333600, 484156400, 458707200, 407604400, 601146000, 350506800, 734207600, 876772400
$ adjusted                   <f64> 16.791179656982422, 16.579240798950195, 16.1174373626709, 16.02262306213379, 16.065746307373047, 15.814659118652344, 16.010698318481445, 15.912524223327637, 15.345203399658203, 14.86106777191162
$ close_plus_di_14           <f64> 0.0, 0.0, 0.0, 0.0, 1.4086529900299278, 1.3357370327531486, 3.2946355294876097, 3.175213538310561, 2.7975109354213354, 2.5248350001853535
$ close_minus_di_14          <f64> 0.0, 0.34525921952158917, 8.48343224466678, 13.540429706785595, 12.756866293718087, 15.017938717809615, 13.919011176217822, 13.41448312903257, 23.015351236530428, 28.79996854804468
$ close_adx_14               <f64> nan, nan, nan, nan, nan, nan, nan, nan, nan, nan