API reference — Feature functions¶
Grouped/trended/windowed transforms, lags and calendar parts. Guide: Data processing.
grouped_scale¶
pythongrouped_scale((keys, values, strategy='zscore'))
One-shot group scaling: fit on (keys, values) and transform the same rows.
Each row's value is scaled by its group's summary under strategy
(centered family like "zscore" or ratio family like "mean"; see
GroupedScaler for the full list and the exact inverse).
Args: keys: group label per row (None = missing). values: numeric value per row (None/NaN = missing). strategy: one of "zscore", "min-max", "median-iqr", "mean-iqr", "median-qd", "median-std", "median-range", "mean-range", "min-qd", "min-iqr", "min", "max", "mean", "median", "iqr", "qd", "std", "range".
Returns: scaled values; rows with a missing key/value, an unseen group or a degenerate (zero) scale give None — missing in, missing out.
Raises: ValueError: unknown strategy or mismatched lengths.
grouped_transform¶
pythongrouped_transform((keys, values, kind='mean'))
Per-row group summary of values within groups defined by keys.
Args:
keys: group label per row (None = missing).
values: numeric value per row (None/NaN = missing; excluded from the
group statistics but counted in each group's n_missing).
kind: "mean", "sum", "std", "count", "min", "max", "median",
"q1" or "q3".
Returns: the summary of each row's group; rows with a missing key/value or an unseen group give None.
Raises: ValueError: unknown kind or mismatched lengths.
trended_transform¶
pythontrended_transform((keys, dates, values, granularity='year_month', kind='mean', hemisphere='north'))
Grouped summary trended at a time granularity.
Each row gets the summary of its (key x time-bucket) cell — e.g. with granularity "year_month" and kind "mean", the row's key-and-month mean. Incomplete rows (missing key/date/value) are dropped from estimation and reported via a warning.
Args: keys: series label per row (None = missing). dates: ISO date strings per row (None = missing). values: numeric values per row (None/NaN = missing). granularity: bucket spec joined by "_" from {year, halfyear, season, quarter, month, week, weekday, day} — e.g. "year_month", "year_week", "month_weekday". kind: summary kind ("mean", "sum", "std", "count", "min", "max", "median", "q1", "q3"). hemisphere: "north" or "south" (affects the season component).
Returns: per-row cell summaries; incomplete rows give None.
Raises: ValueError: unknown granularity/kind/hemisphere, unparseable date or mismatched lengths.
windowed_transform¶
pythonwindowed_transform((keys, dates, values, window_days=7, kind='mean', include_current=True))
Trailing-window aggregation per key over day windows.
Each row summarizes the observed values of its key in a window of
window_days days; incomplete rows (missing key/date/value) are dropped
from estimation and reported via a warning.
Args:
keys: series label per row (None = missing).
dates: ISO date strings per row (None = missing).
values: numeric values per row (None/NaN = missing).
window_days: window length in days (>= 1); covering the window_days
days ending at the row's date, or strictly earlier days when
include_current is false.
kind: summary kind ("mean", "sum", "std", "count", "min", "max",
"median", "q1", "q3").
include_current: include the row's own date in the window.
Returns: per-row window summaries; None for incomplete rows and for empty/all-missing windows.
Raises: ValueError: window_days == 0, unknown kind, unparseable date or mismatched lengths.
lag_by_days¶
pythonlag_by_days((keys, dates, values, lag_days))
Lag values by whole days within each key (day granularity).
Each row receives the value of its key at date - lag_days; duplicate
(key, date) rows keep the last occurrence. Incomplete rows (missing
key/date/value) are dropped from estimation and reported via a warning.
Args: keys: series label per row (None = missing). dates: ISO date strings per row (None = missing). values: numeric values per row (None/NaN = missing). lag_days: lag in whole days (0 returns the row's own value).
Returns: lagged values; None where no source row exists.
Raises: ValueError: unparseable date or mismatched lengths.
decomposed_transform¶
pythondecomposed_transform((keys, dates, values, season_granularity='month', trend_window=3, hemisphere='north'))
Additive decomposition, following the statsmodels seasonal_decompose
(additive) convention.
The trend is a centered moving average over each key's rows ordered by date; the seasonal component is the mean of (series - trend) per (key, season bucket), estimated from rows with a complete trend window. Incomplete rows (missing key/date/value) are dropped from estimation and reported via a warning.
Args:
keys: series label per row (None = missing).
dates: ISO date strings per row (None = missing).
values: numeric values per row (None/NaN = missing).
season_granularity: bucket spec for the seasonal component (e.g.
"month", "weekday" — same vocabulary as trended_transform).
trend_window: centered moving-average window in rows (>= 1).
hemisphere: "north" or "south" (affects the season component).
Returns: dict with detrended (series - trend), deseasonalized
(series - seasonal) and residual (series - trend - seasonal);
incomplete rows give None.
Raises: ValueError: trend_window == 0, unknown granularity/hemisphere, unparseable date or mismatched lengths.
calendar_features¶
pythoncalendar_features((dates, hemisphere='north'))
Calendar features for ISO dates (YYYY-MM-DD or timestamp prefix).
Produces year, halfyear, quarter, month, week (ISO), iso_year, weekday (0 = Monday), day, day_of_year, season and weekend as numeric parts, ready for tree learners.
Args: dates: ISO date strings or timestamps (None = missing). hemisphere: "north" or "south" (southern shifts the season by six months).
Returns: dict of 11 feature lists aligned with dates; rows with a
missing date give None features.
Raises: ValueError: unparseable date or unknown hemisphere.