polars.DataFrame.group_by_dynamic

DataFrame.group_by_dynamic(
    index_column: IntoExpr,
    *,
    every: str | timedelta,
    period: str | timedelta | None = None,
    offset: str | timedelta | None = None,
    include_boundaries: bool = False,
    closed: ClosedInterval = 'left',
    label: Label = 'left',
    group_by: IntoExpr | Iterable[IntoExpr] | None = None,
    start_by: StartBy = 'window',
) → DynamicGroupBy

Группировка по значению времени (или значению индекса типа Int32, Int64).

Вычисляются временные окна, и строки распределяются по окнам. В отличие от обычной группировки, одна строка может входить в несколько групп. По умолчанию окна выглядят так:

• [start, start + period)
• [start + every, start + every + period)
• [start + 2*every, start + 2*every + period)
• …

где start определяется параметрами start_by, offset, every и самой ранней точкой данных. Подробнее см. описание аргумента start_by.

Предупреждение

Столбец индекса должен быть отсортирован по возрастанию. Если передан group_by, столбец индекса должен быть отсортирован по возрастанию в каждой группе.

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

Параметры:

index_column

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

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

every

интервал окна

period

длина окна; если значение равно None, она будет равна ‘every’

offset

смещение окна; не действует, если start_by имеет значение ‘datapoint’. По умолчанию равно нулю.

include_boundaries

Добавляет нижнюю и верхнюю границы окна в столбцы “_lower_boundary” и “_upper_boundary”. Это повлияет на производительность, поскольку усложняет распараллеливание.

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

Определяет, какие границы временного интервала включаются в него.

label{‘left’, ‘right’, ‘datapoint’}

Определяет, какую метку использовать для окна:

• ‘left’: нижняя граница окна
• ‘right’: верхняя граница окна
• ‘datapoint’: первое значение столбца индекса в данном окне. Если метка не должна располагаться на одной из границ, выберите этот вариант для максимальной производительности

group_by

Дополнительно группировать по этому столбцу или этим столбцам

start_by{‘window’, ‘datapoint’, ‘monday’, ‘tuesday’, ‘wednesday’, ‘thursday’, ‘friday’, ‘saturday’, ‘sunday’}

Стратегия определения начала первого окна.

• ‘window’: начать с самой ранней временной отметки, округлить её с помощью every, а затем прибавить offset. Обратите внимание, что недельные окна начинаются в понедельник.
• ‘datapoint’: начать с первой встреченной точки данных.

• день недели (действует, только если every содержит 'w'):

  • ‘monday’: начать окно с понедельника, предшествующего первой точке данных.
  • ‘tuesday’: начать окно со вторника, предшествующего первой точке данных.
  • …
  • ‘sunday’: начать окно с воскресенья, предшествующего первой точке данных.

  Затем полученное окно сдвигается назад, пока самая ранняя точка данных не окажется внутри него или перед ним.

Возвращает:

DynamicGroupBy

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

См. также

rolling

Примечания

1. Если вы знакомы с pandas, то

   # polars
   df.group_by_dynamic("ts", every="1d").agg(pl.col("value").sum())
   

   эквивалентно

   # pandas
   df.set_index("ts").resample("D")["value"].sum().reset_index()
   

   но обратите внимание: в отличие от pandas, polars не добавляет дополнительные строки для пустых окон. Если необходимо, чтобы index_column располагались через равные интервалы, используйте вместе с DataFrame.upsample().

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

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

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

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

   При динамической группировке по целочисленному столбцу окна определяются следующим образом:

   • “1i” # длина 1
   • “10i” # длина 10

Примеры

