import polars as pl
import pytimetk as tk
= tk.load_dataset("stocks_daily", parse_dates=["date"])
df
# Pandas DataFrame input (engine inferred)
= df.groupby("symbol").augment_roc(
roc_df ="date",
date_column="close",
close_column=[22, 63],
periods=5,
start_index
)
# Polars DataFrame input using the tk accessor
= (
roc_pl "symbol == 'AAPL'"))
pl.from_pandas(df.query(
.tk.augment_roc(="date",
date_column="close",
close_column=(5, 10),
periods
) )
augment_roc
augment_roc(
data,
date_column,
close_column,=1,
periods=0,
start_index=False,
reduce_memory='auto',
engine )
Add rate-of-change (ROC) columns to a pandas or polars DataFrame.
Parameters
Name | Type | Description | Default |
---|---|---|---|
data | DataFrame or GroupBy(pandas or polars) | Input financial data. Grouped inputs are expanded per group before computing ROC features. | required |
date_column | str | Name of the column containing date information. Used to preserve the original ordering. | required |
close_column | str | Name of the column containing closing prices on which the ROC is computed. | required |
periods | int, tuple, or list | Lookback windows used for the denominator term. An integer adds a single ROC column, a tuple (start, end) expands to the inclusive range start..end , and a list provides explicit periods. Defaults to 1 . |
1 |
start_index | int | Offset applied to the numerator. When 0 (default) the current value is used; otherwise the numerator uses close.shift(start_index) . |
0 |
reduce_memory | bool | Attempt to reduce memory usage when operating on pandas data. If used with polars inputs a warning is emitted and no conversion is performed. | False |
engine | (auto, pandas, polars) | Execution engine. "auto" (default) infers the backend from the input data type while also accepting explicit overrides. |
"auto" |
Returns
Name | Type | Description |
---|---|---|
DataFrame | DataFrame with ROC columns appended. The return type matches the input backend (pandas or polars). |
Notes
Rate of change is defined as ::
ROC = (Value_t - Value_{t-period}) / Value_{t-period}
When start_index
is non-zero the numerator is taken from Value_{t-start_index}
instead of the current value. The implementation safeguards against division by zero by returning NaN
whenever the denominator is zero.