polars.DataFrame.rolling

DataFrame.rolling(
    index_column: IntoExpr,
    *,
    period: str | timedelta,
    offset: str | timedelta | None = None,
    closed: ClosedInterval = 'right',
    group_by: IntoExpr | Iterable[IntoExpr] | None = None,
) → RollingGroupBy

Создаёт скользящие группы на основе столбца с временными или целочисленными значениями.

В отличие от group_by_dynamic, границы окон определяются отдельными значениями и не образуют постоянные интервалы. Для постоянных интервалов используйте DataFrame.group_by_dynamic().

Если у вас есть временной ряд <t_0, t_1, ..., t_n>, то по умолчанию будут созданы следующие окна:

• (t_0 - period, t_0]
• (t_1 - period, t_1]
• …
• (t_n - period, t_n]

если же передать значение offset, отличное от значения по умолчанию, то окна будут следующими:

• (t_0 + offset, t_0 + offset + period]
• (t_1 + offset, t_1 + offset + period]
• …
• (t_n + offset, t_n + offset + period]

Аргументы period и offset задаются либо с помощью timedelta, либо с помощью следующего строкового синтаксиса:

• 1ns (1 наносекунда)
• 1us (1 микросекунда)
• 1ms (1 миллисекунда)
• 1s (1 секунда)
• 1m (1 минута)
• 1h (1 час)
• 1d (1 календарный день)
• 1w (1 календарная неделя)
• 1mo (1 календарный месяц)
• 1q (1 календарный квартал)
• 1y (1 календарный год)
• 1i (1 индексное значение)

Их можно комбинировать: «3d12h4m25s» # 3 дня, 12 часов, 4 минуты и 25 секунд

Под «календарным днём» подразумевается соответствующее время следующего дня (который может длиться не 24 часа из-за перехода на летнее время). То же относится к «календарной неделе», «календарному месяцу», «календарному кварталу» и «календарному году».

Изменено в версии 0.20.14: Параметр by переименован в group_by.

Параметры:

index_column

Столбец, используемый для группировки по временному окну. Обычно имеет тип Date/Datetime. Значения в этом столбце должны быть отсортированы по возрастанию (или, если указан group_by, значения должны быть отсортированы по возрастанию внутри каждой группы).

При выполнении скользящей операции над индексами тип данных должен быть одним из {UInt32, UInt64, Int32, Int64}. Обратите внимание, что первые три типа временно преобразуются в Int64, поэтому, если важна производительность, используйте столбец Int64.

period

Длина окна — должна быть неотрицательной.

offset

Смещение окна. По умолчанию — -period.

closed{‘right’, ‘left’, ‘both’, ‘none’}

Задаёт, какие границы временного интервала включены.

group_by

Также группировать по этому столбцу или этим столбцам

Возвращает:

RollingGroupBy

Объект, для которого можно вызвать .agg, чтобы агрегировать данные по группам. Результат будет отсортирован по index_column (обратите внимание: если переданы столбцы group_by, сортировка будет выполняться только внутри каждой группы).

См. также

group_by_dynamic

Примеры

>>> dates = [
...     "2020-01-01 13:45:48",
...     "2020-01-01 16:42:13",
...     "2020-01-01 16:45:09",
...     "2020-01-02 18:12:48",
...     "2020-01-03 19:45:32",
...     "2020-01-08 23:16:43",
... ]
>>> df = pl.DataFrame({"dt": dates, "a": [3, 7, 5, 9, 2, 1]}).with_columns(
...     pl.col("dt").str.strptime(pl.Datetime).set_sorted()
... )
>>> out = df.rolling(index_column="dt", period="2d").agg(
...     [
...         pl.sum("a").alias("sum_a"),
...         pl.min("a").alias("min_a"),
...         pl.max("a").alias("max_a"),
...     ]
... )
>>> assert out["sum_a"].to_list() == [3, 10, 15, 24, 11, 1]
>>> assert out["max_a"].to_list() == [3, 7, 7, 9, 9, 1]
>>> assert out["min_a"].to_list() == [3, 3, 3, 3, 2, 1]
>>> out
shape: (6, 4)
┌─────────────────────┬───────┬───────┬───────┐
│ dt                  ┆ sum_a ┆ min_a ┆ max_a │
│ ---                 ┆ ---   ┆ ---   ┆ ---   │
│ datetime[μs]        ┆ i64   ┆ i64   ┆ i64   │
╞═════════════════════╪═══════╪═══════╪═══════╡
│ 2020-01-01 13:45:48 ┆ 3     ┆ 3     ┆ 3     │
│ 2020-01-01 16:42:13 ┆ 10    ┆ 3     ┆ 7     │
│ 2020-01-01 16:45:09 ┆ 15    ┆ 3     ┆ 7     │
│ 2020-01-02 18:12:48 ┆ 24    ┆ 3     ┆ 9     │
│ 2020-01-03 19:45:32 ┆ 11    ┆ 2     ┆ 9     │
│ 2020-01-08 23:16:43 ┆ 1     ┆ 1     ┆ 1     │
└─────────────────────┴───────┴───────┴───────┘

Если в period или offset используется индексное значение, оно определяется значениями в index_column:

>>> df = pl.DataFrame({"int": [0, 4, 5, 6, 8], "value": [1, 4, 2, 4, 1]})
>>> df.rolling("int", period="3i").agg(pl.col("int").alias("aggregated"))
shape: (5, 2)
┌─────┬────────────┐
│ int ┆ aggregated │
│ --- ┆ ---        │
│ i64 ┆ list[i64]  │
╞═════╪════════════╡
│ 0   ┆ [0]        │
│ 4   ┆ [4]        │
│ 5   ┆ [4, 5]     │
│ 6   ┆ [4, 5, 6]  │
│ 8   ┆ [6, 8]     │
└─────┴────────────┘

Если нужно, чтобы индексное значение определялось номером строки, можно объединить rolling с with_row_index().