> ## Documentation Index
> Fetch the complete documentation index at: https://nixtlaverse.nixtla.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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.

```python theme={null}
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`

```python theme={null}
Lag(lag)
```

Bases: <code>[\_BaseLagTransform](#coreforecast.lag_transforms._BaseLagTransform)</code>

Simple lag operator

**Parameters:**

| Name  | Type                     | Description                 | Default    |
| ----- | ------------------------ | --------------------------- | ---------- |
| `lag` | <code>[int](#int)</code> | Number of periods to offset | *required* |

### `RollingMean`

Bases: <code>[\_RollingBase](#coreforecast.lag_transforms._RollingBase)</code>

Rolling Mean

**Parameters:**

| Name          | Type                       | Description                                                                                                        | Default            |
| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`         | <code>[int](#int)</code>   | Number of periods to offset by before applying the transformation.                                                 | *required*         |
| `window_size` | <code>[int](#int)</code>   | Length of the rolling window.                                                                                      | *required*         |
| `min_samples` | <code>[int](#int)</code>   | Minimum number of samples required to compute the statistic. If None, defaults to window\_size.                    | <code>None</code>  |
| `skipna`      | <code>[bool](#bool)</code> | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `RollingStd`

Bases: <code>[\_RollingBase](#coreforecast.lag_transforms._RollingBase)</code>

Rolling Standard Deviation

**Parameters:**

| Name          | Type                       | Description                                                                                                        | Default            |
| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`         | <code>[int](#int)</code>   | Number of periods to offset by before applying the transformation.                                                 | *required*         |
| `window_size` | <code>[int](#int)</code>   | Length of the rolling window.                                                                                      | *required*         |
| `min_samples` | <code>[int](#int)</code>   | Minimum number of samples required to compute the statistic. If None, defaults to window\_size.                    | <code>None</code>  |
| `skipna`      | <code>[bool](#bool)</code> | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `RollingMin`

Bases: <code>[\_RollingBase](#coreforecast.lag_transforms._RollingBase)</code>

Rolling Minimum

**Parameters:**

| Name          | Type                       | Description                                                                                                        | Default            |
| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`         | <code>[int](#int)</code>   | Number of periods to offset by before applying the transformation.                                                 | *required*         |
| `window_size` | <code>[int](#int)</code>   | Length of the rolling window.                                                                                      | *required*         |
| `min_samples` | <code>[int](#int)</code>   | Minimum number of samples required to compute the statistic. If None, defaults to window\_size.                    | <code>None</code>  |
| `skipna`      | <code>[bool](#bool)</code> | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `RollingMax`

Bases: <code>[\_RollingBase](#coreforecast.lag_transforms._RollingBase)</code>

Rolling Maximum

**Parameters:**

| Name          | Type                       | Description                                                                                                        | Default            |
| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`         | <code>[int](#int)</code>   | Number of periods to offset by before applying the transformation.                                                 | *required*         |
| `window_size` | <code>[int](#int)</code>   | Length of the rolling window.                                                                                      | *required*         |
| `min_samples` | <code>[int](#int)</code>   | Minimum number of samples required to compute the statistic. If None, defaults to window\_size.                    | <code>None</code>  |
| `skipna`      | <code>[bool](#bool)</code> | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `RollingQuantile`

```python theme={null}
RollingQuantile(lag, p, window_size, min_samples=None, skipna=False)
```

Bases: <code>[\_RollingBase](#coreforecast.lag_transforms._RollingBase)</code>

Rolling quantile

**Parameters:**

| Name          | Type                         | Description                                                                                                        | Default            |
| ------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`         | <code>[int](#int)</code>     | Number of periods to offset by before applying the transformation                                                  | *required*         |
| `p`           | <code>[float](#float)</code> | Quantile to compute                                                                                                | *required*         |
| `window_size` | <code>[int](#int)</code>     | Length of the rolling window                                                                                       | *required*         |
| `min_samples` | <code>[int](#int)</code>     | Minimum number of samples required to compute the statistic. If None, defaults to window\_size.                    | <code>None</code>  |
| `skipna`      | <code>[bool](#bool)</code>   | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `SeasonalRollingMean`

Bases: <code>[\_SeasonalRollingBase](#coreforecast.lag_transforms._SeasonalRollingBase)</code>

Seasonal rolling Mean

**Parameters:**

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

### `SeasonalRollingStd`

Bases: <code>[\_SeasonalRollingBase](#coreforecast.lag_transforms._SeasonalRollingBase)</code>

Seasonal rolling Standard Deviation

**Parameters:**

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

### `SeasonalRollingMin`

Bases: <code>[\_SeasonalRollingBase](#coreforecast.lag_transforms._SeasonalRollingBase)</code>

Seasonal rolling Minimum

**Parameters:**

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

### `SeasonalRollingMax`

Bases: <code>[\_SeasonalRollingBase](#coreforecast.lag_transforms._SeasonalRollingBase)</code>

Seasonal rolling Maximum

**Parameters:**

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

### `SeasonalRollingQuantile`

```python theme={null}
SeasonalRollingQuantile(lag, p, season_length, window_size, min_samples=None, skipna=False)
```

Bases: <code>[\_SeasonalRollingBase](#coreforecast.lag_transforms._SeasonalRollingBase)</code>

Seasonal rolling statistic

**Parameters:**

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

### `ExpandingMean`

Bases: <code>[\_ExpandingBase](#coreforecast.lag_transforms._ExpandingBase)</code>

Expanding Mean

**Parameters:**

| Name     | Type                       | Description                                                                                                        | Default            |
| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`    | <code>[int](#int)</code>   | Number of periods to offset by before applying the transformation                                                  | *required*         |
| `skipna` | <code>[bool](#bool)</code> | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `ExpandingStd`

Bases: <code>[\_ExpandingBase](#coreforecast.lag_transforms._ExpandingBase)</code>

Expanding Standard Deviation

**Parameters:**

| Name     | Type                       | Description                                                                                                        | Default            |
| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`    | <code>[int](#int)</code>   | Number of periods to offset by before applying the transformation                                                  | *required*         |
| `skipna` | <code>[bool](#bool)</code> | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `ExpandingMin`

Bases: <code>[\_ExpandingComp](#coreforecast.lag_transforms._ExpandingComp)</code>

Expanding Minimum

**Parameters:**

| Name     | Type                       | Description                                                                                                        | Default            |
| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`    | <code>[int](#int)</code>   | Number of periods to offset by before applying the transformation                                                  | *required*         |
| `skipna` | <code>[bool](#bool)</code> | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `ExpandingMax`

Bases: <code>[\_ExpandingComp](#coreforecast.lag_transforms._ExpandingComp)</code>

Expanding Maximum

**Parameters:**

| Name     | Type                       | Description                                                                                                        | Default            |
| -------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`    | <code>[int](#int)</code>   | Number of periods to offset by before applying the transformation                                                  | *required*         |
| `skipna` | <code>[bool](#bool)</code> | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `ExpandingQuantile`

```python theme={null}
ExpandingQuantile(lag, p, skipna=False)
```

Bases: <code>[\_BaseLagTransform](#coreforecast.lag_transforms._BaseLagTransform)</code>

Expanding quantile

**Parameters:**

| Name     | Type                         | Description                                                                                                        | Default            |
| -------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------ |
| `lag`    | <code>[int](#int)</code>     | Number of periods to offset by before applying the transformation                                                  | *required*         |
| `p`      | <code>[float](#float)</code> | Quantile to compute                                                                                                | *required*         |
| `skipna` | <code>[bool](#bool)</code>   | If True, exclude NaN values from calculations. When False (default), NaN values propagate through the calculation. | <code>False</code> |

### `ExponentiallyWeightedMean`

```python theme={null}
ExponentiallyWeightedMean(lag, alpha, skipna=False)
```

Bases: <code>[\_BaseLagTransform](#coreforecast.lag_transforms._BaseLagTransform)</code>

Exponentially weighted mean

**Parameters:**

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