Lag transformations | CoreForecast

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`

​Overview

​Basic Example

​Rolling Window Examples

​Seasonal Rolling Examples

​Expanding Window Examples

​Exponentially Weighted Mean Example

​Update Method for Incremental Processing

​Available lag transformations

​Lag

​RollingMean

​RollingStd

​RollingMin

​RollingMax

​RollingQuantile

​SeasonalRollingMean

​SeasonalRollingStd

​SeasonalRollingMin

​SeasonalRollingMax

​SeasonalRollingQuantile

​ExpandingMean

​ExpandingStd

​ExpandingMin

​ExpandingMax

​ExpandingQuantile

​ExponentiallyWeightedMean