polars.Expr.map_batches

Expr.map_batches(
    function: Callable[[Series],
    Series | Any],
    return_dtype: PolarsDataType | DataTypeExpr | None = None,
    *,
    agg_list: bool = False,
    is_elementwise: bool = False,
    returns_scalar: bool = False,
) → Expr

Применяет пользовательскую функцию Python ко всей Series или последовательности Series.

Предполагается, что результатом этой пользовательской функции будет Series, массив NumPy (в этом случае он будет автоматически преобразован в Series) или скалярное значение, которое будет преобразовано в Series. Если результатом является скалярное значение и вы хотите, чтобы оно осталось скалярным, передайте returns_scalar=True. Если вы хотите применять пользовательскую функцию поэлементно к отдельным значениям, см. map_elements(). Разумный сценарий использования функций map — преобразование значений, представленных выражением, с помощью сторонней библиотеки.

движок:В памятиЧастично потоковыйЧастично распределённый

Параметры:

function

Лямбда-функция или функция для применения.

return_dtype

Тип данных выходной Series.

Рекомендуется задавать его при любой возможности. Если значение равно None, тип данных пытаются определить, вызвав функцию с фиктивными данными и проверив результат.

agg_list

Сначала объединить в список при выполнении агрегации group-by.

Устарело с версии 1.32.0: Вместо этого используйте expr.implode().map_batches(..).

is_elementwise

Установите значение true, если операции выполняются поэлементно, чтобы повысить производительность и улучшить оптимизацию.

При поэлементных операциях длины всех входных данных равны единице или друг другу, поэтому их можно последовательно выполнять над срезами без изменения результатов.

returns_scalar

Если функция возвращает скалярное значение, по умолчанию оно будет обёрнуто в список в выходных данных, поскольку предполагается, что функция всегда возвращает результат, подобный Series. Чтобы сохранить результат скалярным, установите для этого аргумента значение True.

См. также

map_elements

replace

Примечания

UDF, передаваемая в map_batches, должна быть чистой, то есть не должна изменять состояние и зависеть от него, за исключением своих аргументов. Polars может вызывать функцию с произвольными входными данными.

Примеры

>>> df = pl.DataFrame(
...     {
...         "sine": [0.0, 1.0, 0.0, -1.0],
...         "cosine": [1.0, 0.0, -1.0, 0.0],
...     }
... )
>>> df.select(
...     pl.all().map_batches(
...         lambda x: x.to_numpy().argmax(),
...         returns_scalar=True,
...     )
... )
shape: (1, 2)
┌──────┬────────┐
│ sine ┆ cosine │
│ ---  ┆ ---    │
│ i64  ┆ i64    │
╞══════╪════════╡
│ 1    ┆ 0      │
└──────┴────────┘

Ниже приведён пример функции, возвращающей скалярное значение, которое мы хотим сохранить скалярным:

>>> df = pl.DataFrame(
...     {
...         "a": [0, 1, 0, 1],
...         "b": [1, 2, 3, 4],
...     }
... )
>>> df.group_by("a").agg(
...     pl.col("b").map_batches(
...         lambda x: x.max(), returns_scalar=True, return_dtype=pl.self_dtype()
...     )
... )  
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 4   │
│ 0   ┆ 3   │
└─────┴─────┘

Вызовите функцию, принимающую несколько аргументов, создав struct и обратившись к его полям внутри вызова функции.

>>> df = pl.DataFrame(
...     {
...         "a": [5, 1, 0, 3],
...         "b": [4, 2, 3, 4],
...     }
... )
>>> df.with_columns(
...     a_times_b=pl.struct("a", "b").map_batches(
...         lambda x: np.multiply(x.struct.field("a"), x.struct.field("b")),
...         return_dtype=pl.Int64,
...     )
... )
shape: (4, 3)
┌─────┬─────┬───────────┐
│ a   ┆ b   ┆ a_times_b │
│ --- ┆ --- ┆ ---       │
│ i64 ┆ i64 ┆ i64       │
╞═════╪═════╪═══════════╡
│ 5   ┆ 4   ┆ 20        │
│ 1   ┆ 2   ┆ 2         │
│ 0   ┆ 3   ┆ 0         │
│ 3   ┆ 4   ┆ 12        │
└─────┴─────┴───────────┘