Skip to main content

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:
NameTypeDescriptionDefault
lagintNumber of periods to offsetrequired

RollingMean

Bases: _RollingBase Rolling Mean Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformation.required
window_sizeintLength of the rolling window.required
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

RollingStd

Bases: _RollingBase Rolling Standard Deviation Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformation.required
window_sizeintLength of the rolling window.required
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

RollingMin

Bases: _RollingBase Rolling Minimum Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformation.required
window_sizeintLength of the rolling window.required
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

RollingMax

Bases: _RollingBase Rolling Maximum Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformation.required
window_sizeintLength of the rolling window.required
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf 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:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
pfloatQuantile to computerequired
window_sizeintLength of the rolling windowrequired
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

SeasonalRollingMean

Bases: _SeasonalRollingBase Seasonal rolling Mean Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
season_lengthintLength of the seasonal period, e.g. 7 for weekly datarequired
window_sizeintLength of the rolling windowrequired
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

SeasonalRollingStd

Bases: _SeasonalRollingBase Seasonal rolling Standard Deviation Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
season_lengthintLength of the seasonal period, e.g. 7 for weekly datarequired
window_sizeintLength of the rolling windowrequired
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

SeasonalRollingMin

Bases: _SeasonalRollingBase Seasonal rolling Minimum Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
season_lengthintLength of the seasonal period, e.g. 7 for weekly datarequired
window_sizeintLength of the rolling windowrequired
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

SeasonalRollingMax

Bases: _SeasonalRollingBase Seasonal rolling Maximum Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
season_lengthintLength of the seasonal period, e.g. 7 for weekly datarequired
window_sizeintLength of the rolling windowrequired
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf 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:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
pfloatQuantile to computerequired
season_lengthintLength of the seasonal period, e.g. 7 for weekly datarequired
window_sizeintLength of the rolling windowrequired
min_samplesintMinimum number of samples required to compute the statistic. If None, defaults to window_size.None
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

ExpandingMean

Bases: _ExpandingBase Expanding Mean Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

ExpandingStd

Bases: _ExpandingBase Expanding Standard Deviation Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

ExpandingMin

Bases: _ExpandingComp Expanding Minimum Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
skipnaboolIf True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation.False

ExpandingMax

Bases: _ExpandingComp Expanding Maximum Parameters:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
skipnaboolIf 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:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
pfloatQuantile to computerequired
skipnaboolIf 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:
NameTypeDescriptionDefault
lagintNumber of periods to offset by before applying the transformationrequired
alphafloatSmoothing factorrequired
skipnaboolIf True, exclude NaN values from calculations using forward-fill behavior. When False (default), NaN values propagate through the calculation.False