>>> from datetime import datetime
>>> df = pl.DataFrame(
...     {
...         "time": pl.datetime_range(
...             start=datetime(2021, 12, 16),
...             end=datetime(2021, 12, 16, 3),
...             interval="30m",
...             eager=True,
...         ),
...         "n": range(7),
...     }
... )
>>> df
shape: (7, 2)
┌─────────────────────┬─────┐
│ time                ┆ n   │
│ ---                 ┆ --- │
│ datetime[μs]        ┆ i64 │
╞═════════════════════╪═════╡
│ 2021-12-16 00:00:00 ┆ 0   │
│ 2021-12-16 00:30:00 ┆ 1   │
│ 2021-12-16 01:00:00 ┆ 2   │
│ 2021-12-16 01:30:00 ┆ 3   │
│ 2021-12-16 02:00:00 ┆ 4   │
│ 2021-12-16 02:30:00 ┆ 5   │
│ 2021-12-16 03:00:00 ┆ 6   │
└─────────────────────┴─────┘

Группировка по окнам длительностью 1 час.

>>> df.group_by_dynamic("time", every="1h", closed="right").agg(pl.col("n"))
shape: (4, 2)
┌─────────────────────┬───────────┐
│ time                ┆ n         │
│ ---                 ┆ ---       │
│ datetime[μs]        ┆ list[i64] │
╞═════════════════════╪═══════════╡
│ 2021-12-15 23:00:00 ┆ [0]       │
│ 2021-12-16 00:00:00 ┆ [1, 2]    │
│ 2021-12-16 01:00:00 ┆ [3, 4]    │
│ 2021-12-16 02:00:00 ┆ [5, 6]    │
└─────────────────────┴───────────┘

Границы окна также можно добавить в результат агрегации

>>> df.group_by_dynamic(
...     "time", every="1h", include_boundaries=True, closed="right"
... ).agg(pl.col("n").mean())
shape: (4, 4)
┌─────────────────────┬─────────────────────┬─────────────────────┬─────┐
│ _lower_boundary     ┆ _upper_boundary     ┆ time                ┆ n   │
│ ---                 ┆ ---                 ┆ ---                 ┆ --- │
│ datetime[μs]        ┆ datetime[μs]        ┆ datetime[μs]        ┆ f64 │
╞═════════════════════╪═════════════════════╪═════════════════════╪═════╡
│ 2021-12-15 23:00:00 ┆ 2021-12-16 00:00:00 ┆ 2021-12-15 23:00:00 ┆ 0.0 │
│ 2021-12-16 00:00:00 ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 00:00:00 ┆ 1.5 │
│ 2021-12-16 01:00:00 ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 01:00:00 ┆ 3.5 │
│ 2021-12-16 02:00:00 ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 02:00:00 ┆ 5.5 │
└─────────────────────┴─────────────────────┴─────────────────────┴─────┘

При closed=”left” правая граница интервала не включается в окно: [lower_bound, upper_bound)

>>> df.group_by_dynamic("time", every="1h", closed="left").agg(pl.col("n"))
shape: (4, 2)
┌─────────────────────┬───────────┐
│ time                ┆ n         │
│ ---                 ┆ ---       │
│ datetime[μs]        ┆ list[i64] │
╞═════════════════════╪═══════════╡
│ 2021-12-16 00:00:00 ┆ [0, 1]    │
│ 2021-12-16 01:00:00 ┆ [2, 3]    │
│ 2021-12-16 02:00:00 ┆ [4, 5]    │
│ 2021-12-16 03:00:00 ┆ [6]       │
└─────────────────────┴───────────┘

При closed=”both” значения времени на границах окна относятся к двум группам.

>>> df.group_by_dynamic("time", every="1h", closed="both").agg(pl.col("n"))
shape: (4, 2)
┌─────────────────────┬───────────┐
│ time                ┆ n         │
│ ---                 ┆ ---       │
│ datetime[μs]        ┆ list[i64] │
╞═════════════════════╪═══════════╡
│ 2021-12-16 00:00:00 ┆ [0, 1, 2] │
│ 2021-12-16 01:00:00 ┆ [2, 3, 4] │
│ 2021-12-16 02:00:00 ┆ [4, 5, 6] │
│ 2021-12-16 03:00:00 ┆ [6]       │
└─────────────────────┴───────────┘

