Lag transformations | CoreForecast

Compute lag transforms

Overview

Lag transforms allow you to compute lagged features and rolling statistics over grouped time series data. All transforms work with the GroupedArray structure and provide both transform() and update() methods for batch processing and incremental updates.

Basic Example

import numpy as np
from coreforecast.grouped_array import GroupedArray
from coreforecast.lag_transforms import Lag, RollingMean

# Create sample data: two time series
data = np.array([1.0, 2.0, 3.0, 4.0, 5.0, 10.0, 20.0, 30.0])
indptr = np.array([0, 5, 8])  # First series: 5 elements, second: 3 elements
ga = GroupedArray(data, indptr)

# Simple lag
lag2 = Lag(lag=2)
lagged = lag2.transform(ga)

# Rolling mean with lag
rolling_mean = RollingMean(lag=1, window_size=3)
rolling = rolling_mean.transform(ga)

Rolling Window Examples

Rolling window operations compute statistics over a sliding window of observations.

import numpy as np
from coreforecast.grouped_array import GroupedArray
from coreforecast.lag_transforms import (
    RollingMean, RollingStd, RollingMin, RollingMax, RollingQuantile
)

# Sample time series data
data = np.array([10.0, 12.0, 15.0, 14.0, 18.0, 20.0, 22.0, 19.0])
indptr = np.array([0, 8])
ga = GroupedArray(data, indptr)

# Rolling mean with window size 3, lag 1
rolling_mean = RollingMean(lag=1, window_size=3)
mean_result = rolling_mean.transform(ga)
# Computes mean of last 3 values with lag 1

# Rolling standard deviation
rolling_std = RollingStd(lag=1, window_size=3, min_samples=2)
std_result = rolling_std.transform(ga)

# Rolling minimum and maximum
rolling_min = RollingMin(lag=1, window_size=3)
rolling_max = RollingMax(lag=1, window_size=3)
min_result = rolling_min.transform(ga)
max_result = rolling_max.transform(ga)

# Rolling median (50th percentile)
rolling_median = RollingQuantile(lag=1, p=0.5, window_size=3)
median_result = rolling_median.transform(ga)

Seasonal Rolling Examples

Seasonal rolling operations compute statistics over windows that respect seasonality patterns.

import numpy as np
from coreforecast.grouped_array import GroupedArray
from coreforecast.lag_transforms import (
    SeasonalRollingMean, SeasonalRollingStd, SeasonalRollingMin,
    SeasonalRollingMax, SeasonalRollingQuantile
)

# Daily data with weekly seasonality (14 days)
data = np.array([10.0, 15.0, 12.0, 18.0, 20.0, 22.0, 25.0,
                 11.0, 16.0, 13.0, 19.0, 21.0, 23.0, 26.0])
indptr = np.array([0, 14])
ga = GroupedArray(data, indptr)

# Seasonal rolling mean with weekly pattern
seasonal_mean = SeasonalRollingMean(
    lag=1,
    season_length=7,  # Weekly seasonality
    window_size=2     # Use last 2 seasonal observations
)
seasonal_result = seasonal_mean.transform(ga)
# Computes mean using observations from the same day of week

# Seasonal rolling std
seasonal_std = SeasonalRollingStd(lag=1, season_length=7, window_size=2)
seasonal_std_result = seasonal_std.transform(ga)

# Seasonal rolling min/max
seasonal_min = SeasonalRollingMin(lag=1, season_length=7, window_size=2)
seasonal_max = SeasonalRollingMax(lag=1, season_length=7, window_size=2)

# Seasonal rolling quantile
seasonal_q90 = SeasonalRollingQuantile(
    lag=1, p=0.9, season_length=7, window_size=2
)

Expanding Window Examples

Expanding windows compute cumulative statistics from the start of each series.

import numpy as np
from coreforecast.grouped_array import GroupedArray
from coreforecast.lag_transforms import (
    ExpandingMean, ExpandingStd, ExpandingMin, ExpandingMax, ExpandingQuantile
)

# Sample data: two time series
data = np.array([5.0, 10.0, 8.0, 12.0, 15.0, 20.0, 25.0, 30.0])
indptr = np.array([0, 5, 8])
ga = GroupedArray(data, indptr)

# Expanding mean (cumulative average)
exp_mean = ExpandingMean(lag=1)
cumulative_avg = exp_mean.transform(ga)
# Each value is the mean of all previous observations

# Expanding standard deviation
exp_std = ExpandingStd(lag=1)
cumulative_std = exp_std.transform(ga)

# Expanding min and max
exp_min = ExpandingMin(lag=1)
exp_max = ExpandingMax(lag=1)
running_min = exp_min.transform(ga)
running_max = exp_max.transform(ga)

