augment_qsmomentum

augment_qsmomentum(
    data,
    date_column,
    close_column,
    roc_fast_period=21,
    roc_slow_period=252,
    returns_period=126,
    reduce_memory=False,
    engine='auto',
)

Calculate Quant Science Momentum (QSM) for pandas or polars inputs.

Parameters

Name	Type	Description	Default
data	DataFrame or GroupBy(pandas or polars)	Input financial data. Grouped inputs are processed per group before the momentum columns are appended.	required
date_column	str	Name of the column containing date information.	required
close_column	str	Column containing closing prices used to compute QSM.	required
roc_fast_period	int, tuple, or list	Lookback window(s) for the fast Rate of Change (ROC). Accepts a single integer, an inclusive tuple range, or a list of explicit periods.	21
roc_slow_period	int, tuple, or list	Lookback window(s) for the slow ROC component.	252
returns_period	int, tuple, or list	Lookback window(s) used when calculating the rolling standard deviation of returns.	126
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, cudf)	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}_qsmom_{fast}_{slow}_{returns} columns appended for every valid combination. The return type matches the input backend.

Notes

QSM measures the difference between slow and fast ROC values normalised by the rolling volatility of returns. Only combinations where fast < slow and returns_period <= slow are evaluated. If no combinations satisfy these rules a ValueError is raised to surface the configuration issue.

Examples

import pytimetk as tk
import polars as pl

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

# Calculate QSM for multiple ROCs using pandas backend
qsm_pd = (
    df.groupby("symbol")
    .augment_qsmomentum(
        date_column="date",
        close_column="close",
        roc_fast_period=[5, 21],
        roc_slow_period=252,
        returns_period=126,
    )
)

# Compute QSM on a polars DataFrame via the tk accessor
qsm_pl = (
    pl.from_pandas(df.query("symbol == 'AAPL'"))
    .tk.augment_qsmomentum(
        date_column="date",
        close_column="close",
        roc_fast_period=[5, 21],
        roc_slow_period=252,
        returns_period=126,
    )
)