import pytimetk as tk
import polars as pl
= tk.load_dataset("stocks_daily", parse_dates=["date"])
df
# Calculate QSM for multiple ROCs using pandas backend
= (
qsm_pd "symbol")
df.groupby(
.augment_qsmomentum(="date",
date_column="close",
close_column=[5, 21],
roc_fast_period=252,
roc_slow_period=126,
returns_period
)
)
# Compute QSM on a polars DataFrame via the tk accessor
= (
qsm_pl "symbol == 'AAPL'"))
pl.from_pandas(df.query(
.tk.augment_qsmomentum(="date",
date_column="close",
close_column=[5, 21],
roc_fast_period=252,
roc_slow_period=126,
returns_period
) )
augment_qsmomentum
augment_qsmomentum(
data,
date_column,
close_column,=21,
roc_fast_period=252,
roc_slow_period=126,
returns_period=False,
reduce_memory='auto',
engine )
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.