# Expanding quantile
exp_median = ExpandingQuantile(lag=1, p=0.5)
running_median = exp_median.transform(ga)

Exponentially Weighted Mean Example

The exponentially weighted mean gives more weight to recent observations.

import numpy as np
from coreforecast.grouped_array import GroupedArray
from coreforecast.lag_transforms import ExponentiallyWeightedMean

# Sample data
data = np.array([10.0, 12.0, 15.0, 14.0, 18.0, 20.0])
indptr = np.array([0, 6])
ga = GroupedArray(data, indptr)

# Exponentially weighted mean with alpha=0.3
# Higher alpha = more weight to recent values
ewm = ExponentiallyWeightedMean(lag=1, alpha=0.3)
smoothed = ewm.transform(ga)

Update Method for Incremental Processing

All transforms provide an update() method for efficient incremental computation when new data arrives.

import numpy as np
from coreforecast.grouped_array import GroupedArray
from coreforecast.lag_transforms import ExpandingMean

# Initial data
data = np.array([1.0, 2.0, 3.0, 4.0, 5.0])
indptr = np.array([0, 5])
ga = GroupedArray(data, indptr)

# Transform to initialize statistics
exp_mean = ExpandingMean(lag=1)
result = exp_mean.transform(ga)

# New observation arrives
new_data = np.array([6.0])
new_indptr = np.array([0, 1])
new_ga = GroupedArray(new_data, new_indptr)

# Update statistics incrementally (much faster than re-transforming)
updated_value = exp_mean.update(new_ga)
# Returns the updated expanding mean for the new observation

Available lag transformations

Lag

Lag(lag)

Bases: _BaseLagTransform

Simple lag operator

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset	required

RollingMean

Bases: _RollingBase

Rolling Mean

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation.	required
window_size	int	Length of the rolling window.	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

RollingStd

Bases: _RollingBase

Rolling Standard Deviation

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation.	required
window_size	int	Length of the rolling window.	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

RollingMin

Bases: _RollingBase

Rolling Minimum

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation.	required
window_size	int	Length of the rolling window.	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

RollingMax

Bases: _RollingBase

Rolling Maximum

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation.	required
window_size	int	Length of the rolling window.	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

RollingQuantile

RollingQuantile(lag, p, window_size, min_samples=None, skipna=False)

Bases: _RollingBase

Rolling quantile

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
p	float	Quantile to compute	required
window_size	int	Length of the rolling window	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

SeasonalRollingMean

Bases: _SeasonalRollingBase

Seasonal rolling Mean

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
season_length	int	Length of the seasonal period, e.g. 7 for weekly data	required
window_size	int	Length of the rolling window	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

SeasonalRollingStd

Bases: _SeasonalRollingBase

Seasonal rolling Standard Deviation

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
season_length	int	Length of the seasonal period, e.g. 7 for weekly data	required
window_size	int	Length of the rolling window	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

SeasonalRollingMin

Bases: _SeasonalRollingBase

Seasonal rolling Minimum

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
season_length	int	Length of the seasonal period, e.g. 7 for weekly data	required
window_size	int	Length of the rolling window	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

SeasonalRollingMax

Bases: _SeasonalRollingBase

Seasonal rolling Maximum

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
season_length	int	Length of the seasonal period, e.g. 7 for weekly data	required
window_size	int	Length of the rolling window	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

SeasonalRollingQuantile

SeasonalRollingQuantile(lag, p, season_length, window_size, min_samples=None, skipna=False)

Bases: _SeasonalRollingBase

Seasonal rolling statistic

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
p	float	Quantile to compute	required
season_length	int	Length of the seasonal period, e.g. 7 for weekly data	required
window_size	int	Length of the rolling window	required
min_samples	int	Minimum number of samples required to compute the statistic. If None, defaults to window_size.	None
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

ExpandingMean

Bases: _ExpandingBase

Expanding Mean

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

ExpandingStd

Bases: _ExpandingBase

Expanding Standard Deviation

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

ExpandingMin

Bases: _ExpandingComp

Expanding Minimum

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

ExpandingMax

Bases: _ExpandingComp

Expanding Maximum

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

ExpandingQuantile

ExpandingQuantile(lag, p, skipna=False)

Bases: _BaseLagTransform

Expanding quantile

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
p	float	Quantile to compute	required
skipna	bool	If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.	False

ExponentiallyWeightedMean

ExponentiallyWeightedMean(lag, alpha, skipna=False)

Bases: _BaseLagTransform

Exponentially weighted mean

Parameters:

Name	Type	Description	Default
lag	int	Number of periods to offset by before applying the transformation	required
alpha	float	Smoothing factor	required
skipna	bool	If True, exclude NaN values from calculations using forward-fill behavior. When False (default), NaN values propagate through the calculation.	False