polars.Series.map_elements

Series.map_elements(
    function: Callable[[Any],
    Any],
    return_dtype: PolarsDataType | None = None,
    *,
    skip_nulls: bool = True,
    _disable_inefficient_map_warning: bool = False,
) → Self

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

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

Этот метод работает значительно медленнее, чем API нативных выражений. Используйте его, только если не можете реализовать логику другим способом.

Предположим, что функция: x ↦ sqrt(x):

• Для применения функции к элементам Series рассмотрите: s.sqrt().
• Для применения функции к внутренним элементам списков рассмотрите: s.list.eval(pl.element().sqrt()).
• Для применения функции к элементам полей struct рассмотрите: s.struct.field("field_name").sqrt().

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

Реализация логики с помощью функции Python почти всегда значительно медленнее и требует больше памяти, чем реализация той же логики с помощью API нативных выражений, поскольку:

• Механизм нативных выражений работает на Rust; UDF работают на Python.
• Использование UDF на Python требует материализации DataFrame в памяти.
• Нативные выражения Polars можно выполнять параллельно (UDF, как правило, нельзя).
• Логические выражения Polars можно оптимизировать (UDF — нельзя).

Для достижения максимальной производительности всегда отдавайте предпочтение API нативных выражений, если это возможно.

Параметры:

function

Пользовательская функция или лямбда-выражение.

return_dtype

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

skip_nulls

Нулевые значения будут пропущены и не будут переданы функции Python. Это ускоряет выполнение, поскольку позволяет не вызывать Python и использовать более специализированные функции.

Возвращает:

Series

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

Если return_dtype не задан, это может привести к неожиданным результатам. Это допустимо, но считается ошибкой в запросе пользователя.

Примечания

• Если ваша функция требует больших затрат ресурсов и вы не хотите, чтобы она вызывалась для одного и того же входного значения более одного раза, рассмотрите возможность применения к ней декоратора @lru_cache. Если ваши данные подходят для этого, можно добиться значительного ускорения.
• UDF, переданная в map_elements, должна быть чистой, то есть не должна изменять состояние, отличное от её аргументов, или зависеть от него.

Примеры

>>> s = pl.Series("a", [1, 2, 3])
>>> s.map_elements(lambda x: x + 10, return_dtype=pl.Int64)  
shape: (3,)
Series: 'a' [i64]
[
    11
    12
    13
]