preprocessing.rolling.RollingFeatures

preprocessing.rolling.RollingFeatures(stats, window_sizes, features_names=None)

Compute rolling window statistics over time series data.

This transformer computes rolling statistics (mean, std, min, max, sum, median) over windows of specified sizes from a time series. The class follows the scikit-learn transformer API with fit() and transform() methods, making it compatible with scikit-learn pipelines. It also provides transform_batch() for pandas Series input.

Parameters

Name	Type	Description	Default
stats	str | List[str] | List[Any]	Rolling statistics to compute. Can be a single string (‘mean’, ‘std’, ‘min’, ‘max’, ‘sum’, ‘median’), list of statistic names, or list of callable functions. Multiple statistics can be computed simultaneously.	required
window_sizes	int | List[int]	Window size(s) for rolling computation. Can be a single integer or list of integers. Multiple windows are applied to all statistics.	required
features_names	List[str] | None	Custom names for output features. If None, names are auto-generated from statistic names and window sizes (e.g., ‘roll_mean_7’, ‘roll_std_14’). Defaults to None.	None

Attributes

Name	Type	Description
stats		Statistics specification as provided during initialization.
window_sizes		List of window sizes for rolling computation.
features_names		List of output feature names.
stats_funcs		List of compiled/numba-optimized statistical functions.

Note

• Output contains NaN values for positions where the rolling window cannot be fully computed (first window_size-1 positions).
• Statistics are computed using numba-optimized JIT functions for performance.
• The transformer returns numpy arrays from transform() and pandas DataFrames from transform_batch() to maintain index alignment.
• Supports custom user-defined functions in the stats parameter.

Examples

import numpy as np
from spotforecast2_safe.preprocessing.rolling import RollingFeatures

# Single statistic and window size — transform() returns the last
# window's statistic as a 1D array of shape (n_features,).
y = np.arange(10, dtype=float)
rf = RollingFeatures(stats='mean', window_sizes=3)
features = rf.fit(y).transform(y)
print("transform output:", features)
assert features.shape == (1,)
# Mean of last window [7, 8, 9] = 8.0
assert float(features[0]) == 8.0

transform output: [8.]

import numpy as np
from spotforecast2_safe.preprocessing.rolling import RollingFeatures

# Multiple statistics and window sizes — feature names are
# auto-generated as roll_<stat>_<window>.
y = np.arange(10, dtype=float)
rf = RollingFeatures(
    stats=['mean', 'std', 'min', 'max'],
    window_sizes=[3, 5],
)
rf.fit(y)
print("features_names:", rf.features_names)
assert rf.features_names == [
    'roll_mean_3', 'roll_std_3', 'roll_min_3', 'roll_max_3',
    'roll_mean_5', 'roll_std_5', 'roll_min_5', 'roll_max_5',
]

features_names: ['roll_mean_3', 'roll_std_3', 'roll_min_3', 'roll_max_3', 'roll_mean_5', 'roll_std_5', 'roll_min_5', 'roll_max_5']

import numpy as np
import pandas as pd
from spotforecast2_safe.preprocessing.rolling import RollingFeatures

# Use transform_batch() with a pandas Series to preserve the index.
dates = pd.date_range('2024-01-01', periods=10, freq='D')
y_series = pd.Series(np.arange(10, dtype=float), index=dates)
rf = RollingFeatures(stats=['mean', 'max'], window_sizes=5)
features_df = rf.transform_batch(y_series)
print(features_df.head())
assert features_df.shape == (10, 2)
assert features_df.index.equals(y_series.index)

            roll_mean_5  roll_max_5
2024-01-01          NaN         NaN
2024-01-02          NaN         NaN
2024-01-03          NaN         NaN
2024-01-04          NaN         NaN
2024-01-05          2.0         4.0

import numpy as np
from spotforecast2_safe.preprocessing.rolling import RollingFeatures

# Custom feature names override the auto-generated ones.
rf = RollingFeatures(
    stats='mean',
    window_sizes=[3, 5, 7],
    features_names=['ma_3', 'ma_5', 'ma_7'],
)
rf.fit(np.arange(10, dtype=float))
print("features_names:", rf.features_names)
assert rf.features_names == ['ma_3', 'ma_5', 'ma_7']

features_names: ['ma_3', 'ma_5', 'ma_7']

Methods

Name	Description
fit	Fit the rolling features transformer (no-op).
transform	Compute rolling window statistics from time series data.
transform_batch	Compute rolling features from a pandas Series with index preservation.

fit

preprocessing.rolling.RollingFeatures.fit(X, y=None)

Fit the rolling features transformer (no-op).

This transformer does not learn any parameters from the data. Method exists for scikit-learn compatibility.

Parameters

Name	Type	Description	Default
X	Any	Time series data (not used for fitting).	required
y	Any	Target values (ignored). Defaults to None.	None

Returns

Name	Type	Description
self	RollingFeatures	Returns the fitted transformer.

Examples

import numpy as np
from spotforecast2_safe.preprocessing.rolling import RollingFeatures

rf = RollingFeatures(stats='mean', window_sizes=3)
y = np.arange(10, dtype=float)
result = rf.fit(y)
assert result is rf, "fit() must return self"
features = result.transform(y)
print("fit() returns self:", result is rf)
print("transform output:", features)

fit() returns self: True
transform output: [8.]

transform

preprocessing.rolling.RollingFeatures.transform(X)

Compute rolling window statistics from time series data.

Parameters

Name	Type	Description	Default
X	np.ndarray	Time series data as 1D or 2D numpy array.	required

Returns

Name	Type	Description
	np.ndarray	np.ndarray: Array of rolling statistics. - If X is 1D: shape (n_features,) — statistics over the last window of the series. - If X is 2D: shape (X.shape[1], n_features) — used for vectorized bootstrap.

Examples

import numpy as np
from spotforecast2_safe.preprocessing.rolling import RollingFeatures

# 1D input: returns a 1D array of shape (n_features,) with
# the statistic computed over the last window of the series.
y = np.arange(10, dtype=float)
rf = RollingFeatures(stats='mean', window_sizes=3)
out = rf.transform(y)
print("transform output:", out, "shape:", out.shape)
# Mean of last window [7, 8, 9] = 8.0
assert out.shape == (1,)
assert float(out[0]) == 8.0

transform output: [8.] shape: (1,)

transform_batch

preprocessing.rolling.RollingFeatures.transform_batch(X)

Compute rolling features from a pandas Series with index preservation.

Parameters

Name	Type	Description	Default
X	pd.Series	Time series data as a pandas Series with a datetime index.	required

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: DataFrame of rolling statistics with the same index as X and one column per (window_size, statistic) combination.

Examples

import numpy as np
import pandas as pd
from spotforecast2_safe.preprocessing.rolling import RollingFeatures

y = pd.Series(
    np.arange(20, dtype=float),
    index=pd.date_range("2024-01-01", periods=20, freq="D"),
)
rf = RollingFeatures(stats=['mean', 'std'], window_sizes=[3, 5])
df = rf.transform_batch(y)
print(df.head())
assert df.shape == (20, 4)
assert list(df.columns) == [
    'roll_mean_3', 'roll_std_3', 'roll_mean_5', 'roll_std_5',
]
assert df.index.equals(y.index)

            roll_mean_3  roll_std_3  roll_mean_5  roll_std_5
2024-01-01          NaN         NaN          NaN         NaN
2024-01-02          NaN         NaN          NaN         NaN
2024-01-03          1.0    0.816497          NaN         NaN
2024-01-04          2.0    0.816497          NaN         NaN
2024-01-05          3.0    0.816497          2.0    1.414214