Динамическую группировку также можно сочетать с группировкой по обычным ключам

>>> df = df.with_columns(groups=pl.Series(["a", "a", "a", "b", "b", "a", "a"]))
>>> df
shape: (7, 3)
┌─────────────────────┬─────┬────────┐
│ time                ┆ n   ┆ groups │
│ ---                 ┆ --- ┆ ---    │
│ datetime[μs]        ┆ i64 ┆ str    │
╞═════════════════════╪═════╪════════╡
│ 2021-12-16 00:00:00 ┆ 0   ┆ a      │
│ 2021-12-16 00:30:00 ┆ 1   ┆ a      │
│ 2021-12-16 01:00:00 ┆ 2   ┆ a      │
│ 2021-12-16 01:30:00 ┆ 3   ┆ b      │
│ 2021-12-16 02:00:00 ┆ 4   ┆ b      │
│ 2021-12-16 02:30:00 ┆ 5   ┆ a      │
│ 2021-12-16 03:00:00 ┆ 6   ┆ a      │
└─────────────────────┴─────┴────────┘
>>> df.group_by_dynamic(
...     "time",
...     every="1h",
...     closed="both",
...     group_by="groups",
...     include_boundaries=True,
... ).agg(pl.col("n"))
shape: (6, 5)
┌────────┬─────────────────────┬─────────────────────┬─────────────────────┬───────────┐
│ groups ┆ _lower_boundary     ┆ _upper_boundary     ┆ time                ┆ n         │
│ ---    ┆ ---                 ┆ ---                 ┆ ---                 ┆ ---       │
│ str    ┆ datetime[μs]        ┆ datetime[μs]        ┆ datetime[μs]        ┆ list[i64] │
╞════════╪═════════════════════╪═════════════════════╪═════════════════════╪═══════════╡
│ a      ┆ 2021-12-16 00:00:00 ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 00:00:00 ┆ [0, 1, 2] │
│ a      ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 01:00:00 ┆ [2]       │
│ a      ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 02:00:00 ┆ [5, 6]    │
│ a      ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 04:00:00 ┆ 2021-12-16 03:00:00 ┆ [6]       │
│ b      ┆ 2021-12-16 01:00:00 ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 01:00:00 ┆ [3, 4]    │
│ b      ┆ 2021-12-16 02:00:00 ┆ 2021-12-16 03:00:00 ┆ 2021-12-16 02:00:00 ┆ [4]       │
└────────┴─────────────────────┴─────────────────────┴─────────────────────┴───────────┘

Динамическая группировка по столбцу индекса

>>> df = pl.DataFrame(
...     {
...         "idx": pl.int_range(0, 6, eager=True),
...         "A": ["A", "A", "B", "B", "B", "C"],
...     }
... )
>>> (
...     df.group_by_dynamic(
...         "idx",
...         every="2i",
...         period="3i",
...         include_boundaries=True,
...         closed="right",
...     ).agg(pl.col("A").alias("A_agg_list"))
... )
shape: (4, 4)
┌─────────────────┬─────────────────┬─────┬─────────────────┐
│ _lower_boundary ┆ _upper_boundary ┆ idx ┆ A_agg_list      │
│ ---             ┆ ---             ┆ --- ┆ ---             │
│ i64             ┆ i64             ┆ i64 ┆ list[str]       │
╞═════════════════╪═════════════════╪═════╪═════════════════╡
│ -2              ┆ 1               ┆ -2  ┆ ["A", "A"]      │
│ 0               ┆ 3               ┆ 0   ┆ ["A", "B", "B"] │
│ 2               ┆ 5               ┆ 2   ┆ ["B", "B", "C"] │
│ 4               ┆ 7               ┆ 4   ┆ ["C"]           │
└─────────────────┴─────────────────┴─────┴─────────────────┘