augment_stochastic_oscillator

augment_stochastic_oscillator(
    data,
    date_column,
    high_column,
    low_column,
    close_column,
    k_periods=14,
    d_periods=3,
    reduce_memory=False,
    engine='auto',
)

Calculate Stochastic Oscillator (%K and %D) 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 or ColumnSelector	Name of the column containing date information (selectors supported).	required
high_column	str or ColumnSelector	Column containing high prices.	required
low_column	str or ColumnSelector	Column containing low prices.	required
close_column	str or ColumnSelector	Column containing closing prices. Resulting columns are prefixed with this name.	required
k_periods	int, tuple, or list	Lookback window(s) for the %K calculation. Accepts a single integer, an inclusive tuple range, or an explicit list. Defaults to `14`.	`14`
d_periods	int or list	Lookback window(s) for the %D smoothing calculation. Defaults to `3`.	`3`
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 %K and %D columns appended for every combination of `k_periods` and `d_periods`. The return type matches the input backend.

Notes

%K is defined as 100 * (Close - LowestLow) / (HighestHigh - LowestLow) where LowestLow/HighestHigh span the specified lookback window. %D is the rolling mean of %K over d_periods. Division-by-zero scenarios yield NaN values to match the pandas behaviour.

Examples

import polars as pl
import pytimetk as tk

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

# Pandas example (engine inferred)
stoch_df = df.groupby("symbol").augment_stochastic_oscillator(
    date_column="date",
    high_column="high",
    low_column="low",
    close_column="close",
    k_periods=[14, 21],
    d_periods=[3, 9],
)

# Polars example (method chaining)
stoch_pl = (
    pl.from_pandas(df.query("symbol == 'AAPL'"))
    .tk.augment_stochastic_oscillator(
        date_column="date",
        high_column="high",
        low_column="low",
        close_column="close",
        k_periods=14,
        d_periods=[3],
    )
)

from pytimetk.utils.selection import contains
selector_demo = (
    df
        .augment_stochastic_oscillator(
            date_column=contains("dat"),
            high_column=contains("high"),
            low_column=contains("low"),
            close_column=contains("clos"),
            k_periods=14,
            d_periods=[3],
        )
)