Выражения

На этой странице представлен обзор всех публичных выражений Polars.

class polars.Expr

Выражения, которые можно использовать в различных контекстах.

Методы:

`abs`	Вычислить абсолютные значения.
`add`	Метод, эквивалентный оператору сложения `expr + other`.
`agg_groups`	Получить индексы групп для операции группировки.
`alias`	Переименовать выражение.
`all`	Вернуть, являются ли все значения столбца `True`.
`and_`	Метод, эквивалентный побитовому оператору «И» `expr & other & ...`.
`any`	Вернуть, есть ли в столбце значения `True`.
`append`	Добавить выражения.
`approx_n_unique`	Приблизительное количество уникальных значений.
`arccos`	Вычислить поэлементное значение арккосинуса.
`arccosh`	Вычислить поэлементное значение обратного гиперболического косинуса.
`arcsin`	Вычислить поэлементное значение арксинуса.
`arcsinh`	Вычислить поэлементное значение обратного гиперболического синуса.
`arctan`	Вычислить поэлементное значение арктангенса.
`arctanh`	Вычислить поэлементное значение обратного гиперболического тангенса.
`arg_max`	Получить индекс максимального значения.
`arg_min`	Получить индекс минимального значения.
`arg_sort`	Получить значения индексов, которые задают порядок сортировки этого столбца.
`arg_true`	Вернуть индексы, для которых выражение принимает значение `True`.
`arg_unique`	Получить индекс первого уникального значения.
`backward_fill`	Заполнить пропущенные значения следующим ненулевым значением.
`bitwise_and`	Выполнить агрегацию побитовых операций И.
`bitwise_count_ones`	Вычислить количество установленных битов.
`bitwise_count_zeros`	Вычислить количество сброшенных битов.
`bitwise_leading_ones`	Вычислить количество старших установленных битов до первого сброшенного бита.
`bitwise_leading_zeros`	Вычислить количество старших сброшенных битов до первого установленного бита.
`bitwise_or`	Выполнить агрегацию побитовых операций ИЛИ.
`bitwise_trailing_ones`	Вычислить количество младших установленных битов до первого сброшенного бита.
`bitwise_trailing_zeros`	Вычислить количество младших сброшенных битов до первого установленного бита.
`bitwise_xor`	Выполнить агрегацию побитовых операций исключающего ИЛИ.
`bottom_k`	Вернуть `k` наименьших элементов.
`bottom_k_by`	Вернуть элементы, соответствующие `k` наименьшим элементам столбца (столбцов) `by`.
`cast`	Преобразовать один тип данных в другой.
`cbrt`	Вычислить кубический корень элементов.
`ceil`	Округлить вверх до ближайшего целого значения.
`clip`	Заменить значения за заданными границами значениями границ.
`cos`	Вычислить поэлементное значение косинуса.
`cosh`	Вычислить поэлементное значение гиперболического косинуса.
`cot`	Вычислить поэлементное значение котангенса.
`count`	Вернуть количество ненулевых элементов в столбце.
`cum_count`	Вернуть накопительное количество ненулевых значений в столбце.
`cum_max`	Получить массив с накопительным максимумом, вычисленным для каждого элемента.
`cum_min`	Получить массив с накопительным минимумом, вычисленным для каждого элемента.
`cum_prod`	Получить массив с накопительным произведением, вычисленным для каждого элемента.
`cum_sum`	Получить массив с накопительной суммой, вычисленной для каждого элемента.
`cumulative_eval`	Вычислить выражение в скользящем окне, которое при каждой итерации увеличивается на `1` позицию.
`cut`	Разбить непрерывные значения на дискретные категории.
`degrees`	Преобразовать радианы в градусы.
`deserialize`	Прочитать сериализованное выражение из файла.
`diff`	Вычислить первую дискретную разность между сдвинутыми элементами.
`dot`	Вычислить скалярное произведение двух выражений.
`drop_nans`	Удалить все значения NaN с плавающей запятой.
`drop_nulls`	Удалить все значения null.
`entropy`	Вычислить энтропию.
`eq`	Метод, эквивалентный оператору равенства `expr == other`.
`eq_missing`	Метод, эквивалентный оператору равенства `expr == other`, где `None == None`.
`ewm_mean`	Вычислить экспоненциально взвешенное скользящее среднее.
`ewm_mean_by`	Вычислить экспоненциально взвешенное скользящее среднее на основе времени.
`ewm_std`	Вычислить экспоненциально взвешенное скользящее стандартное отклонение.
`ewm_sum`	Вычислить экспоненциально взвешенную скользящую сумму.
`ewm_sum_by`	Вычислить экспоненциально взвешенную скользящую сумму на основе времени.
`ewm_var`	Вычислить экспоненциально взвешенную скользящую дисперсию.
`exclude`	Исключить столбцы из выражения для нескольких столбцов.
`exp`	Вычислить экспоненту поэлементно.
`explode`	Развернуть выражение списка.
`extend_constant`	Очень быстрый метод расширения Series на 'n' копий значения.
`fill_nan`	Заполнить значение NaN с плавающей запятой заданным значением.
`fill_null`	Заполнить значения null заданным значением или стратегией.
`filter`	Отфильтровать выражение по одному или нескольким выражениям-предикатам.
`first`	Получить первое значение.
`flatten`	Преобразовать столбец-список или строковый столбец в плоский вид.
`floor`	Округлить вниз до ближайшего целого значения.
`floordiv`	Метод, эквивалентный оператору целочисленного деления `expr // other`.
`forward_fill`	Заполнить пропущенные значения последним ненулевым значением.
`from_json`	Прочитать выражение из строки в формате JSON и создать Expression.
`gather`	Получить значения по индексам.
`gather_every`	Получить каждое n-е значение Series и вернуть их в виде новой Series.
`ge`	Метод, эквивалентный оператору «больше или равно» `expr >= other`.
`get`	Вернуть одно значение по индексу.
`gt`	Метод, эквивалентный оператору «больше» `expr > other`.
`has_nulls`	Проверить, содержит ли выражение одно или несколько значений null.
`hash`	Вычислить хеш элементов в выборке.
`head`	Получить первые `n` строк.
`hist`	Распределить значения по интервалам и подсчитать количество вхождений.
`implode`	Собрать значения в список.
`index_of`	Получить индекс первого вхождения значения или `None`, если оно не найдено.
`inspect`	Вывести значение, которое вычисляет это выражение, и передать его дальше.
`interpolate`	Интерполировать промежуточные значения.
`interpolate_by`	Заполнить значения null интерполяцией на основе другого столбца.
`is_between`	Проверить, находится ли это выражение между заданными нижней и верхней границами.
`is_close`	Проверить, близко ли это выражение к другому, то есть почти равно ли ему.
`is_duplicated`	Вернуть булеву маску, указывающую на повторяющиеся значения.
`is_empty`	Вернуть, является ли столбец пустым.
`is_finite`	Вернуть булеву Series, указывающую, какие значения являются конечными.
`is_first_distinct`	Вернуть булеву маску, указывающую на первое вхождение каждого уникального значения.
`is_in`	Проверить, присутствуют ли элементы этого выражения в другой Series.
`is_infinite`	Вернуть булеву Series, указывающую, какие значения являются бесконечными.
`is_last_distinct`	Вернуть булеву маску, указывающую на последнее вхождение каждого уникального значения.
`is_nan`	Вернуть булеву Series, указывающую, какие значения являются NaN.
`is_not_nan`	Вернуть булеву Series, указывающую, какие значения не являются NaN.
`is_not_null`	Вернуть булеву Series, указывающую, какие значения не равны null.
`is_null`	Вернуть булеву Series, указывающую, какие значения равны null.
`is_sorted`	Проверить, отсортировано ли выражение.
`is_unique`	Получить маску уникальных значений.
`item`	Получить единственное значение.
`kurtosis`	Вычислить эксцесс набора данных (по Фишеру или Пирсону).
`last`	Получить последнее значение.
`le`	Метод, эквивалентный оператору «меньше или равно» `expr <= other`.
`len`	Вернуть количество элементов в столбце.
`limit`	Получить первые `n` строк (синоним `Expr.head()`).
`log`	Вычислить логарифм по заданному основанию.
`log10`	Вычислить десятичный логарифм входного массива поэлементно.
`log1p`	Вычислить натуральный логарифм каждого элемента, увеличенного на единицу.
`lower_bound`	Вычислить нижнюю границу.
`lt`	Метод, эквивалентный оператору «меньше» `expr < other`.
`map_batches`	Применить пользовательскую функцию Python ко всей Series или последовательности Series.
`map_elements`	Применить пользовательскую функцию (UDF) к каждому элементу столбца.
`max`	Получить максимальное значение.
`max_by`	Получить максимальное значение, упорядоченное по другому выражению.
`mean`	Получить среднее значение.
`median`	Получить медианное значение с помощью линейной интерполяции.
`min`	Получить минимальное значение.
`min_by`	Получить минимальное значение, упорядоченное по другому выражению.
`mod`	Метод, эквивалентный оператору взятия остатка `expr % other`.
`mode`	Вычислить наиболее часто встречающееся значение (значения).
`mul`	Метод, эквивалентный оператору умножения `expr * other`.
`n_unique`	Подсчитать уникальные значения.
`nan_max`	Получить максимальное значение, распространяя/сохраняя обнаруженные значения NaN.
`nan_min`	Получить минимальное значение, распространяя/сохраняя обнаруженные значения NaN.
`ne`	Метод, эквивалентный оператору неравенства `expr != other`.
`ne_missing`	Метод, эквивалентный оператору равенства `expr != other`, где `None == None`.
`neg`	Метод, эквивалентный унарному оператору минуса `-expr`.
`not_`	Метод, эквивалентный побитовому оператору «НЕ» `~expr`.

`null_count`	Подсчитать значения null.
`or_`	Эквивалент метода для побитового оператора «или» `expr \| other \| ...`.
`over`	Вычислить выражения для заданных групп.
`pct_change`	Вычислить процентное изменение между значениями.
`peak_max`	Получить булеву маску локальных максимумов.
`peak_min`	Получить булеву маску локальных минимумов.
`pipe`	Предоставляет структурированный способ применения последовательности пользовательских функций (UDF).
`pow`	Эквивалент метода для оператора возведения в степень `expr ** exponent`.
`product`	Вычислить произведение выражения.
`qcut`	Разбить непрерывные значения на дискретные категории на основе их квантилей.
`quantile`	Получить значение квантиля.
`radians`	Преобразовать градусы в радианы.
`rank`	Присвоить данным ранги с корректной обработкой совпадений.
`rechunk`	Создать единый блок памяти для этого Series.
`register_plugin`	Зарегистрировать функцию плагина.
`reinterpret`	Интерпретировать базовые биты как знаковое/беззнаковое целое число или число с плавающей запятой.
`repeat_by`	Повторить элементы этого Series в соответствии с заданным выражением.
`replace`	Заменить заданные значения другими значениями того же типа данных.
`replace_strict`	Заменить все значения другими значениями.
`reshape`	Изменить форму этого Expr, преобразовав его в плоский столбец или столбец Array.
`reverse`	Обратить порядок выборки.
`rle`	Сжать данные столбца с помощью кодирования длин серий.
`rle_id`	Получить отдельный целочисленный идентификатор для каждой серии одинаковых значений.
`rolling`	Создать скользящие группы на основе столбца с временными или целочисленными значениями.
`rolling_kurtosis`	Вычислить скользящий эксцесс.
`rolling_map`	Вычислить пользовательскую функцию для скользящего окна.
`rolling_max`	Вычислить скользящий максимум (максимум в движущемся окне) для значений этого массива.
`rolling_max_by`	Вычислить скользящий максимум на основе другого столбца.
`rolling_mean`	Вычислить скользящее среднее (среднее в движущемся окне) для значений этого массива.
`rolling_mean_by`	Вычислить скользящее среднее на основе другого столбца.
`rolling_median`	Вычислить скользящую медиану.
`rolling_median_by`	Вычислить скользящую медиану на основе другого столбца.
`rolling_min`	Вычислить скользящий минимум (минимум в движущемся окне) для значений этого массива.
`rolling_min_by`	Вычислить скользящий минимум на основе другого столбца.
`rolling_quantile`	Вычислить скользящий квантиль.
`rolling_quantile_by`	Вычислить скользящий квантиль на основе другого столбца.
`rolling_rank`	Вычислить скользящий ранг.
`rolling_rank_by`	Вычислить скользящий ранг на основе другого столбца.
`rolling_skew`	Вычислить скользящую асимметрию.
`rolling_std`	Вычислить скользящее стандартное отклонение.
`rolling_std_by`	Вычислить скользящее стандартное отклонение на основе другого столбца.
`rolling_sum`	Вычислить скользящую сумму (сумму в движущемся окне) для значений этого массива.
`rolling_sum_by`	Вычислить скользящую сумму на основе другого столбца.
`rolling_var`	Вычислить скользящую дисперсию.
`rolling_var_by`	Вычислить скользящую дисперсию на основе другого столбца.
`round`	Округлить базовые данные с плавающей запятой до `decimals` знаков.
`round_sig_figs`	Округлить до заданного числа значащих цифр.
`sample`	Выполнить выборку из этого выражения.
`search_sorted`	Найти индексы, куда следует вставить элементы, чтобы сохранить порядок.
`set_sorted`	Пометить выражение как «отсортированное».
`shift`	Сдвинуть значения на заданное количество индексов.
`shrink_dtype`	Уменьшить разрядность числовых столбцов до минимально необходимого типа данных.
`shuffle`	Перемешать содержимое этого выражения.
`sign`	Поэлементно вычислить знак для числовых типов.
`sin`	Поэлементно вычислить синус.
`sinh`	Поэлементно вычислить гиперболический синус.
`skew`	Вычислить выборочную асимметрию набора данных.
`slice`	Получить срез этого выражения.
`sort`	Отсортировать этот столбец.
`sort_by`	Отсортировать этот столбец в соответствии с порядком других столбцов.
`sqrt`	Вычислить квадратный корень элементов.
`std`	Получить стандартное отклонение.
`sub`	Эквивалент метода для оператора вычитания `expr - other`.
`sum`	Получить сумму.
`tail`	Получить последние `n` строк.
`tan`	Поэлементно вычислить тангенс.
`tanh`	Поэлементно вычислить гиперболический тангенс.
`to_physical`	Преобразовать в физическое представление логического типа данных.
`top_k`	Вернуть `k` наибольших элементов.
`top_k_by`	Вернуть элементы, соответствующие `k` наибольшим элементам столбца (столбцов) `by`.
`truediv`	Эквивалент метода для оператора деления с плавающей запятой `expr / other`.
`truncate`	Округлить числовые данные к нулю до `decimals` знаков после запятой.
`unique`	Получить уникальные значения этого выражения.
`unique_counts`	Вернуть количество уникальных значений в порядке их появления.
`upper_bound`	Вычислить верхнюю границу.
`value_counts`	Подсчитать количество вхождений уникальных значений.
`var`	Получить дисперсию.
`where`	Отфильтровать один столбец.
`xor`	Эквивалент метода для побитового оператора исключающего «или» `expr ^ other`.

abs() → Expr

Вычислить абсолютные значения.

То же, что и abs(expr).

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "A": [-1.0, 0.0, 1.0, 2.0],
...     }
... )
>>> df.select(pl.col("A").abs())
shape: (4, 1)
┌─────┐
│ A   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
│ 0.0 │
│ 1.0 │
│ 2.0 │
└─────┘

add(
    other: Any,
) → Expr

Эквивалент метода для оператора сложения expr + other.

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

Параметры:

other: Числовое значение или строка; принимает выражение в качестве входных данных.

Примеры

>>> df = pl.DataFrame({"x": [1, 2, 3, 4, 5]})
>>> df.with_columns(
...     pl.col("x").add(2).alias("x+int"),
...     pl.col("x").add(pl.col("x").cum_prod()).alias("x+expr"),
... )
shape: (5, 3)
┌─────┬───────┬────────┐
│ x   ┆ x+int ┆ x+expr │
│ --- ┆ ---   ┆ ---    │
│ i64 ┆ i64   ┆ i64    │
╞═════╪═══════╪════════╡
│ 1   ┆ 3     ┆ 2      │
│ 2   ┆ 4     ┆ 4      │
│ 3   ┆ 5     ┆ 9      │
│ 4   ┆ 6     ┆ 28     │
│ 5   ┆ 7     ┆ 125    │
└─────┴───────┴────────┘

>>> df = pl.DataFrame(
...     {"x": ["a", "d", "g"], "y": ["b", "e", "h"], "z": ["c", "f", "i"]}
... )
>>> df.with_columns(pl.col("x").add(pl.col("y")).add(pl.col("z")).alias("xyz"))
shape: (3, 4)
┌─────┬─────┬─────┬─────┐
│ x   ┆ y   ┆ z   ┆ xyz │
│ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ str ┆ str ┆ str │
╞═════╪═════╪═════╪═════╡
│ a   ┆ b   ┆ c   ┆ abc │
│ d   ┆ e   ┆ f   ┆ def │
│ g   ┆ h   ┆ i   ┆ ghi │
└─────┴─────┴─────┴─────┘

agg_groups() → Expr

Получить индексы групп для операции группировки.

Устарело с версии 1.35: используйте вместо этого df.with_row_index().group_by(...).agg(pl.col('index')). Этот метод будет удалён в Polars 2.0.

Следует использовать только в контексте агрегации.

Примеры

>>> import warnings
>>> warnings.filterwarnings("ignore", category=DeprecationWarning)
>>> df = pl.DataFrame(
...     {
...         "group": [
...             "one",
...             "one",
...             "one",
...             "two",
...             "two",
...             "two",
...         ],
...         "value": [94, 95, 96, 97, 97, 99],
...     }
... )
>>> df.group_by("group", maintain_order=True).agg(pl.col("value").agg_groups())
shape: (2, 2)
┌───────┬───────────┐
│ group ┆ value     │
│ ---   ┆ ---       │
│ str   ┆ list[u32] │
╞═══════╪═══════════╡
│ one   ┆ [0, 1, 2] │
│ two   ┆ [3, 4, 5] │
└───────┴───────────┘

Новый рекомендуемый подход: >>> ( … df.with_row_index() … .group_by(“group”, maintain_order=True) … .agg(pl.col(“index”)) … ) shape: (2, 2) ┌───────┬───────────┐ │ group ┆ index │ │ — ┆ — │ │ str ┆ list[u32] │ ╞═══════╪═══════════╡ │ one ┆ [0, 1, 2] │ │ two ┆ [3, 4, 5] │ └───────┴───────────┘

alias(
    name: str_,
) → Expr

Переименовать выражение.

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

Параметры:

name: Новое имя.

См. также

name.map
name.prefix
name.suffix

Примеры

Переименовать выражение, чтобы не перезаписать существующий столбец.

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": ["x", "y", "z"],
...     }
... )
>>> df.with_columns(
...     pl.col("a") + 10,
...     pl.col("b").str.to_uppercase().alias("c"),
... )
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 11  ┆ x   ┆ X   │
│ 12  ┆ y   ┆ Y   │
│ 13  ┆ z   ┆ Z   │
└─────┴─────┴─────┘

Переопределить имя по умолчанию для столбцов-литералов, чтобы избежать ошибок из-за повторяющихся имён столбцов.

>>> df.with_columns(
...     pl.lit(True).alias("c"),
...     pl.lit(4.0).alias("d"),
... )
shape: (3, 4)
┌─────┬─────┬──────┬─────┐
│ a   ┆ b   ┆ c    ┆ d   │
│ --- ┆ --- ┆ ---  ┆ --- │
│ i64 ┆ str ┆ bool ┆ f64 │
╞═════╪═════╪══════╪═════╡
│ 1   ┆ x   ┆ true ┆ 4.0 │
│ 2   ┆ y   ┆ true ┆ 4.0 │
│ 3   ┆ z   ┆ true ┆ 4.0 │
└─────┴─────┴──────┴─────┘

all(
    *,
    ignore_nulls: bool = True,
) → Expr

Вернуть, являются ли все значения в столбце True.

Работает только со столбцами типа данных Boolean.

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

Примечание

Не следует путать этот метод с функцией polars.all(), которую можно использовать для выбора всех столбцов.

Параметры:

ignore_nulls

Если задано значение True (по умолчанию), значения null игнорируются. Если значений, отличных от null, нет, результатом будет True.
Если задано значение False, для обработки значений null используется логика Клини: если столбец содержит значения null и не содержит значений False, результатом будет null.

Возвращает:

Expr: Выражение типа данных Boolean.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [True, True],
...         "b": [False, True],
...         "c": [None, True],
...     }
... )
>>> df.select(pl.col("*").all())
shape: (1, 3)
┌──────┬───────┬──────┐
│ a    ┆ b     ┆ c    │
│ ---  ┆ ---   ┆ ---  │
│ bool ┆ bool  ┆ bool │
╞══════╪═══════╪══════╡
│ true ┆ false ┆ true │
└──────┴───────┴──────┘

Включить логику Клини, задав ignore_nulls=False.

>>> df.select(pl.col("*").all(ignore_nulls=False))
shape: (1, 3)
┌──────┬───────┬──────┐
│ a    ┆ b     ┆ c    │
│ ---  ┆ ---   ┆ ---  │
│ bool ┆ bool  ┆ bool │
╞══════╪═══════╪══════╡
│ true ┆ false ┆ null │
└──────┴───────┴──────┘

and_(
    *others: Any,
) → Expr

Эквивалент метода для побитового оператора «и» expr & other & ....

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

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

Параметры:

*others: Одно или несколько целочисленных или булевых выражений для вычисления/объединения.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [5, 6, 7, 4, 8],
...         "y": [1.5, 2.5, 1.0, 4.0, -5.75],
...         "z": [-9, 2, -1, 4, 8],
...     }
... )

Объединение логических условий «и»:

>>> df.select(
...     (pl.col("x") >= pl.col("z"))
...     .and_(
...         pl.col("y") >= pl.col("z"),
...         pl.col("y") == pl.col("y"),
...         pl.col("z") <= pl.col("x"),
...         pl.col("y") != pl.col("x"),
...     )
...     .alias("all")
... )
shape: (5, 1)
┌───────┐
│ all   │
│ ---   │
│ bool  │
╞═══════╡
│ true  │
│ true  │
│ true  │
│ false │
│ false │
└───────┘

Побитовая операция «и» над целочисленными столбцами:

>>> df.select("x", "z", x_and_z=pl.col("x").and_(pl.col("z")))
shape: (5, 3)
┌─────┬─────┬─────────┐
│ x   ┆ z   ┆ x_and_z │
│ --- ┆ --- ┆ ---     │
│ i64 ┆ i64 ┆ i64     │
╞═════╪═════╪═════════╡
│ 5   ┆ -9  ┆ 5       │
│ 6   ┆ 2   ┆ 2       │
│ 7   ┆ -1  ┆ 7       │
│ 4   ┆ 4   ┆ 4       │
│ 8   ┆ 8   ┆ 8       │
└─────┴─────┴─────────┘

any(
    *,
    ignore_nulls: bool = True,
) → Expr

Вернуть, содержит ли столбец хотя бы одно значение True.

Работает только со столбцами типа данных Boolean.

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

Параметры:

ignore_nulls

Если задано значение True (по умолчанию), значения null игнорируются. Если значений, отличных от null, нет, результатом будет False.
Если задано значение False, для обработки значений null используется логика Клини: если столбец содержит значения null и не содержит значений True, результатом будет null.

Возвращает:

Expr: Выражение типа данных Boolean.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [True, False],
...         "b": [False, False],
...         "c": [None, False],
...     }
... )
>>> df.select(pl.col("*").any())
shape: (1, 3)
┌──────┬───────┬───────┐
│ a    ┆ b     ┆ c     │
│ ---  ┆ ---   ┆ ---   │
│ bool ┆ bool  ┆ bool  │
╞══════╪═══════╪═══════╡
│ true ┆ false ┆ false │
└──────┴───────┴───────┘

Включить логику Клини, задав ignore_nulls=False.

>>> df.select(pl.col("*").any(ignore_nulls=False))
shape: (1, 3)
┌──────┬───────┬──────┐
│ a    ┆ b     ┆ c    │
│ ---  ┆ ---   ┆ ---  │
│ bool ┆ bool  ┆ bool │
╞══════╪═══════╪══════╡
│ true ┆ false ┆ null │
└──────┴───────┴──────┘

append(
    other: IntoExpr,
    *,
    upcast: bool = True,
) → Expr

Добавить выражения.

Это выполняется путём добавления блоков other к этому Series.

движок:В памяти

Параметры:

other: Выражение для добавления.
upcast: Привести оба значения Series к одному общему типу.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [8, 9, 10],
...         "b": [None, 4, 4],
...     }
... )
>>> df.select(pl.all().head(1).append(pl.all().tail(1)))
shape: (2, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ i64  │
╞═════╪══════╡
│ 8   ┆ null │
│ 10  ┆ 4    │
└─────┴──────┘

approx_n_unique() → Expr

Приблизительное количество уникальных значений.

Для оценки кардинальности используется алгоритм HyperLogLog++.

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

Примеры

>>> df = pl.DataFrame({"n": [1, 1, 2]})
>>> df.select(pl.col("n").approx_n_unique())
shape: (1, 1)
┌─────┐
│ n   │
│ --- │
│ u32 │
╞═════╡
│ 2   │
└─────┘
>>> df = pl.DataFrame({"n": range(1000)})
>>> df.select(
...     exact=pl.col("n").n_unique(),
...     approx=pl.col("n").approx_n_unique(),
... )  
shape: (1, 2)
┌───────┬────────┐
│ exact ┆ approx │
│ ---   ┆ ---    │
│ u32   ┆ u32    │
╞═══════╪════════╡
│ 1000  ┆ 1005   │
└───────┴────────┘

arccos() → Expr

Поэлементно вычислить арккосинус.

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

Возвращает:

Expr: Выражение типа данных Float64, задающее угол в радианах.

Примечания

Чтобы преобразовать результат из радианов в градусы, вызовите .degrees().

Примеры

>>> df = pl.DataFrame({"a": [1.0, 0.5, 0]})
>>> df.select(pl.col("a").arccos())
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.0      │
│ 1.047198 │
│ 1.570796 │
└──────────┘
>>> df.select(pl.col("a").arccos().degrees())
shape: (3, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ 0.0  │
│ 60.0 │
│ 90.0 │
└──────┘

arccosh() → Expr

Поэлементно вычислить гиперболический арккосинус.

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

Возвращает:

Expr: Выражение типа данных Float64.

Примеры

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").arccosh())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
└─────┘

arcsin() → Expr

Поэлементно вычислить арксинус.

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

Возвращает:

Expr: Выражение типа данных Float64, задающее угол в радианах.

Примечания

Чтобы преобразовать результат из радианов в градусы, вызовите .degrees().

Примеры

>>> df = pl.DataFrame({"a": [1.0, 0.5, 0]})
>>> df.select(pl.col("a").arcsin())
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.570796 │
│ 0.523599 │
│ 0.0      │
└──────────┘
>>> df.select(pl.col("a").arcsin().degrees())
shape: (3, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ 90.0 │
│ 30.0 │
│ 0.0  │
└──────┘

arcsinh() → Expr

Поэлементно вычислить гиперболический арксинус.

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

Возвращает:

Expr: Выражение типа данных Float64.

Примеры

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").arcsinh())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.881374 │
└──────────┘

arctan() → Expr

Вычисляет поэлементное значение арктангенса.

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

Возвращает:

Expr: Выражение типа данных Float64, представляющее угол в радианах.

Примечания

Чтобы преобразовать результат из радиан в градусы, вызовите .degrees().

Примеры

>>> df = pl.DataFrame({"a": [float("Inf"), 1, 0]})
>>> df.select(pl.col("a").arctan())
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.570796 │
│ 0.785398 │
│ 0.0      │
└──────────┘
>>> df.select(pl.col("a").arctan().degrees())
shape: (3, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ 90.0 │
│ 45.0 │
│ 0.0  │
└──────┘

arctanh() → Expr

Вычисляет поэлементное значение обратного гиперболического тангенса.

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

Возвращает:

Expr: Выражение типа данных Float64.

Примеры

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").arctanh())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ inf │
└─────┘

arg_max() → Expr

Получает индекс максимального значения.

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

движок:В памятиПотоковый

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [20, 10, 30],
...     }
... )
>>> df.select(pl.col("a").arg_max())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 2   │
└─────┘

arg_min() → Expr

Получает индекс минимального значения.

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

движок:В памятиПотоковый

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [20, 10, 30],
...     }
... )
>>> df.select(pl.col("a").arg_min())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 1   │
└─────┘

arg_sort(
    *,
    descending: bool = False,
    nulls_last: bool = False,
) → Expr

Получает значения индексов, которые сортируют этот столбец.

движок:В памяти

Параметры:

descending: Сортировать в порядке убывания.
nulls_last: Размещать значения null в конце, а не в начале.

Возвращает:

Expr: Выражение типа данных UInt32.

См. также

Expr.gather: Извлекает значения по индексам.
Expr.rank: Получает ранг каждой строки.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [20, 10, 30],
...         "b": [1, 2, 3],
...     }
... )
>>> df.select(pl.col("a").arg_sort())
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 1   │
│ 0   │
│ 2   │
└─────┘

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

>>> df.select(pl.col("b").gather(pl.col("a").arg_sort()))
shape: (3, 1)
┌─────┐
│ b   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
│ 1   │
│ 3   │
└─────┘

arg_true() → Expr

Возвращает индексы, для которых выражение принимает значение True.

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

Изменяет количество возвращаемых строк, поэтому не будет работать в сочетании с другими выражениями. Используйте как единственное выражение в select / with_columns.

См. также

Series.arg_true: Возвращает индексы, для которых Series имеет значение True
polars.arg_where

Примеры

>>> df = pl.DataFrame({"a": [1, 1, 2, 1]})
>>> df.select((pl.col("a") == 1).arg_true())
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 0   │
│ 1   │
│ 3   │
└─────┘

arg_unique() → Expr

Получает индекс первого уникального значения.

движок:В памятиПотоковый

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [8, 9, 10],
...         "b": [None, 4, 4],
...     }
... )
>>> df.select(pl.col("a").arg_unique())
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 0   │
│ 1   │
│ 2   │
└─────┘
>>> df.select(pl.col("b").arg_unique())
shape: (2, 1)
┌─────┐
│ b   │
│ --- │
│ u32 │
╞═════╡
│ 0   │
│ 1   │
└─────┘

backward_fill(
    limit: int | None = None,
) → Expr

Заполняет пропущенные значения следующим ненулевым значением.

Это псевдоним .fill_null(strategy="backward").

движок:В памятиПотоковый

Параметры:

limit: Количество последовательных значений null для заполнения назад.

См. также

fill_null
forward_fill
shift

bitwise_and() → Expr

Выполняет агрегацию побитовых операций AND.

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

Примеры

>>> df = pl.DataFrame({"n": [-1, 0, 1]})
>>> df.select(pl.col("n").bitwise_and())
shape: (1, 1)
┌─────┐
│ n   │
│ --- │
│ i64 │
╞═════╡
│ 0   │
└─────┘
>>> df = pl.DataFrame(
...     {"grouper": ["a", "a", "a", "b", "b"], "n": [-1, 0, 1, -1, 1]}
... )
>>> df.group_by("grouper", maintain_order=True).agg(pl.col("n").bitwise_and())
shape: (2, 2)
┌─────────┬─────┐
│ grouper ┆ n   │
│ ---     ┆ --- │
│ str     ┆ i64 │
╞═════════╪═════╡
│ a       ┆ 0   │
│ b       ┆ 1   │
└─────────┴─────┘

bitwise_count_ones() → Expr

Вычисляет количество установленных битов.

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

bitwise_count_zeros() → Expr

Вычисляет количество сброшенных битов.

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

bitwise_leading_ones() → Expr

Вычисляет количество старших установленных битов до первого сброшенного бита.

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

bitwise_leading_zeros() → Expr

Вычисляет количество старших сброшенных битов до первого установленного бита.

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

bitwise_or() → Expr

Выполняет агрегацию побитовых операций OR.

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

Примеры

>>> df = pl.DataFrame({"n": [-1, 0, 1]})
>>> df.select(pl.col("n").bitwise_or())
shape: (1, 1)
┌─────┐
│ n   │
│ --- │
│ i64 │
╞═════╡
│ -1  │
└─────┘
>>> df = pl.DataFrame(
...     {"grouper": ["a", "a", "a", "b", "b"], "n": [-1, 0, 1, -1, 1]}
... )
>>> df.group_by("grouper", maintain_order=True).agg(pl.col("n").bitwise_or())
shape: (2, 2)
┌─────────┬─────┐
│ grouper ┆ n   │
│ ---     ┆ --- │
│ str     ┆ i64 │
╞═════════╪═════╡
│ a       ┆ -1  │
│ b       ┆ -1  │
└─────────┴─────┘

bitwise_trailing_ones() → Expr

Вычисляет количество младших установленных битов до первого сброшенного бита.

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

bitwise_trailing_zeros() → Expr

Вычисляет количество младших сброшенных битов до первого установленного бита.

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

bitwise_xor() → Expr

Выполняет агрегацию побитовых операций XOR.

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

Примеры

>>> df = pl.DataFrame({"n": [-1, 0, 1]})
>>> df.select(pl.col("n").bitwise_xor())
shape: (1, 1)
┌─────┐
│ n   │
│ --- │
│ i64 │
╞═════╡
│ -2  │
└─────┘
>>> df = pl.DataFrame(
...     {"grouper": ["a", "a", "a", "b", "b"], "n": [-1, 0, 1, -1, 1]}
... )
>>> df.group_by("grouper", maintain_order=True).agg(pl.col("n").bitwise_xor())
shape: (2, 2)
┌─────────┬─────┐
│ grouper ┆ n   │
│ ---     ┆ --- │
│ str     ┆ i64 │
╞═════════╪═════╡
│ a       ┆ -2  │
│ b       ┆ -2  │
└─────────┴─────┘

bottom_k(
    k: int | IntoExprColumn = 5,
) → Expr

Возвращает k наименьших элементов.

Ненулевые элементы всегда имеют приоритет перед элементами null. Порядок выходных данных не гарантируется; если необходимо отсортировать результат, вызовите sort() после этой функции.

Временная сложность:

\[O(n)\]

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

Параметры:

k: Количество возвращаемых элементов.

См. также

top_k
top_k_by
bottom_k_by

Примеры

>>> df = pl.DataFrame(
...     {
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.select(
...     pl.col("value").top_k().alias("top_k"),
...     pl.col("value").bottom_k().alias("bottom_k"),
... )
shape: (5, 2)
┌───────┬──────────┐
│ top_k ┆ bottom_k │
│ ---   ┆ ---      │
│ i64   ┆ i64      │
╞═══════╪══════════╡
│ 4     ┆ 1        │
│ 98    ┆ 98       │
│ 2     ┆ 2        │
│ 3     ┆ 3        │
│ 99    ┆ 4        │
└───────┴──────────┘

bottom_k_by(
    by: IntoExpr | Iterable[IntoExpr],
    k: int | IntoExprColumn = 5,
    *,
    reverse: bool | Sequence[bool] = False,
) → Expr

Возвращает элементы, соответствующие k наименьшим элементам столбца (столбцов) by.

Ненулевые элементы всегда имеют приоритет перед элементами null независимо от значения reverse. Порядок выходных данных не гарантируется; если необходимо отсортировать результат, вызовите sort() после этой функции.

Временная сложность:

\[O(n \log{n})\]

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

Изменено в версии 1.0.0: Параметр descending переименован в reverse.

Параметры:

by: Столбец (столбцы), используемый для определения наименьших элементов. Принимает выражение. Строки интерпретируются как имена столбцов.
k: Количество возвращаемых элементов.
reverse: Учитывать k наибольших элементов столбца (столбцов) by вместо k наименьших. Значение можно задать отдельно для каждого столбца, передав последовательность логических значений.

См. также

top_k
top_k_by
bottom_k

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [6, 5, 4, 3, 2, 1],
...         "c": ["Apple", "Orange", "Apple", "Apple", "Banana", "Banana"],
...     }
... )
>>> df
shape: (6, 3)
┌─────┬─────┬────────┐
│ a   ┆ b   ┆ c      │
│ --- ┆ --- ┆ ---    │
│ i64 ┆ i64 ┆ str    │
╞═════╪═════╪════════╡
│ 1   ┆ 6   ┆ Apple  │
│ 2   ┆ 5   ┆ Orange │
│ 3   ┆ 4   ┆ Apple  │
│ 4   ┆ 3   ┆ Apple  │
│ 5   ┆ 2   ┆ Banana │
│ 6   ┆ 1   ┆ Banana │
└─────┴─────┴────────┘

Получение двух нижних строк по столбцу a или b.

>>> df.select(
...     pl.all().bottom_k_by("a", 2).name.suffix("_btm_by_a"),
...     pl.all().bottom_k_by("b", 2).name.suffix("_btm_by_b"),
... )
shape: (2, 6)
┌────────────┬────────────┬────────────┬────────────┬────────────┬────────────┐
│ a_btm_by_a ┆ b_btm_by_a ┆ c_btm_by_a ┆ a_btm_by_b ┆ b_btm_by_b ┆ c_btm_by_b │
│ ---        ┆ ---        ┆ ---        ┆ ---        ┆ ---        ┆ ---        │
│ i64        ┆ i64        ┆ str        ┆ i64        ┆ i64        ┆ str        │
╞════════════╪════════════╪════════════╪════════════╪════════════╪════════════╡
│ 1          ┆ 6          ┆ Apple      ┆ 6          ┆ 1          ┆ Banana     │
│ 2          ┆ 5          ┆ Orange     ┆ 5          ┆ 2          ┆ Banana     │
└────────────┴────────────┴────────────┴────────────┴────────────┴────────────┘

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

>>> df.select(
...     pl.all()
...     .bottom_k_by(["c", "a"], 2, reverse=[False, True])
...     .name.suffix("_by_ca"),
...     pl.all()
...     .bottom_k_by(["c", "b"], 2, reverse=[False, True])
...     .name.suffix("_by_cb"),
... )
shape: (2, 6)
┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐
│ a_by_ca ┆ b_by_ca ┆ c_by_ca ┆ a_by_cb ┆ b_by_cb ┆ c_by_cb │
│ ---     ┆ ---     ┆ ---     ┆ ---     ┆ ---     ┆ ---     │
│ i64     ┆ i64     ┆ str     ┆ i64     ┆ i64     ┆ str     │
╞═════════╪═════════╪═════════╪═════════╪═════════╪═════════╡
│ 4       ┆ 3       ┆ Apple   ┆ 1       ┆ 6       ┆ Apple   │
│ 3       ┆ 4       ┆ Apple   ┆ 3       ┆ 4       ┆ Apple   │
└─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘

Получение двух нижних строк по столбцу a в каждой группе.

>>> (
...     df.group_by("c", maintain_order=True)
...     .agg(pl.all().bottom_k_by("a", 2))
...     .explode(pl.all().exclude("c"))
... )
shape: (5, 3)
┌────────┬─────┬─────┐
│ c      ┆ a   ┆ b   │
│ ---    ┆ --- ┆ --- │
│ str    ┆ i64 ┆ i64 │
╞════════╪═════╪═════╡
│ Apple  ┆ 1   ┆ 6   │
│ Apple  ┆ 3   ┆ 4   │
│ Orange ┆ 2   ┆ 5   │
│ Banana ┆ 5   ┆ 2   │
│ Banana ┆ 6   ┆ 1   │
└────────┴─────┴─────┘

cast(
    dtype: PolarsDataType | DataTypeExpr | type[Any],
    *,
    strict: bool = True,
    wrap_numerical: bool = False,
) → Expr

Преобразует один тип данных в другой.

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

Параметры:

dtype: Тип данных, к которому выполняется преобразование.
strict: Вызывает ошибку, если преобразование недопустимо для строк после проталкивания предикатов. Если False, недопустимые преобразования приведут к значениям null.
wrap_numerical: Если значение равно True, при переполнении числовые преобразования выполняются по модулю вместо пометки преобразования как недопустимого.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": ["4", "5", "6"],
...     }
... )
>>> df.with_columns(
...     pl.col("a").cast(pl.Float64),
...     pl.col("b").cast(pl.Int32),
... )
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ i32 │
╞═════╪═════╡
│ 1.0 ┆ 4   │
│ 2.0 ┆ 5   │
│ 3.0 ┆ 6   │
└─────┴─────┘

cbrt() → Expr

Вычисляет кубический корень элементов.

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

Примеры

>>> df = pl.DataFrame({"values": [1.0, 2.0, 4.0]})
>>> df.select(pl.col("values").cbrt())
shape: (3, 1)
┌──────────┐
│ values   │
│ ---      │
│ f64      │
╞══════════╡
│ 1.0      │
│ 1.259921 │
│ 1.587401 │
└──────────┘

ceil() → Expr

Округляет вверх до ближайшего целого значения.

Работает только с Series с числами с плавающей запятой.

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

См. также

floor: Округляет вниз до ближайшего целого.
round: Округляет до ближайшего целого.

Примеры

>>> df = pl.DataFrame({"a": [0.3, 0.5, 1.0, 1.1]})
>>> df.select(pl.col("a").ceil())
shape: (4, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
│ 1.0 │
│ 1.0 │
│ 2.0 │
└─────┘

clip(
    lower_bound: NumericLiteral | TemporalLiteral | IntoExprColumn | None = None,
    upper_bound: NumericLiteral | TemporalLiteral | IntoExprColumn | None = None,
) → Expr

Заменяет значения за пределами заданных границ соответствующим граничным значением.

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

Параметры:

lower_bound: Нижняя граница. Принимает выражение. Значения, не являющиеся выражениями, интерпретируются как литералы. Строки интерпретируются как имена столбцов.
upper_bound: Верхняя граница. Принимает выражение. Значения, не являющиеся выражениями, интерпретируются как литералы. Строки интерпретируются как имена столбцов.

См. также

when

Примечания

Этот метод работает только с числовыми и временными столбцами. Для ограничения значений других типов данных можно написать выражение when-then-otherwise. См. when().

Примеры

Указание нижней и верхней границ:

>>> df = pl.DataFrame({"a": [-50, 5, 50, None]})
>>> df.with_columns(clip=pl.col("a").clip(1, 10))
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ clip │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ -50  ┆ 1    │
│ 5    ┆ 5    │
│ 50   ┆ 10   │
│ null ┆ null │
└──────┴──────┘

Указание только одной границы:

>>> df.with_columns(clip=pl.col("a").clip(upper_bound=10))
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ clip │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ -50  ┆ -50  │
│ 5    ┆ 5    │
│ 50   ┆ 10   │
│ null ┆ null │
└──────┴──────┘

Использование столбцов в качестве границ:

>>> df = pl.DataFrame(
...     {"a": [-50, 5, 50, None], "low": [10, 1, 0, 0], "up": [20, 4, 3, 2]}
... )
>>> df.with_columns(clip=pl.col("a").clip("low", "up"))
shape: (4, 4)
┌──────┬─────┬─────┬──────┐
│ a    ┆ low ┆ up  ┆ clip │
│ ---  ┆ --- ┆ --- ┆ ---  │
│ i64  ┆ i64 ┆ i64 ┆ i64  │
╞══════╪═════╪═════╪══════╡
│ -50  ┆ 10  ┆ 20  ┆ 10   │
│ 5    ┆ 1   ┆ 4   ┆ 4    │
│ 50   ┆ 0   ┆ 3   ┆ 3    │
│ null ┆ 0   ┆ 2   ┆ null │
└──────┴─────┴─────┴──────┘

cos() → Expr

Вычисляет поэлементное значение косинуса.

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

Возвращает:

Expr: Выражение типа данных Float64.

Примечания

Аргумент должен быть задан в радианах. Чтобы преобразовать градусы в радианы, вызовите .radians().

Примеры

>>> from math import pi
>>> df = pl.DataFrame({"a": [0.0, pi / 2]})
>>> df.select(pl.col("a").cos())
shape: (2, 1)
┌────────────┐
│ a          │
│ ---        │
│ f64        │
╞════════════╡
│ 1.0        │
│ 6.1232e-17 │
└────────────┘
>>> df = pl.DataFrame({"a": [0.0, 90]})
>>> df.select(pl.col("a").radians().cos())
shape: (2, 1)
┌────────────┐
│ a          │
│ ---        │
│ f64        │
╞════════════╡
│ 1.0        │
│ 6.1232e-17 │
└────────────┘

cosh() → Expr

Вычисляет поэлементное значение гиперболического косинуса.

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

Возвращает:

Expr: Выражение типа данных Float64.

Примеры

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").cosh())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.543081 │
└──────────┘

cot() → Expr

Вычисляет поэлементное значение котангенса.

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

Возвращает:

Expr: Выражение типа данных Float64.

Примечания

Аргумент должен быть задан в радианах. Чтобы преобразовать градусы в радианы, вызовите .radians().

Примеры

>>> from math import pi
>>> df = pl.DataFrame({"a": [0.0, pi / 4]})
>>> df.select(pl.col("a").cot())
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ inf │
│ 1.0 │
└─────┘
>>> df = pl.DataFrame({"a": [0.0, 45]})
>>> df.select(pl.col("a").radians().cot())
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ inf │
│ 1.0 │
└─────┘

count() → Expr

Возвращает количество ненулевых элементов в столбце.

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

Возвращает:

Expr: Выражение типа данных UInt32.

См. также

len

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3], "b": [None, 4, 4]})
>>> df.select(pl.all().count())
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ u32 ┆ u32 │
╞═════╪═════╡
│ 3   ┆ 2   │
└─────┴─────┘

cum_count(
    *,
    reverse: bool = False,
) → Expr

Возвращает накопительное количество ненулевых значений в столбце.

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

Параметры:

reverse: Выполнить операцию в обратном порядке.

Примеры

>>> df = pl.DataFrame({"a": ["x", "k", None, "d"]})
>>> df.with_columns(
...     pl.col("a").cum_count().alias("cum_count"),
...     pl.col("a").cum_count(reverse=True).alias("cum_count_reverse"),
... )
shape: (4, 3)
┌──────┬───────────┬───────────────────┐
│ a    ┆ cum_count ┆ cum_count_reverse │
│ ---  ┆ ---       ┆ ---               │
│ str  ┆ u32       ┆ u32               │
╞══════╪═══════════╪═══════════════════╡
│ x    ┆ 1         ┆ 3                 │
│ k    ┆ 2         ┆ 2                 │
│ null ┆ 2         ┆ 1                 │
│ d    ┆ 3         ┆ 1                 │
└──────┴───────────┴───────────────────┘

cum_max(
    *,
    reverse: bool = False,
) → Expr

Возвращает массив с накопительным максимумом, вычисленным для каждого элемента.

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

Параметры:

reverse: Выполнить операцию в обратном порядке.

Примеры

>>> df = pl.DataFrame({"a": [1, 3, 2]})
>>> df.with_columns(
...     pl.col("a").cum_max().alias("cum_max"),
...     pl.col("a").cum_max(reverse=True).alias("cum_max_reverse"),
... )
shape: (3, 3)
┌─────┬─────────┬─────────────────┐
│ a   ┆ cum_max ┆ cum_max_reverse │
│ --- ┆ ---     ┆ ---             │
│ i64 ┆ i64     ┆ i64             │
╞═════╪═════════╪═════════════════╡
│ 1   ┆ 1       ┆ 3               │
│ 3   ┆ 3       ┆ 3               │
│ 2   ┆ 3       ┆ 2               │
└─────┴─────────┴─────────────────┘

Значения null исключаются, но их также можно заполнить вызовом fill_null(strategy="forward").

>>> df = pl.DataFrame({"values": [None, 10, None, 8, 9, None, 16, None]})
>>> df.with_columns(
...     pl.col("values").cum_max().alias("cum_max"),
...     pl.col("values")
...     .cum_max()
...     .fill_null(strategy="forward")
...     .alias("cum_max_all_filled"),
... )
shape: (8, 3)
┌────────┬─────────┬────────────────────┐
│ values ┆ cum_max ┆ cum_max_all_filled │
│ ---    ┆ ---     ┆ ---                │
│ i64    ┆ i64     ┆ i64                │
╞════════╪═════════╪════════════════════╡
│ null   ┆ null    ┆ null               │
│ 10     ┆ 10      ┆ 10                 │
│ null   ┆ null    ┆ 10                 │
│ 8      ┆ 10      ┆ 10                 │
│ 9      ┆ 10      ┆ 10                 │
│ null   ┆ null    ┆ 10                 │
│ 16     ┆ 16      ┆ 16                 │
│ null   ┆ null    ┆ 16                 │
└────────┴─────────┴────────────────────┘

cum_min(
    *,
    reverse: bool = False,
) → Expr

Возвращает массив с накопительным минимумом, вычисленным для каждого элемента.

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

Параметры:

reverse: Выполнить операцию в обратном порядке.

Примеры

>>> df = pl.DataFrame({"a": [3, 1, 2]})
>>> df.with_columns(
...     pl.col("a").cum_min().alias("cum_min"),
...     pl.col("a").cum_min(reverse=True).alias("cum_min_reverse"),
... )
shape: (3, 3)
┌─────┬─────────┬─────────────────┐
│ a   ┆ cum_min ┆ cum_min_reverse │
│ --- ┆ ---     ┆ ---             │
│ i64 ┆ i64     ┆ i64             │
╞═════╪═════════╪═════════════════╡
│ 3   ┆ 3       ┆ 1               │
│ 1   ┆ 1       ┆ 1               │
│ 2   ┆ 1       ┆ 2               │
└─────┴─────────┴─────────────────┘

cum_prod(
    *,
    reverse: bool = False,
) → Expr

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

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

Параметры:

reverse: Выполнить операцию в обратном порядке.

Примечания

Типы данных из {Int8, UInt8, Int16, UInt16} преобразуются в Int64 перед суммированием для предотвращения переполнения.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3, 4]})
>>> df.with_columns(
...     pl.col("a").cum_prod().alias("cum_prod"),
...     pl.col("a").cum_prod(reverse=True).alias("cum_prod_reverse"),
... )
shape: (4, 3)
┌─────┬──────────┬──────────────────┐
│ a   ┆ cum_prod ┆ cum_prod_reverse │
│ --- ┆ ---      ┆ ---              │
│ i64 ┆ i64      ┆ i64              │
╞═════╪══════════╪══════════════════╡
│ 1   ┆ 1        ┆ 24               │
│ 2   ┆ 2        ┆ 24               │
│ 3   ┆ 6        ┆ 12               │
│ 4   ┆ 24       ┆ 4                │
└─────┴──────────┴──────────────────┘

cum_sum(
    *,
    reverse: bool = False,
) → Expr

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

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

Параметры:

reverse: Выполнить операцию в обратном порядке.

Примечания

Типы данных из {Int8, UInt8, Int16, UInt16} преобразуются в Int64 перед суммированием для предотвращения переполнения.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3, 4]})
>>> df.with_columns(
...     pl.col("a").cum_sum().alias("cum_sum"),
...     pl.col("a").cum_sum(reverse=True).alias("cum_sum_reverse"),
... )
shape: (4, 3)
┌─────┬─────────┬─────────────────┐
│ a   ┆ cum_sum ┆ cum_sum_reverse │
│ --- ┆ ---     ┆ ---             │
│ i64 ┆ i64     ┆ i64             │
╞═════╪═════════╪═════════════════╡
│ 1   ┆ 1       ┆ 10              │
│ 2   ┆ 3       ┆ 9               │
│ 3   ┆ 6       ┆ 7               │
│ 4   ┆ 10      ┆ 4               │
└─────┴─────────┴─────────────────┘

Значения null исключаются, но их также можно заполнить вызовом fill_null(strategy="forward").

>>> df = pl.DataFrame({"values": [None, 10, None, 8, 9, None, 16, None]})
>>> df.with_columns(
...     pl.col("values").cum_sum().alias("value_cum_sum"),
...     pl.col("values")
...     .cum_sum()
...     .fill_null(strategy="forward")
...     .alias("value_cum_sum_all_filled"),
... )
shape: (8, 3)
┌────────┬───────────────┬──────────────────────────┐
│ values ┆ value_cum_sum ┆ value_cum_sum_all_filled │
│ ---    ┆ ---           ┆ ---                      │
│ i64    ┆ i64           ┆ i64                      │
╞════════╪═══════════════╪══════════════════════════╡
│ null   ┆ null          ┆ null                     │
│ 10     ┆ 10            ┆ 10                       │
│ null   ┆ null          ┆ 10                       │
│ 8      ┆ 18            ┆ 18                       │
│ 9      ┆ 27            ┆ 27                       │
│ null   ┆ null          ┆ 27                       │
│ 16     ┆ 43            ┆ 43                       │
│ null   ┆ null          ┆ 43                       │
└────────┴───────────────┴──────────────────────────┘

cumulative_eval(
    expr: Expr,
    *,
    min_samples: int = 1,
) → Expr

Выполняет выражение над скользящим окном, которое на каждой итерации увеличивается на 1 позицию.

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

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без уведомления о несовместимых изменениях.

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

expr: Вычисляемое выражение
min_samples: Количество допустимых значений в окне, необходимое для вычисления выражения. допустимые значения = length - null_count

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

Это может работать очень медленно, поскольку временная сложность может составлять O(n^2). Не используйте это для операций, обходящих все элементы.

Примеры

>>> df = pl.DataFrame({"values": [1, 2, 3, 4, 5]})
>>> df.select(
...     [
...         pl.col("values").cumulative_eval(
...             pl.element().first() - pl.element().last() ** 2
...         )
...     ]
... )
shape: (5, 1)
┌────────┐
│ values │
│ ---    │
│ i64    │
╞════════╡
│ 0      │
│ -3     │
│ -8     │
│ -15    │
│ -24    │
└────────┘

cut(
    breaks: Sequence[float],
    *,
    labels: Sequence[str_] | None = None,
    left_closed: bool = False,
    include_breaks: bool = False,
) → Expr

Разбивает непрерывные значения на дискретные категории.

движок:В памяти

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

Параметры:

breaks: Список уникальных точек разбиения.
labels: Названия категорий. Количество меток должно быть на единицу больше количества точек разбиения.
left_closed: Задать интервалы с замкнутой левой границей вместо правой.
include_breaks: Добавить столбец с правой границей интервала, в который попадает каждое наблюдение. Это изменит тип выходных данных с Enum на Struct.

Возвращает:

Expr: Выражение типа данных Enum, если include_breaks имеет значение False (по умолчанию); в противном случае — выражение типа данных Struct.

См. также

qcut

Примеры

Разделение столбца на три категории.

>>> df = pl.DataFrame({"foo": [-2, -1, 0, 1, 2]})
>>> df.with_columns(
...     pl.col("foo").cut([-1, 1], labels=["a", "b", "c"]).alias("cut")
... )
shape: (5, 2)
┌─────┬──────┐
│ foo ┆ cut  │
│ --- ┆ ---  │
│ i64 ┆ enum │
╞═════╪══════╡
│ -2  ┆ a    │
│ -1  ┆ a    │
│ 0   ┆ b    │
│ 1   ┆ b    │
│ 2   ┆ c    │
└─────┴──────┘

Добавление категории и точки разбиения.

>>> df.with_columns(
...     pl.col("foo").cut([-1, 1], include_breaks=True).alias("cut")
... ).unnest("cut")
shape: (5, 3)
┌─────┬────────────┬────────────┐
│ foo ┆ breakpoint ┆ category   │
│ --- ┆ ---        ┆ ---        │
│ i64 ┆ f64        ┆ enum       │
╞═════╪════════════╪════════════╡
│ -2  ┆ -1.0       ┆ (-inf, -1] │
│ -1  ┆ -1.0       ┆ (-inf, -1] │
│ 0   ┆ 1.0        ┆ (-1, 1]    │
│ 1   ┆ 1.0        ┆ (-1, 1]    │
│ 2   ┆ inf        ┆ (1, inf]   │
└─────┴────────────┴────────────┘

degrees() → Expr

Преобразует радианы в градусы.

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

Возвращает:

Expr: Выражение типа данных Float64.

Примеры

>>> import math
>>> df = pl.DataFrame({"a": [x * math.pi for x in range(-4, 5)]})
>>> df.select(pl.col("a").degrees())
shape: (9, 1)
┌────────┐
│ a      │
│ ---    │
│ f64    │
╞════════╡
│ -720.0 │
│ -540.0 │
│ -360.0 │
│ -180.0 │
│ 0.0    │
│ 180.0  │
│ 360.0  │
│ 540.0  │
│ 720.0  │
└────────┘

classmethod deserialize(
    source: str_ | Path | IOBase | bytes,
    *,
    format: SerializationFormat = 'binary',
) → Expr

Прочитать сериализованное выражение из файла.

Параметры:

source

Путь к файлу или файловоподобный объект (под файловоподобным объектом подразумеваются объекты, у которых есть метод read(), например файловый дескриптор (например, через встроенную функцию open) или BytesIO).

format

Формат, в котором был сериализован Expr. Варианты:

"binary": десериализация из двоичного формата (байты). Используется по умолчанию.
"json": десериализация из формата JSON (строка).

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

Эта функция использует pickle, если логический план содержит пользовательские функции Python (UDF), и поэтому наследует связанные с этим последствия для безопасности. Десериализация может выполнять произвольный код, поэтому ее следует применять только к доверенным данным.

См. также

Expr.meta.serialize

Примечания

Сериализация не обеспечивает совместимость между версиями Polars: LazyFrame, сериализованный в одной версии Polars, может быть не десериализуем в другой версии.

Примеры

>>> import io
>>> expr = pl.col("foo").sum().over("bar")
>>> bytes = expr.meta.serialize()
>>> pl.Expr.deserialize(io.BytesIO(bytes))
<Expr ['col("foo").sum().over([col("ba…'] at ...>

diff(
    n: int | IntoExpr = 1,
    null_behavior: NullBehavior = 'ignore',
) → Expr

Вычислить первую дискретную разность между элементами со сдвигом.

движок:В памятиПотоковый

Параметры:

n: Количество позиций для сдвига.
null_behavior{‘ignore’, ‘drop’}: Способ обработки значений null.

Примеры

>>> df = pl.DataFrame({"int": [20, 10, 30, 25, 35]})
>>> df.with_columns(change=pl.col("int").diff())
shape: (5, 2)
┌─────┬────────┐
│ int ┆ change │
│ --- ┆ ---    │
│ i64 ┆ i64    │
╞═════╪════════╡
│ 20  ┆ null   │
│ 10  ┆ -10    │
│ 30  ┆ 20     │
│ 25  ┆ -5     │
│ 35  ┆ 10     │
└─────┴────────┘

>>> df.with_columns(change=pl.col("int").diff(n=2))
shape: (5, 2)
┌─────┬────────┐
│ int ┆ change │
│ --- ┆ ---    │
│ i64 ┆ i64    │
╞═════╪════════╡
│ 20  ┆ null   │
│ 10  ┆ null   │
│ 30  ┆ 10     │
│ 25  ┆ 15     │
│ 35  ┆ 5      │
└─────┴────────┘

>>> df.select(pl.col("int").diff(n=2, null_behavior="drop").alias("diff"))
shape: (3, 1)
┌──────┐
│ diff │
│ ---  │
│ i64  │
╞══════╡
│ 10   │
│ 15   │
│ 5    │
└──────┘

dot(
    other: Expr | str_,
) → Expr

Вычислить скалярное произведение двух выражений.

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

Параметры:

other: Выражение, с которым нужно вычислить скалярное произведение.

Примеры

>>> df = pl.DataFrame({"a": [1, 3, 5], "b": [2, 4, 6]})
>>> df.select(pl.col("a").dot(pl.col("b")))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 44  │
└─────┘

drop_nans() → Expr

Удалить все значения NaN с плавающей точкой.

Исходный порядок оставшихся элементов сохраняется.

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

См. также

drop_nulls

Примечания

Значение NaN — это не то же самое, что значение null. Чтобы удалить значения null, используйте drop_nulls().

Примеры

>>> df = pl.DataFrame({"a": [1.0, None, 3.0, float("nan")]})
>>> df.select(pl.col("a").drop_nans())
shape: (3, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ 1.0  │
│ null │
│ 3.0  │
└──────┘

drop_nulls() → Expr

Удалить все значения null.

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

Исходный порядок оставшихся элементов сохраняется.

См. также

drop_nans

Примечания

Значение null — это не то же самое, что значение NaN. Чтобы удалить значения NaN, используйте drop_nans().

Примеры

>>> df = pl.DataFrame({"a": [1.0, None, 3.0, float("nan")]})
>>> df.select(pl.col("a").drop_nulls())
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
│ 3.0 │
│ NaN │
└─────┘

entropy(
    base: float = 2.718281828459045,
    *,
    normalize: bool = True,
) → Expr

Вычислить энтропию.

Используется формула -sum(pk * log(pk)), где pk — дискретные вероятности.

движок:В памятиПотоковый

Параметры:

base: Основание логарифма; по умолчанию e
normalize: Нормализовать pk, если сумма его значений не равна 1.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").entropy(base=2))
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.459148 │
└──────────┘
>>> df.select(pl.col("a").entropy(base=2, normalize=False))
shape: (1, 1)
┌───────────┐
│ a         │
│ ---       │
│ f64       │
╞═══════════╡
│ -6.754888 │
└───────────┘

eq(
    other: Any,
) → Expr

Метод, эквивалентный оператору равенства expr == other.

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

Параметры:

other: Литерал или выражение, с которым нужно выполнить сравнение.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 4.0],
...         "y": [2.0, 2.0, float("nan"), 4.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").eq(pl.col("y")).alias("x == y"),
... )
shape: (4, 3)
┌─────┬─────┬────────┐
│ x   ┆ y   ┆ x == y │
│ --- ┆ --- ┆ ---    │
│ f64 ┆ f64 ┆ bool   │
╞═════╪═════╪════════╡
│ 1.0 ┆ 2.0 ┆ false  │
│ 2.0 ┆ 2.0 ┆ true   │
│ NaN ┆ NaN ┆ true   │
│ 4.0 ┆ 4.0 ┆ true   │
└─────┴─────┴────────┘

eq_missing(
    other: Any,
) → Expr

Метод, эквивалентный оператору равенства expr == other, где None == None.

Он отличается от поведения по умолчанию eq, при котором значения null распространяются.

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

Параметры:

other: Литерал или выражение, с которым нужно выполнить сравнение.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 4.0, None, None],
...         "y": [2.0, 2.0, float("nan"), 4.0, 5.0, None],
...     }
... )
>>> df.with_columns(
...     pl.col("x").eq(pl.col("y")).alias("x eq y"),
...     pl.col("x").eq_missing(pl.col("y")).alias("x eq_missing y"),
... )
shape: (6, 4)
┌──────┬──────┬────────┬────────────────┐
│ x    ┆ y    ┆ x eq y ┆ x eq_missing y │
│ ---  ┆ ---  ┆ ---    ┆ ---            │
│ f64  ┆ f64  ┆ bool   ┆ bool           │
╞══════╪══════╪════════╪════════════════╡
│ 1.0  ┆ 2.0  ┆ false  ┆ false          │
│ 2.0  ┆ 2.0  ┆ true   ┆ true           │
│ NaN  ┆ NaN  ┆ true   ┆ true           │
│ 4.0  ┆ 4.0  ┆ true   ┆ true           │
│ null ┆ 5.0  ┆ null   ┆ false          │
│ null ┆ null ┆ null   ┆ true           │
└──────┴──────┴────────┴────────────────┘

ewm_mean(
    *,
    com: float | None = None,
    span: float | None = None,
    half_life: float | None = None,
    alpha: float | None = None,
    adjust: bool = True,
    min_samples: int = 1,
    ignore_nulls: bool = False,
) → Expr

Вычислить экспоненциально взвешенное скользящее среднее.

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памятиПотоковый

Параметры:

com

Задать затухание через центр масс, $\gamma$, где

\[\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0\]

span

Задать затухание через интервал, $\theta$, где

\[\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1\]

half_life

Задать затухание через период полураспада, $\tau$, где

\[\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \tau } \right\} \; \forall \; \tau > 0\]

alpha

Задать коэффициент сглаживания alpha напрямую: $0 < \alpha \leq 1$.

adjust

Делить на затухающий поправочный коэффициент в начальных периодах, чтобы компенсировать несбалансированность относительных весов

Если adjust=True (значение по умолчанию), функция EW вычисляется с использованием весов $w_i = (1 - \alpha)^i$
Если adjust=False, функция EW вычисляется рекурсивно:

\[\begin{split}y_0 &= x_0 \\ y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t\end{split}\]

min_samples

Минимальное количество наблюдений в окне, необходимое для получения значения (иначе результат будет null).

ignore_nulls

Не учитывать пропущенные значения при вычислении весов.

Если ignore_nulls=False (значение по умолчанию), веса основаны на абсолютных позициях. Например, веса $x_0$ и $x_2$, используемые при вычислении итогового взвешенного среднего для [$x_0$, None, $x_2$], равны $(1-\alpha)^2$ и $1$, если adjust=True, и $(1-\alpha)^2$ и $\alpha$, если adjust=False.
Если ignore_nulls=True, веса основаны на относительных позициях. Например, веса $x_0$ и $x_2$, используемые при вычислении итогового взвешенного среднего для [$x_0$, None, $x_2$], равны $1-\alpha$ и $1$, если adjust=True, и $1-\alpha$ и $\alpha$, если adjust=False.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").ewm_mean(com=1, ignore_nulls=False))
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.0      │
│ 1.666667 │
│ 2.428571 │
└──────────┘

ewm_mean_by(
    by: str_ | IntoExpr,
    *,
    half_life: str_ | timedelta,
) → Expr

Вычислить экспоненциально взвешенное скользящее среднее с учетом времени.

Для наблюдений $x_0, x_1, \ldots, x_{n-1}$ в моменты времени $t_0, t_1, \ldots, t_{n-1}$ EWMA вычисляется следующим образом:

\[ \begin{align}\begin{aligned}y_0 &= x_0\\\alpha_i &= 1 - \exp \left\{ \frac{ -\ln(2)(t_i-t_{i-1}) } { \tau } \right\}\\y_i &= \alpha_i x_i + (1 - \alpha_i) y_{i-1}; \quad i > 0\end{aligned}\end{align} \]

где $\tau$ — half_life.

движок:В памяти

Параметры:

by

Время, по которому нужно вычислить среднее. Тип данных должен быть DateTime, Date, UInt64, UInt32, Int64 или Int32.

half_life

Интервал времени, за который наблюдение уменьшается вдвое.

Можно создать из timedelta или использовать следующий строковый формат:

1ns (1 наносекунда)
1us (1 микросекунда)
1ms (1 миллисекунда)
1s (1 секунда)
1m (1 минута)
1h (1 час)
1d (1 день)
1w (1 неделя)
1i (1 индексная позиция)

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

Обратите внимание, что half_life трактуется как постоянная длительность: календарные интервалы, например месяцы (или даже дни в случае часового пояса), не поддерживаются. Укажите длительность в приблизительно эквивалентном количестве часов (например, «370h» вместо «1mo»).

Возвращает:

Expr: Float16, если входные данные имеют тип Float16; class:.Float32, если входные данные имеют тип Float32; в противном случае — class:.Float64.

Примеры

>>> from datetime import date, timedelta
>>> df = pl.DataFrame(
...     {
...         "values": [0, 1, 2, None, 4],
...         "times": [
...             date(2020, 1, 1),
...             date(2020, 1, 3),
...             date(2020, 1, 10),
...             date(2020, 1, 15),
...             date(2020, 1, 17),
...         ],
...     }
... ).sort("times")
>>> df.with_columns(
...     result=pl.col("values").ewm_mean_by("times", half_life="4d"),
... )
shape: (5, 3)
┌────────┬────────────┬──────────┐
│ values ┆ times      ┆ result   │
│ ---    ┆ ---        ┆ ---      │
│ i64    ┆ date       ┆ f64      │
╞════════╪════════════╪══════════╡
│ 0      ┆ 2020-01-01 ┆ 0.0      │
│ 1      ┆ 2020-01-03 ┆ 0.292893 │
│ 2      ┆ 2020-01-10 ┆ 1.492474 │
│ null   ┆ 2020-01-15 ┆ null     │
│ 4      ┆ 2020-01-17 ┆ 3.254508 │
└────────┴────────────┴──────────┘

ewm_std(
    *,
    com: float | None = None,
    span: float | None = None,
    half_life: float | None = None,
    alpha: float | None = None,
    adjust: bool = True,
    bias: bool = False,
    min_samples: int = 1,
    ignore_nulls: bool = False,
) → Expr

Вычислить экспоненциально взвешенное скользящее стандартное отклонение.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

com

Задать затухание через центр масс, $\gamma$, где

\[\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0\]

span

Задать затухание через интервал, $\theta$, где

\[\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1\]

half_life

Задать затухание через период полураспада, $\lambda$, где

\[\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \; \forall \; \lambda > 0\]

alpha

Задать коэффициент сглаживания alpha напрямую: $0 < \alpha \leq 1$.

adjust

Если adjust=True (значение по умолчанию), функция EW вычисляется с использованием весов $w_i = (1 - \alpha)^i$
Если adjust=False, функция EW вычисляется рекурсивно:

\[\begin{split}y_0 &= x_0 \\ y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t\end{split}\]

bias

Если bias=False, применить поправку, чтобы оценка была статистически несмещенной.

min_samples

Минимальное количество наблюдений в окне, необходимое для получения значения (иначе результат будет null).

ignore_nulls

Не учитывать пропущенные значения при вычислении весов.

Если ignore_nulls=False (значение по умолчанию), веса основаны на абсолютных позициях. Например, веса $x_0$ и $x_2$, используемые при вычислении итогового взвешенного среднего для [$x_0$, None, $x_2$], равны $(1-\alpha)^2$ и $1$, если adjust=True, и $(1-\alpha)^2$ и $\alpha$, если adjust=False.
Если ignore_nulls=True, веса основаны на относительных позициях. Например, веса $x_0$ и $x_2$, используемые при вычислении итогового взвешенного среднего для [$x_0$, None, $x_2$], равны $1-\alpha$ и $1$, если adjust=True, и $1-\alpha$ и $\alpha$, если adjust=False.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").ewm_std(com=1, ignore_nulls=False))
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ null     │
│ 0.707107 │
│ 0.963624 │
└──────────┘

ewm_sum(
    *,
    com: float | None = None,
    span: float | None = None,
    half_life: float | None = None,
    alpha: float | None = None,
    min_samples: int = 1,
    ignore_nulls: bool = False,
) → Expr

Вычислить экспоненциально взвешенную скользящую сумму.

движок:В памятиПотоковый

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без объявления таких изменений нарушающими обратную совместимость.

Параметры:

com: Задать затухание через центр масс, $\gamma$, где

\[\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0\]
span: Задать затухание через интервал, $\theta$, где

\[\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1\]
half_life: Задать затухание через период полураспада, $\tau$, где

\[\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \tau } \right\} \; \forall \; \tau > 0\]
alpha: Задать коэффициент сглаживания alpha напрямую: $0 < \alpha \leq 1$.
min_samples: Минимальное количество наблюдений в окне, необходимое для получения значения (иначе результат будет null).
ignore_nulls: Не учитывать пропущенные значения при вычислении весов.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").ewm_sum(alpha=0.5))
shape: (3, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ 1.0  │
│ 2.5  │
│ 4.25 │
└──────┘

ewm_sum_by(
    by: str_ | IntoExpr,
    *,
    half_life: str_ | timedelta,
) → Expr

Вычислить экспоненциально взвешенную скользящую сумму с учетом времени.

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

Для наблюдений $x_0, x_1, \ldots, x_{n-1}$ в моменты времени $t_0, t_1, \ldots, t_{n-1}$ EWMS вычисляется следующим образом:

\[ \begin{align}\begin{aligned}y_0 &= x_0\\\lambda_i &= \exp \left\{ \frac{ -\ln(2)(t_i-t_{i-1}) } { \tau } \right\}\\y_i &= x_i + \lambda_i y_{i-1}; \quad i > 0\end{aligned}\end{align} \]

где $\tau$ — half_life.

движок:В памяти

Параметры:

by: Столбец, используемый как источник данных о временном затухании.
half_life: Период полураспада экспоненциального затухания.

Примеры

>>> df = pl.DataFrame(
...     {
...         "values": [1, 2, 3, 4, 5],
...         "times": [0, 1, 2, 5, 6],
...     }
... )
>>> df.select(
...     pl.col("values").ewm_sum_by("times", half_life="1i"),
... )
shape: (5, 1)
┌──────────┐
│ values   │
│ ---      │
│ f64      │
╞══════════╡
│ 1.0      │
│ 2.5      │
│ 4.25     │
│ 4.53125  │
│ 7.265625 │
└──────────┘

ewm_var(
    *,
    com: float | None = None,
    span: float | None = None,
    half_life: float | None = None,
    alpha: float | None = None,
    adjust: bool = True,
    bias: bool = False,
    min_samples: int = 1,
    ignore_nulls: bool = False,
) → Expr

Вычислить экспоненциально взвешенную скользящую дисперсию.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

com

Задать затухание через центр масс, $\gamma$, где

\[\alpha = \frac{1}{1 + \gamma} \; \forall \; \gamma \geq 0\]

span

Задать затухание через интервал, $\theta$, где

\[\alpha = \frac{2}{\theta + 1} \; \forall \; \theta \geq 1\]

half_life

Задать затухание через период полураспада, $\lambda$, где

\[\alpha = 1 - \exp \left\{ \frac{ -\ln(2) }{ \lambda } \right\} \; \forall \; \lambda > 0\]

alpha

Задать коэффициент сглаживания alpha напрямую: $0 < \alpha \leq 1$.

adjust

Если adjust=True (значение по умолчанию), функция EW вычисляется с использованием весов $w_i = (1 - \alpha)^i$
Если adjust=False, функция EW вычисляется рекурсивно:

\[\begin{split}y_0 &= x_0 \\ y_t &= (1 - \alpha)y_{t - 1} + \alpha x_t\end{split}\]

bias

Если bias=False, применить поправку, чтобы оценка была статистически несмещенной.

min_samples

Минимальное количество наблюдений в окне, необходимое для получения значения (иначе результат будет null).

ignore_nulls

Не учитывать пропущенные значения при вычислении весов.

Если ignore_nulls=False (значение по умолчанию), веса основаны на абсолютных позициях. Например, веса $x_0$ и $x_2$, используемые при вычислении итогового взвешенного среднего для [$x_0$, None, $x_2$], равны $(1-\alpha)^2$ и $1$, если adjust=True, и $(1-\alpha)^2$ и $\alpha$, если adjust=False.
Если ignore_nulls=True, веса основаны на относительных позициях. Например, веса $x_0$ и $x_2$, используемые при вычислении итогового взвешенного среднего для [$x_0$, None, $x_2$], равны $1-\alpha$ и $1$, если adjust=True, и $1-\alpha$ и $\alpha$, если adjust=False.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").ewm_var(com=1, ignore_nulls=False))
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ null     │
│ 0.5      │
│ 0.928571 │
└──────────┘

exclude(
    columns: str_ | PolarsDataType | Collection[str_ | PolarsDataType],
    *more_columns: str_ | PolarsDataType,
) → Expr

Исключить столбцы из выражения с несколькими столбцами.

Работает только после выбора столбцов с помощью шаблона или регулярного выражения. Нельзя одновременно указывать строковые имена столбцов и типы данных (вместо этого можно использовать селекторы).

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

Параметры:

columns: Имя или тип данных столбца(-ов), которые нужно исключить. Принимает регулярное выражение. Регулярные выражения должны начинаться с ^ и заканчиваться на $.
*more_columns: Дополнительные имена или типы данных столбцов для исключения, передаваемые как позиционные аргументы.

Примеры

>>> df = pl.DataFrame(
...     {
...         "aa": [1, 2, 3],
...         "ba": ["a", "b", None],
...         "cc": [None, 2.5, 1.5],
...     }
... )
>>> df
shape: (3, 3)
┌─────┬──────┬──────┐
│ aa  ┆ ba   ┆ cc   │
│ --- ┆ ---  ┆ ---  │
│ i64 ┆ str  ┆ f64  │
╞═════╪══════╪══════╡
│ 1   ┆ a    ┆ null │
│ 2   ┆ b    ┆ 2.5  │
│ 3   ┆ null ┆ 1.5  │
└─────┴──────┴──────┘

Исключение по имени столбца(-ов):

>>> df.select(pl.all().exclude("ba"))
shape: (3, 2)
┌─────┬──────┐
│ aa  ┆ cc   │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ null │
│ 2   ┆ 2.5  │
│ 3   ┆ 1.5  │
└─────┴──────┘

Исключение по регулярному выражению, например удаление всех столбцов, имена которых оканчиваются на букву «a»:

>>> df.select(pl.all().exclude("^.*a$"))
shape: (3, 1)
┌──────┐
│ cc   │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ 2.5  │
│ 1.5  │
└──────┘

Исключение по типу(-ам) данных, например удаление всех столбцов типа Int64 или Float64:

>>> df.select(pl.all().exclude([pl.Int64, pl.Float64]))
shape: (3, 1)
┌──────┐
│ ba   │
│ ---  │
│ str  │
╞══════╡
│ a    │
│ b    │
│ null │
└──────┘

exp() → Expr

Вычислить экспоненту поэлементно.

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

Примеры

>>> df = pl.DataFrame({"values": [1.0, 2.0, 4.0]})
>>> df.select(pl.col("values").exp())
shape: (3, 1)
┌──────────┐
│ values   │
│ ---      │
│ f64      │
╞══════════╡
│ 2.718282 │
│ 7.389056 │
│ 54.59815 │
└──────────┘

explode(
    *,
    empty_as_null: bool = <object object>,
    keep_nulls: bool = True,
) → Expr

Развернуть выражение списка.

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

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

Параметры:

empty_as_null: Развернуть пустой список/массив в null.
keep_nulls: Развернуть список/массив null в null.

Возвращает:

Expr: Выражение с типом данных элементов списка.

См. также

Expr.list.explode: Развернуть столбец списка.

Примеры

>>> df = pl.DataFrame(
...     {
...         "group": ["a", "b"],
...         "values": [
...             [1, 2],
...             [3, 4],
...         ],
...     }
... )
>>> df.select(pl.col("values").explode(empty_as_null=False))
shape: (4, 1)
┌────────┐
│ values │
│ ---    │
│ i64    │
╞════════╡
│ 1      │
│ 2      │
│ 3      │
│ 4      │
└────────┘

extend_constant(
    value: IntoExpr,
    n: int | IntoExprColumn,
) → Expr

Чрезвычайно быстрый метод расширения Series на ‘n’ копий значения.

движок:В памяти

Параметры:

value: Постоянное литеральное значение или выражение с единичным значением, которым нужно расширить результирующий Series выражения; можно передать None, чтобы заполнить null-значениями.
n: Количество дополнительных значений, которые будут добавлены.

Примеры

>>> df = pl.DataFrame({"values": [1, 2, 3]})
>>> df.select((pl.col("values") - 1).extend_constant(99, n=2))
shape: (5, 1)
┌────────┐
│ values │
│ ---    │
│ i64    │
╞════════╡
│ 0      │
│ 1      │
│ 2      │
│ 99     │
│ 99     │
└────────┘

fill_nan(
    value: int | float | Expr | None,
) → Expr

Заменить значение NaN с плавающей точкой заданным значением.

движок:В памятиПотоковый

Параметры:

value: Значение для замены значений NaN.

См. также

fill_null

Примечания

Значение NaN — это не то же самое, что значение null. Чтобы заполнить значения null, используйте fill_null().

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1.0, None, float("nan")],
...         "b": [4.0, float("nan"), 6],
...     }
... )
>>> df.with_columns(pl.col("b").fill_nan(0))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ f64  ┆ f64 │
╞══════╪═════╡
│ 1.0  ┆ 4.0 │
│ null ┆ 0.0 │
│ NaN  ┆ 6.0 │
└──────┴─────┘

fill_null(
    value: Any | Expr | None = None,
    strategy: FillNullStrategy | None = None,
    limit: int | None = None,
) → Expr

Заполняет значения null указанным значением или стратегией.

Чтобы интерполировать значения null, см. interpolate. Примеры заполнения null выражением приведены ниже.

движок:В памятиПотоковая обработка

Параметры:

value: Значение, используемое для заполнения значений null.
strategy{None, ‘forward’, ‘backward’, ‘min’, ‘max’, ‘mean’, ‘zero’, ‘one’}: Стратегия, используемая для заполнения значений null.
limit: Количество последовательных значений null для заполнения при использовании стратегии ‘forward’ или ‘backward’.

См. также

backward_fill
fill_nan
forward_fill

Примечания

Значение null — это не то же самое, что значение NaN. Для заполнения значений NaN используйте fill_nan().

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None],
...         "b": [4, None, 6],
...     }
... )
>>> df.with_columns(pl.col("b").fill_null(strategy="zero"))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ i64  ┆ i64 │
╞══════╪═════╡
│ 1    ┆ 4   │
│ 2    ┆ 0   │
│ null ┆ 6   │
└──────┴─────┘
>>> df.with_columns(pl.col("b").fill_null(99))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ i64  ┆ i64 │
╞══════╪═════╡
│ 1    ┆ 4   │
│ 2    ┆ 99  │
│ null ┆ 6   │
└──────┴─────┘
>>> df.with_columns(pl.col("b").fill_null(strategy="forward"))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ i64  ┆ i64 │
╞══════╪═════╡
│ 1    ┆ 4   │
│ 2    ┆ 4   │
│ null ┆ 6   │
└──────┴─────┘
>>> df.with_columns(pl.col("b").fill_null(pl.col("b").median()))
shape: (3, 2)
┌──────┬─────┐
│ a    ┆ b   │
│ ---  ┆ --- │
│ i64  ┆ f64 │
╞══════╪═════╡
│ 1    ┆ 4.0 │
│ 2    ┆ 5.0 │
│ null ┆ 6.0 │
└──────┴─────┘
>>> df.with_columns(pl.all().fill_null(pl.all().median()))
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 1.0 ┆ 4.0 │
│ 2.0 ┆ 5.0 │
│ 1.5 ┆ 6.0 │
└─────┴─────┘

filter(
    *predicates: IntoExprColumn | Iterable[IntoExprColumn],
    **constraints: Any,
) → Expr

Фильтрует выражение на основе одного или нескольких выражений-предикатов.

Исходный порядок оставшихся элементов сохраняется.

Элементы, для которых фильтр возвращает не True, отбрасываются, включая значения null.

В основном используется в контексте агрегации. Для фильтрации на уровне DataFrame используйте LazyFrame.filter.

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

predicates: Выражение или выражения, возвращающие логический Series.
constraints: Фильтры столбцов; используйте name = value для фильтрации столбцов по указанному значению. Каждое ограничение работает так же, как pl.col(name).eq(value), и неявно объединяется с другими условиями фильтра с помощью &.

Примеры

>>> df = pl.DataFrame(
...     {
...         "group_col": ["g1", "g1", "g2"],
...         "b": [1, 2, 3],
...     }
... )
>>> df.group_by("group_col").agg(
...     lt=pl.col("b").filter(pl.col("b") < 2).sum(),
...     gte=pl.col("b").filter(pl.col("b") >= 2).sum(),
... ).sort("group_col")
shape: (2, 3)
┌───────────┬─────┬─────┐
│ group_col ┆ lt  ┆ gte │
│ ---       ┆ --- ┆ --- │
│ str       ┆ i64 ┆ i64 │
╞═══════════╪═════╪═════╡
│ g1        ┆ 1   ┆ 2   │
│ g2        ┆ 0   ┆ 3   │
└───────────┴─────┴─────┘

В качестве именованных аргументов выражения фильтрации также могут принимать ограничения.

>>> df = pl.DataFrame(
...     {
...         "key": ["a", "a", "a", "a", "b", "b", "b", "b", "b"],
...         "n": [1, 2, 2, 3, 1, 3, 3, 2, 3],
...     },
... )
>>> df.group_by("key").agg(
...     n_1=pl.col("n").filter(n=1).sum(),
...     n_2=pl.col("n").filter(n=2).sum(),
...     n_3=pl.col("n").filter(n=3).sum(),
... ).sort(by="key")
shape: (2, 4)
┌─────┬─────┬─────┬─────┐
│ key ┆ n_1 ┆ n_2 ┆ n_3 │
│ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╪═════╡
│ a   ┆ 1   ┆ 4   ┆ 3   │
│ b   ┆ 1   ┆ 2   ┆ 9   │
└─────┴─────┴─────┴─────┘

first(
    *,
    ignore_nulls: bool = False,
) → Expr

Получает первое значение.

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

ignore_nulls: Игнорировать значения null (по умолчанию False). Если задано True, возвращается первое ненулевое значение, иначе возвращается None, если ненулевых значений нет.

Примеры

>>> df = pl.DataFrame({"a": [None, 1, 2]})
>>> df.select(pl.col("a").first())
shape: (1, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ null │
└──────┘
>>> df.select(pl.col("a").first(ignore_nulls=True))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
└─────┘

flatten() → Expr

Разворачивает столбец списка или строк.

Псевдоним для Expr.list.explode().

Устарело с версии 1.38: Expr.flatten() устарел и будет удален в версии 2.0. Вместо него используйте Expr.list.explode(keep_nulls=False, empty_as_null=False), который обеспечивает поведение, соответствующее вашим ожиданиям.

Примеры

>>> df = pl.DataFrame(
...     {
...         "group": ["a", "b", "b"],
...         "values": [[1, 2], [2, 3], [4]],
...     }
... )
>>> df.group_by("group").agg(pl.col("values").flatten())  
shape: (2, 2)
┌───────┬───────────┐
│ group ┆ values    │
│ ---   ┆ ---       │
│ str   ┆ list[i64] │
╞═══════╪═══════════╡
│ a     ┆ [1, 2]    │
│ b     ┆ [2, 3, 4] │
└───────┴───────────┘

floor() → Expr

Округляет вниз до ближайшего целого значения.

Работает только с Series с числами с плавающей точкой.

движок:В памятиПотоковая обработкаРаспределенная обработка

См. также

ceil: Округляет вверх до ближайшего целого значения.
round: Округляет до ближайшего целого числа.

Примеры

>>> df = pl.DataFrame({"a": [0.3, 0.5, 1.0, 1.1]})
>>> df.select(pl.col("a").floor())
shape: (4, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
│ 0.0 │
│ 1.0 │
│ 1.0 │
└─────┘

floordiv(
    other: Any,
) → Expr

Эквивалент метода для оператора целочисленного деления expr // other.

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

other: Числовой литерал или значение выражения.

См. также

truediv

Примеры

>>> df = pl.DataFrame({"x": [1, 2, 3, 4, 5]})
>>> df.with_columns(
...     pl.col("x").truediv(2).alias("x/2"),
...     pl.col("x").floordiv(2).alias("x//2"),
... )
shape: (5, 3)
┌─────┬─────┬──────┐
│ x   ┆ x/2 ┆ x//2 │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ f64 ┆ i64  │
╞═════╪═════╪══════╡
│ 1   ┆ 0.5 ┆ 0    │
│ 2   ┆ 1.0 ┆ 1    │
│ 3   ┆ 1.5 ┆ 1    │
│ 4   ┆ 2.0 ┆ 2    │
│ 5   ┆ 2.5 ┆ 2    │
└─────┴─────┴──────┘

Обратите внимание, что floordiv в Polars немного отличается от целочисленного деления с округлением вниз в Python. Например, рассмотрим деление 6.0 на 0.1 с округлением вниз. В Python результат:

>>> 6.0 // 0.1
59.0

поскольку 0.1 не представлено внутри системы точно этим значением, а имеет немного большее значение. Поэтому результат деления немного меньше 60, и операция округления вниз возвращает 59.0.

В Polars сначала выполняется деление чисел с плавающей точкой, в результате которого получается значение с плавающей точкой 60.0, а затем выполняется округление вниз с помощью floor:

>>> df = pl.DataFrame({"x": [6.0, 6.03]})
>>> df.with_columns(
...     pl.col("x").truediv(0.1).alias("x/0.1"),
... ).with_columns(
...     pl.col("x/0.1").floor().alias("x/0.1 floor"),
... )
shape: (2, 3)
┌──────┬───────┬─────────────┐
│ x    ┆ x/0.1 ┆ x/0.1 floor │
│ ---  ┆ ---   ┆ ---         │
│ f64  ┆ f64   ┆ f64         │
╞══════╪═══════╪═════════════╡
│ 6.0  ┆ 60.0  ┆ 60.0        │
│ 6.03 ┆ 60.3  ┆ 60.0        │
└──────┴───────┴─────────────┘

в результате получается более интуитивное значение 60.0. Строка, где x = 6.03, включена, чтобы продемонстрировать эффект округления вниз.

floordiv объединяет эти два шага в одном выражении и возвращает тот же результат:

>>> df.with_columns(
...     pl.col("x").floordiv(0.1).alias("x//0.1"),
... )
shape: (2, 2)
┌──────┬────────┐
│ x    ┆ x//0.1 │
│ ---  ┆ ---    │
│ f64  ┆ f64    │
╞══════╪════════╡
│ 6.0  ┆ 60.0   │
│ 6.03 ┆ 60.0   │
└──────┴────────┘

forward_fill(
    limit: int | None = None,
) → Expr

Заполняет пропущенные значения последним ненулевым значением.

Это псевдоним для .fill_null(strategy="forward").

движок:В памятиПотоковая обработка

Параметры:

limit: Количество последовательных значений null для заполнения предыдущим значением.

См. также

backward_fill
fill_null
shift

classmethod from_json(
    value: str_,
) → Expr

Считывает выражение из строки в формате JSON для создания Expression.

Устарело с версии 0.20.11: Этот метод переименован в deserialize(). Обратите внимание, что новый метод принимает файловые объекты вместо строк. Чтобы сохранить прежнее поведение, оберните ввод в io.StringIO.

Параметры:

value: Строковое значение в формате JSON

gather(
    indices: int | Sequence[int] | IntoExpr | Series | np.ndarray[Any,
    Any],
    *,
    null_on_oob: bool = False,
) → Expr

Извлекает значения по индексам.

движок:В памятиПотоковая обработка

Параметры:

indices

Выражение, результатом которого является Series типа UInt32.

null_on_oob

Поведение при выходе индекса за границы:

True -> установить для результата значение null
False -> вызвать ошибку

Возвращает:

Expr: Выражение того же типа данных.

См. также

Expr.get: Извлекает одно значение

Примеры

>>> df = pl.DataFrame(
...     {
...         "group": [
...             "one",
...             "one",
...             "one",
...             "two",
...             "two",
...             "two",
...         ],
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.group_by("group", maintain_order=True).agg(
...     pl.col("value").gather([2, 1])
... )
shape: (2, 2)
┌───────┬───────────┐
│ group ┆ value     │
│ ---   ┆ ---       │
│ str   ┆ list[i64] │
╞═══════╪═══════════╡
│ one   ┆ [2, 98]   │
│ two   ┆ [4, 99]   │
└───────┴───────────┘

Используйте null_on_oob=True, чтобы возвращать null для индексов, выходящих за границы.

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").gather([0, 1, 10], null_on_oob=True))
shape: (3, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ 1    │
│ 2    │
│ null │
└──────┘

gather_every(
    n: int,
    offset: int = 0,
) → Expr

Извлекает каждое n-е значение Series и возвращает его в виде нового Series.

движок:В памятиПотоковая обработка

Параметры:

n: Извлекать каждую n-ю строку.
offset: Начальный индекс.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5, 6, 7, 8, 9]})
>>> df.select(pl.col("foo").gather_every(3))
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 4   │
│ 7   │
└─────┘

>>> df.select(pl.col("foo").gather_every(3, offset=1))
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 2   │
│ 5   │
│ 8   │
└─────┘

ge(
    other: Any,
) → Expr

Эквивалент метода для оператора «больше или равно» expr >= other.

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

other: Литерал или значение выражения для сравнения.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [5.0, 4.0, float("nan"), 2.0],
...         "y": [5.0, 3.0, float("nan"), 1.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").ge(pl.col("y")).alias("x >= y"),
... )
shape: (4, 3)
┌─────┬─────┬────────┐
│ x   ┆ y   ┆ x >= y │
│ --- ┆ --- ┆ ---    │
│ f64 ┆ f64 ┆ bool   │
╞═════╪═════╪════════╡
│ 5.0 ┆ 5.0 ┆ true   │
│ 4.0 ┆ 3.0 ┆ true   │
│ NaN ┆ NaN ┆ true   │
│ 2.0 ┆ 1.0 ┆ true   │
└─────┴─────┴────────┘

get(
    index: int | Expr,
    *,
    null_on_oob: bool = False,
) → Expr

Возвращает одно значение по индексу.

движок:В памятиЧастичная потоковая обработка

Параметры:

index

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

null_on_oob

Поведение при выходе индекса за границы:

True -> установить для результата значение null
False -> вызвать ошибку

Возвращает:

Expr: Выражение того же типа данных.

Примеры

>>> df = pl.DataFrame(
...     {
...         "group": [
...             "one",
...             "one",
...             "one",
...             "two",
...             "two",
...             "two",
...         ],
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.group_by("group", maintain_order=True).agg(pl.col("value").get(1))
shape: (2, 2)
┌───────┬───────┐
│ group ┆ value │
│ ---   ┆ ---   │
│ str   ┆ i64   │
╞═══════╪═══════╡
│ one   ┆ 98    │
│ two   ┆ 99    │
└───────┴───────┘

gt(
    other: Any,
) → Expr

Эквивалент метода для оператора «больше» expr > other.

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

other: Литерал или значение выражения для сравнения.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [5.0, 4.0, float("nan"), 2.0],
...         "y": [5.0, 3.0, float("nan"), 1.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").gt(pl.col("y")).alias("x > y"),
... )
shape: (4, 3)
┌─────┬─────┬───────┐
│ x   ┆ y   ┆ x > y │
│ --- ┆ --- ┆ ---   │
│ f64 ┆ f64 ┆ bool  │
╞═════╪═════╪═══════╡
│ 5.0 ┆ 5.0 ┆ false │
│ 4.0 ┆ 3.0 ┆ true  │
│ NaN ┆ NaN ┆ false │
│ 2.0 ┆ 1.0 ┆ true  │
└─────┴─────┴───────┘

has_nulls() → Expr

Проверяет, содержит ли выражение одно или несколько значений null.

движок:В памятиПотоковая обработка

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [None, 1, None],
...         "b": [10, None, 300],
...         "c": [350, 650, 850],
...     }
... )
>>> df.select(pl.all().has_nulls())
shape: (1, 3)
┌──────┬──────┬───────┐
│ a    ┆ b    ┆ c     │
│ ---  ┆ ---  ┆ ---   │
│ bool ┆ bool ┆ bool  │
╞══════╪══════╪═══════╡
│ true ┆ true ┆ false │
└──────┴──────┴───────┘

hash(
    seed: int = 0,
    seed_1: int | None = None,
    seed_2: int | None = None,
    seed_3: int | None = None,
) → Expr

Вычисляет хеш элементов в выборке.

Хеш имеет тип UInt64.

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

seed: Параметр начального значения генератора случайных чисел. По умолчанию равен 0.
seed_1: Параметр начального значения генератора случайных чисел. Если не задан, по умолчанию равен seed.
seed_2: Параметр начального значения генератора случайных чисел. Если не задан, по умолчанию равен seed.
seed_3: Параметр начального значения генератора случайных чисел. Если не задан, по умолчанию равен seed.

Примечания

Эта реализация hash не гарантирует стабильность результатов в разных версиях Polars. Стабильность гарантируется только в рамках одной версии.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None],
...         "b": ["x", None, "z"],
...     }
... )
>>> df.with_columns(pl.all().hash(10, 20, 30, 40))  
shape: (3, 2)
┌──────────────────────┬──────────────────────┐
│ a                    ┆ b                    │
│ ---                  ┆ ---                  │
│ u64                  ┆ u64                  │
╞══════════════════════╪══════════════════════╡
│ 9774092659964970114  ┆ 13614470193936745724 │
│ 1101441246220388612  ┆ 11638928888656214026 │
│ 11638928888656214026 ┆ 13382926553367784577 │
└──────────────────────┴──────────────────────┘

head(
    n: int | Expr = 10,
) → Expr

Получает первые n строк.

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

n: Количество возвращаемых строк.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5, 6, 7]})
>>> df.select(pl.col("foo").head(3))
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

hist(
    bins: IntoExpr | None = None,
    *,
    bin_count: int | None = None,
    include_category: bool = False,
    include_breakpoint: bool = False,
) → Expr

Распределяет значения по интервалам и подсчитывает количество попаданий в каждый из них.

движок:В памяти

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент, и это не будет считаться нарушением обратной совместимости.

Параметры:

bins: Границы интервалов. Если значение не указано, границы определяются на основе данных.
bin_count: Если bins не задан, создаются bin_count равномерных интервалов, полностью охватывающих данные.
include_breakpoint: Добавить столбец с указанием верхней границы интервала.
include_category: Добавить столбец, представляющий интервалы в виде категорий.

Возвращает:

DataFrame

Примеры

>>> df = pl.DataFrame({"a": [1, 3, 8, 8, 2, 1, 3]})
>>> df.select(pl.col("a").hist(bins=[1, 2, 3]))
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 3   │
│ 2   │
└─────┘
>>> df.select(
...     pl.col("a").hist(
...         bins=[1, 2, 3], include_breakpoint=True, include_category=True
...     )
... )
shape: (2, 1)
┌──────────────────────┐
│ a                    │
│ ---                  │
│ struct[3]            │
╞══════════════════════╡
│ {2.0,"[1.0, 2.0]",3} │
│ {3.0,"(2.0, 3.0]",2} │
└──────────────────────┘

implode(
    *,
    maintain_order: bool = True,
) → Expr

Агрегирует значения в список.

Сам возвращаемый список является скалярным значением типа list.

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

maintain_order: Следует ли сохранять порядок элементов в списке. Значение False может повысить производительность, особенно в рамках group_by.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": [4, 5, 6],
...     }
... )
>>> df.select(pl.all().implode())
shape: (1, 2)
┌───────────┬───────────┐
│ a         ┆ b         │
│ ---       ┆ ---       │
│ list[i64] ┆ list[i64] │
╞═══════════╪═══════════╡
│ [1, 2, 3] ┆ [4, 5, 6] │
└───────────┴───────────┘

index_of(
    element: IntoExpr,
) → Expr

Получает индекс первого вхождения значения или None, если оно не найдено.

движок:В памятиПотоковая обработка

Параметры:

element: Искомое значение.

Примеры

>>> df = pl.DataFrame({"a": [1, None, 17]})
>>> df.select(
...     [
...         pl.col("a").index_of(17).alias("seventeen"),
...         pl.col("a").index_of(None).alias("null"),
...         pl.col("a").index_of(55).alias("fiftyfive"),
...     ]
... )
shape: (1, 3)
┌───────────┬──────┬───────────┐
│ seventeen ┆ null ┆ fiftyfive │
│ ---       ┆ ---  ┆ ---       │
│ u32       ┆ u32  ┆ u32       │
╞═══════════╪══════╪═══════════╡
│ 2         ┆ 1    ┆ null      │
└───────────┴──────┴───────────┘

inspect(
    fmt: str_ = '{}',
) → Expr

Выводит значение, вычисленное этим выражением, и передает его дальше.

движок:В памятиПотоковая обработкаРаспределенная обработка

Примеры

>>> df = pl.DataFrame({"foo": [1, 1, 2]})
>>> df.select(pl.col("foo").cum_sum().inspect("value is: {}").alias("bar"))
value is: shape: (3,)
Series: 'foo' [i64]
[
    1
    2
    4
]
shape: (3, 1)
┌─────┐
│ bar │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 4   │
└─────┘

interpolate(
    method: InterpolationMethod = 'linear',
) → Expr

Интерполирует промежуточные значения.

Значения null в начале и конце последовательности остаются null.

движок:В памятиПотоковая обработка

Параметры:

method{‘linear’, ‘nearest’}: Метод интерполяции.

Примеры

Заполнение значений null с помощью линейной интерполяции.

>>> df = pl.DataFrame(
...     {
...         "a": [1, None, 3],
...         "b": [1.0, float("nan"), 3.0],
...     }
... )
>>> df.select(pl.all().interpolate())
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ f64 ┆ f64 │
╞═════╪═════╡
│ 1.0 ┆ 1.0 │
│ 2.0 ┆ NaN │
│ 3.0 ┆ 3.0 │
└─────┴─────┘

Заполнение значений null с помощью интерполяции ближайшим значением.

>>> df.select(pl.all().interpolate("nearest"))
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ f64 │
╞═════╪═════╡
│ 1   ┆ 1.0 │
│ 3   ┆ NaN │
│ 3   ┆ 3.0 │
└─────┴─────┘

Пересчет сетки данных на новую сетку.

>>> df_original_grid = pl.DataFrame(
...     {
...         "grid_points": [1, 3, 10],
...         "values": [2.0, 6.0, 20.0],
...     }
... )  # Interpolate from this to the new grid
>>> df_new_grid = pl.DataFrame({"grid_points": range(1, 11)})
>>> df_new_grid.join(
...     df_original_grid, on="grid_points", how="left", coalesce=True
... ).with_columns(pl.col("values").interpolate())
shape: (10, 2)
┌─────────────┬────────┐
│ grid_points ┆ values │
│ ---         ┆ ---    │
│ i64         ┆ f64    │
╞═════════════╪════════╡
│ 1           ┆ 2.0    │
│ 2           ┆ 4.0    │
│ 3           ┆ 6.0    │
│ 4           ┆ 8.0    │
│ 5           ┆ 10.0   │
│ 6           ┆ 12.0   │
│ 7           ┆ 14.0   │
│ 8           ┆ 16.0   │
│ 9           ┆ 18.0   │
│ 10          ┆ 20.0   │
└─────────────┴────────┘

interpolate_by(
    by: IntoExpr,
) → Expr

Заполняет значения null с помощью интерполяции на основе другого столбца.

Значения null в начале и конце последовательности остаются null.

движок:В памяти

Параметры:

by: Столбец, на основе которого интерполируются значения.

Примеры

Заполнение значений null с помощью линейной интерполяции.

>>> df = pl.DataFrame(
...     {
...         "a": [1, None, None, 3],
...         "b": [1, 2, 7, 8],
...     }
... )
>>> df.with_columns(a_interpolated=pl.col("a").interpolate_by("b"))
shape: (4, 3)
┌──────┬─────┬────────────────┐
│ a    ┆ b   ┆ a_interpolated │
│ ---  ┆ --- ┆ ---            │
│ i64  ┆ i64 ┆ f64            │
╞══════╪═════╪════════════════╡
│ 1    ┆ 1   ┆ 1.0            │
│ null ┆ 2   ┆ 1.285714       │
│ null ┆ 7   ┆ 2.714286       │
│ 3    ┆ 8   ┆ 3.0            │
└──────┴─────┴────────────────┘

is_between(
    lower_bound: IntoExpr,
    upper_bound: IntoExpr,
    closed: ClosedInterval = 'both',
) → Expr

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

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

lower_bound: Значение нижней границы. Принимает выражение. Строки интерпретируются как имена столбцов, а другие значения, не являющиеся выражениями, — как литералы.
upper_bound: Значение верхней границы. Принимает выражение. Строки интерпретируются как имена столбцов, а другие значения, не являющиеся выражениями, — как литералы.
closed{‘both’, ‘left’, ‘right’, ‘none’}: Определяет, какие границы интервала включаются в него.

Возвращает:

Expr: Выражение типа данных Boolean.

Примечания

Если значение lower_bound больше значения upper_bound, результат будет False, поскольку ни одно значение не может удовлетворять этому условию.

Примеры

>>> df = pl.DataFrame({"num": [1, 2, 3, 4, 5]})
>>> df.with_columns(pl.col("num").is_between(2, 4).alias("is_between"))
shape: (5, 2)
┌─────┬────────────┐
│ num ┆ is_between │
│ --- ┆ ---        │
│ i64 ┆ bool       │
╞═════╪════════════╡
│ 1   ┆ false      │
│ 2   ┆ true       │
│ 3   ┆ true       │
│ 4   ┆ true       │
│ 5   ┆ false      │
└─────┴────────────┘

Используйте аргумент closed, чтобы включить или исключить значения на границах:

>>> df.with_columns(
...     pl.col("num").is_between(2, 4, closed="left").alias("is_between")
... )
shape: (5, 2)
┌─────┬────────────┐
│ num ┆ is_between │
│ --- ┆ ---        │
│ i64 ┆ bool       │
╞═════╪════════════╡
│ 1   ┆ false      │
│ 2   ┆ true       │
│ 3   ┆ true       │
│ 4   ┆ false      │
│ 5   ┆ false      │
└─────┴────────────┘

Можно также использовать строки, а также числовые и временные значения (примечание: строковые литералы следует заключать в lit, чтобы не путать их с именами столбцов):

>>> df = pl.DataFrame({"a": ["a", "b", "c", "d", "e"]})
>>> df.with_columns(
...     pl.col("a")
...     .is_between(pl.lit("a"), pl.lit("c"), closed="both")
...     .alias("is_between")
... )
shape: (5, 2)
┌─────┬────────────┐
│ a   ┆ is_between │
│ --- ┆ ---        │
│ str ┆ bool       │
╞═════╪════════════╡
│ a   ┆ true       │
│ b   ┆ true       │
│ c   ┆ true       │
│ d   ┆ false      │
│ e   ┆ false      │
└─────┴────────────┘

Используйте выражения столбцов в качестве нижней и верхней границ для сравнения с литеральным значением:

>>> df = pl.DataFrame({"a": [1, 2, 3, 4, 5], "b": [5, 4, 3, 2, 1]})
>>> df.with_columns(
...     pl.lit(3).is_between(pl.col("a"), pl.col("b")).alias("between_ab")
... )
shape: (5, 3)
┌─────┬─────┬────────────┐
│ a   ┆ b   ┆ between_ab │
│ --- ┆ --- ┆ ---        │
│ i64 ┆ i64 ┆ bool       │
╞═════╪═════╪════════════╡
│ 1   ┆ 5   ┆ true       │
│ 2   ┆ 4   ┆ true       │
│ 3   ┆ 3   ┆ true       │
│ 4   ┆ 2   ┆ false      │
│ 5   ┆ 1   ┆ false      │
└─────┴─────┴────────────┘

is_close(
    other: IntoExpr,
    *,
    abs_tol: float = 0.0,
    rel_tol: float = 1e-09,
    nans_equal: bool = False,
) → Expr

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

Два значения a и b считаются близкими, если выполняется следующее условие:

\[|a-b| \le max \{ \text{rel_tol} \cdot max \{ |a|, |b| \}, \text{abs_tol} \}\]

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

other: Литерал или значение выражения для сравнения.
abs_tol: Абсолютная погрешность. Это максимально допустимая абсолютная разница между двумя значениями. Должна быть неотрицательной.
rel_tol: Относительная погрешность. Это максимально допустимая разница между двумя значениями относительно большего абсолютного значения. Должна быть неотрицательной.
nans_equal: Следует ли считать значения NaN равными.

Возвращает:

Expr: Выражение типа данных Boolean.

Примечания

Реализация этого метода симметрична и соответствует поведению math.isclose(). Обратите внимание, что это поведение отличается от numpy.isclose().

Примеры

>>> df = pl.DataFrame({"a": [1.5, 2.0, 2.5], "b": [1.55, 2.2, 3.0]})
>>> df.with_columns(pl.col("a").is_close("b", abs_tol=0.1).alias("is_close"))
shape: (3, 3)
┌─────┬──────┬──────────┐
│ a   ┆ b    ┆ is_close │
│ --- ┆ ---  ┆ ---      │
│ f64 ┆ f64  ┆ bool     │
╞═════╪══════╪══════════╡
│ 1.5 ┆ 1.55 ┆ true     │
│ 2.0 ┆ 2.2  ┆ false    │
│ 2.5 ┆ 3.0  ┆ false    │
└─────┴──────┴──────────┘

is_duplicated() → Expr

Возвращает логическую маску, указывающую на дублирующиеся значения.

движок:В памяти

Возвращает:

Expr: Выражение типа данных Boolean.

Примеры

>>> df = pl.DataFrame({"a": [1, 1, 2]})
>>> df.select(pl.col("a").is_duplicated())
shape: (3, 1)
┌───────┐
│ a     │
│ ---   │
│ bool  │
╞═══════╡
│ true  │
│ true  │
│ false │
└───────┘

is_empty(
    *,
    ignore_nulls: bool = False,
) → Expr

Возвращает, является ли столбец пустым.

движок:В памятиПотоковая обработка

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

Параметры:

ignore_nulls: Если значение равно true, столбец, содержащий только значения null, также будет считаться пустым. По умолчанию задано false.

Возвращает:

Expr: Выражение типа данных Boolean.

Примеры

>>> df = pl.DataFrame({"x": [None, None]})
>>> df.select(
...     a=pl.col.x.is_empty(),
...     b=pl.col.x.drop_nulls().is_empty(),
...     c=pl.col.x.is_empty(ignore_nulls=True),
... )
shape: (1, 3)
┌───────┬──────┬──────┐
│ a     ┆ b    ┆ c    │
│ ---   ┆ ---  ┆ ---  │
│ bool  ┆ bool ┆ bool │
╞═══════╪══════╪══════╡
│ false ┆ true ┆ true │
└───────┴──────┴──────┘

is_finite() → Expr

Возвращает логический Series, указывающий, какие значения являются конечными.

движок:В памятиПотоковая обработкаРаспределенная обработка

Возвращает:

Expr: Выражение типа данных Boolean.

Примеры

>>> df = pl.DataFrame(
...     {
...         "A": [1.0, 2],
...         "B": [3.0, float("inf")],
...     }
... )
>>> df.select(pl.all().is_finite())
shape: (2, 2)
┌──────┬───────┐
│ A    ┆ B     │
│ ---  ┆ ---   │
│ bool ┆ bool  │
╞══════╪═══════╡
│ true ┆ true  │
│ true ┆ false │
└──────┴───────┘

is_first_distinct() → Expr

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

движок:В памятиПотоковая обработка

Возвращает:

Expr: Выражение типа данных Boolean.

Примеры

>>> df = pl.DataFrame({"a": [1, 1, 2, 3, 2]})
>>> df.with_columns(pl.col("a").is_first_distinct().alias("first"))
shape: (5, 2)
┌─────┬───────┐
│ a   ┆ first │
│ --- ┆ ---   │
│ i64 ┆ bool  │
╞═════╪═══════╡
│ 1   ┆ true  │
│ 1   ┆ false │
│ 2   ┆ true  │
│ 3   ┆ true  │
│ 2   ┆ false │
└─────┴───────┘

is_in(
    other: Expr | Collection[Any] | Series,
    *,
    nulls_equal: bool = False,
) → Expr

Проверяет, содержатся ли элементы этого выражения в другом Series.

движок:В памятиПотоковая обработкаРаспределенная обработка

Параметры:

other: Series или последовательность примитивного типа.
nulls_equalbool, default False: Если значение равно True, null считается отдельным значением. Значения null не распространяются.

Возвращает:

Expr: Выражение типа данных Boolean.

Примеры

>>> df = pl.DataFrame(
...     {"sets": [[1, 2, 3], [1, 2], [9, 10]], "optional_members": [1, 2, 3]}
... )
>>> df.with_columns(contains=pl.col("optional_members").is_in("sets"))
shape: (3, 3)
┌───────────┬──────────────────┬──────────┐
│ sets      ┆ optional_members ┆ contains │
│ ---       ┆ ---              ┆ ---      │
│ list[i64] ┆ i64              ┆ bool     │
╞═══════════╪══════════════════╪══════════╡
│ [1, 2, 3] ┆ 1                ┆ true     │
│ [1, 2]    ┆ 2                ┆ true     │
│ [9, 10]   ┆ 3                ┆ false    │
└───────────┴──────────────────┴──────────┘

is_infinite() → Expr

Возвращает логический Series, указывающий, какие значения являются бесконечными.

движок:В памятиПотоковая обработкаРаспределенная обработка

Возвращает:

Expr: Выражение типа данных Boolean.

Примеры

>>> df = pl.DataFrame(
...     {
...         "A": [1.0, 2],
...         "B": [3.0, float("inf")],
...     }
... )
>>> df.select(pl.all().is_infinite())
shape: (2, 2)
┌───────┬───────┐
│ A     ┆ B     │
│ ---   ┆ ---   │
│ bool  ┆ bool  │
╞═══════╪═══════╡
│ false ┆ false │
│ false ┆ true  │
└───────┴───────┘

is_last_distinct() → Expr

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

движок:В памяти

Возвращает:

Expr: Выражение типа данных Boolean.

Примеры

>>> df = pl.DataFrame({"a": [1, 1, 2, 3, 2]})
>>> df.with_columns(pl.col("a").is_last_distinct().alias("last"))
shape: (5, 2)
┌─────┬───────┐
│ a   ┆ last  │
│ --- ┆ ---   │
│ i64 ┆ bool  │
╞═════╪═══════╡
│ 1   ┆ false │
│ 1   ┆ true  │
│ 2   ┆ false │
│ 3   ┆ true  │
│ 2   ┆ true  │
└─────┴───────┘

is_nan() → Expr

Возвращает логический Series, указывающий, какие значения являются NaN.

движок:В памятиПотоковая обработкаРаспределенная обработка

Примечания

Числа с плавающей точкой NaN (Not A Number — «не число») не следует путать с пропущенными данными, представленными как Null/None.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None, 1, 5],
...         "b": [1.0, 2.0, float("nan"), 1.0, 5.0],
...     }
... )
>>> df.with_columns(pl.col(pl.Float64).is_nan().name.suffix("_isnan"))
shape: (5, 3)
┌──────┬─────┬─────────┐
│ a    ┆ b   ┆ b_isnan │
│ ---  ┆ --- ┆ ---     │
│ i64  ┆ f64 ┆ bool    │
╞══════╪═════╪═════════╡
│ 1    ┆ 1.0 ┆ false   │
│ 2    ┆ 2.0 ┆ false   │
│ null ┆ NaN ┆ true    │
│ 1    ┆ 1.0 ┆ false   │
│ 5    ┆ 5.0 ┆ false   │
└──────┴─────┴─────────┘

is_not_nan() → Expr

Возвращает булев Series, указывающий, какие значения не являются NaN.

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

Примечания

Числа с плавающей точкой NaN (Not A Number) не следует путать с отсутствующими данными, представленными как Null/None.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None, 1, 5],
...         "b": [1.0, 2.0, float("nan"), 1.0, 5.0],
...     }
... )
>>> df.with_columns(pl.col(pl.Float64).is_not_nan().name.suffix("_is_not_nan"))
shape: (5, 3)
┌──────┬─────┬──────────────┐
│ a    ┆ b   ┆ b_is_not_nan │
│ ---  ┆ --- ┆ ---          │
│ i64  ┆ f64 ┆ bool         │
╞══════╪═════╪══════════════╡
│ 1    ┆ 1.0 ┆ true         │
│ 2    ┆ 2.0 ┆ true         │
│ null ┆ NaN ┆ false        │
│ 1    ┆ 1.0 ┆ true         │
│ 5    ┆ 5.0 ┆ true         │
└──────┴─────┴──────────────┘

is_not_null() → Expr

Возвращает булев Series, указывающий, какие значения не являются null.

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None, 1, 5],
...         "b": [1.0, 2.0, float("nan"), 1.0, 5.0],
...     }
... )
>>> df.with_columns(
...     pl.all().is_not_null().name.suffix("_not_null")  # nan != null
... )
shape: (5, 4)
┌──────┬─────┬────────────┬────────────┐
│ a    ┆ b   ┆ a_not_null ┆ b_not_null │
│ ---  ┆ --- ┆ ---        ┆ ---        │
│ i64  ┆ f64 ┆ bool       ┆ bool       │
╞══════╪═════╪════════════╪════════════╡
│ 1    ┆ 1.0 ┆ true       ┆ true       │
│ 2    ┆ 2.0 ┆ true       ┆ true       │
│ null ┆ NaN ┆ false      ┆ true       │
│ 1    ┆ 1.0 ┆ true       ┆ true       │
│ 5    ┆ 5.0 ┆ true       ┆ true       │
└──────┴─────┴────────────┴────────────┘

is_null() → Expr

Возвращает булев Series, указывающий, какие значения являются null.

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None, 1, 5],
...         "b": [1.0, 2.0, float("nan"), 1.0, 5.0],
...     }
... )
>>> df.with_columns(pl.all().is_null().name.suffix("_isnull"))  # nan != null
shape: (5, 4)
┌──────┬─────┬──────────┬──────────┐
│ a    ┆ b   ┆ a_isnull ┆ b_isnull │
│ ---  ┆ --- ┆ ---      ┆ ---      │
│ i64  ┆ f64 ┆ bool     ┆ bool     │
╞══════╪═════╪══════════╪══════════╡
│ 1    ┆ 1.0 ┆ false    ┆ false    │
│ 2    ┆ 2.0 ┆ false    ┆ false    │
│ null ┆ NaN ┆ true     ┆ false    │
│ 1    ┆ 1.0 ┆ false    ┆ false    │
│ 5    ┆ 5.0 ┆ false    ┆ false    │
└──────┴─────┴──────────┴──────────┘

is_sorted(
    *,
    descending: bool | None = False,
    nulls_last: bool | None = False,
) → Expr

Проверяет, отсортировано ли выражение.

Если descending и/или nulls_last равны None, будут проверены True и False для неуказанных параметров; будет возвращено True, если выражение отсортировано при любой комбинации этих настроек.

движок:В памятиПотоковый

Параметры:

descending: Проверяет, отсортировано ли выражение по убыванию. По умолчанию — False.
nulls_last: При проверке сортировки считать, что значения null расположены в конце. По умолчанию — False.

Возвращает:

Expr: Выражение с типом данных Boolean.

Примеры

Проверка, отсортирован ли столбец по возрастанию.

>>> df = pl.DataFrame({"a": [1, 2, 3, 4]})
>>> df.select(pl.col("a").is_sorted())
shape: (1, 1)
┌──────┐
│ a    │
│ ---  │
│ bool │
╞══════╡
│ true │
└──────┘

Проверка, отсортирован ли столбец по убыванию.

>>> df = pl.DataFrame({"a": [4, 3, 2, 1]})
>>> df.select(pl.col("a").is_sorted(descending=True))
shape: (1, 1)
┌──────┐
│ a    │
│ ---  │
│ bool │
╞══════╡
│ true │
└──────┘

Проверка, отсортирован ли столбец в любом направлении.

>>> df = pl.DataFrame({"a": [4, 3, 2, 1]})
>>> df.select(pl.col("a").is_sorted(descending=None))
shape: (1, 1)
┌──────┐
│ a    │
│ ---  │
│ bool │
╞══════╡
│ true │
└──────┘

is_unique() → Expr

Получить маску уникальных значений.

движок:В памяти

Примеры

>>> df = pl.DataFrame({"a": [1, 1, 2]})
>>> df.select(pl.col("a").is_unique())
shape: (3, 1)
┌───────┐
│ a     │
│ ---   │
│ bool  │
╞═══════╡
│ false │
│ false │
│ true  │
└───────┘

item(
    *,
    allow_empty: bool = False,
) → Expr

Получить единственное значение.

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

Вызывает ошибку, если значение не ровно одно.

Параметры:

allow_empty: Разрешить отсутствие значений; в этом случае вернуть null.

См. также

Expr.get(): Получить одно значение по индексу.

Примеры

>>> df = pl.DataFrame({"a": [1]})
>>> df.select(pl.col("a").item())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
└─────┘
>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").item())
Traceback (most recent call last):
...
polars.exceptions.ComputeError: aggregation 'item' expected a single value, got 3 values
...
>>> df.head(0).select(pl.col("a").item(allow_empty=True))
shape: (1, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ null │
└──────┘

kurtosis(
    *,
    fisher: bool = True,
    bias: bool = True,
) → Expr

Вычислить эксцесс набора данных (по Фишеру или Пирсону).

Эксцесс — это центральный момент четвёртого порядка, делённый на квадрат дисперсии. При использовании определения Фишера из результата вычитается 3.0, чтобы для нормального распределения получить 0.0. Если bias равен False, эксцесс вычисляется с использованием k-статистик, чтобы устранить смещение, возникающее из-за смещённых оценок моментов.

Дополнительную информацию см. в scipy.stats

движок:В памятиПотоковый

Параметры:

fisherbool, optional: Если True, используется определение Фишера (нормальное распределение ==> 0.0). Если False, используется определение Пирсона (нормальное распределение ==> 3.0).
biasbool, optional: Если False, вычисления корректируются с учётом статистического смещения.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3, 2, 1]})
>>> df.select(pl.col("a").kurtosis())
shape: (1, 1)
┌───────────┐
│ a         │
│ ---       │
│ f64       │
╞═══════════╡
│ -1.153061 │
└───────────┘

last(
    *,
    ignore_nulls: bool = False,
) → Expr

Получить последнее значение.

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

Параметры:

ignore_nulls: Игнорировать значения null (по умолчанию False). Если задано значение True, возвращается последнее значение, отличное от null; в противном случае, если таких значений нет, возвращается None.

Примеры

>>> df = pl.DataFrame({"a": [1, 3, 2]})
>>> df.select(pl.col("a").last())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
└─────┘

le(
    other: Any,
) → Expr

Эквивалент метода для оператора «меньше или равно» expr <= other.

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

Параметры:

other: Литерал или значение выражения для сравнения.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [5.0, 4.0, float("nan"), 0.5],
...         "y": [5.0, 3.5, float("nan"), 2.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").le(pl.col("y")).alias("x <= y"),
... )
shape: (4, 3)
┌─────┬─────┬────────┐
│ x   ┆ y   ┆ x <= y │
│ --- ┆ --- ┆ ---    │
│ f64 ┆ f64 ┆ bool   │
╞═════╪═════╪════════╡
│ 5.0 ┆ 5.0 ┆ true   │
│ 4.0 ┆ 3.5 ┆ false  │
│ NaN ┆ NaN ┆ true   │
│ 0.5 ┆ 2.0 ┆ true   │
└─────┴─────┴────────┘

len() → Expr

Возвращает количество элементов в столбце.

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

Значения null учитываются в общем количестве.

Возвращает:

Expr: Выражение с типом данных UInt32.

См. также

count

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3], "b": [None, 4, 4]})
>>> df.select(pl.all().len())
shape: (1, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ u32 ┆ u32 │
╞═════╪═════╡
│ 3   ┆ 3   │
└─────┴─────┘

limit(
    n: int | Expr = 10,
) → Expr

Получить первые n строк (псевдоним для Expr.head()).

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

Параметры:

n: Количество возвращаемых строк.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5, 6, 7]})
>>> df.select(pl.col("foo").limit(3))
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

log(
    base: float | IntoExpr = 2.718281828459045,
) → Expr

Вычислить логарифм по заданному основанию.

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

Параметры:

base: Заданное основание; по умолчанию e

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").log(base=2))
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.0      │
│ 1.0      │
│ 1.584963 │
└──────────┘

log10() → Expr

Поэлементно вычислить логарифм входного массива по основанию 10.

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

Примеры

>>> df = pl.DataFrame({"values": [1.0, 2.0, 4.0]})
>>> df.select(pl.col("values").log10())
shape: (3, 1)
┌─────────┐
│ values  │
│ ---     │
│ f64     │
╞═════════╡
│ 0.0     │
│ 0.30103 │
│ 0.60206 │
└─────────┘

log1p() → Expr

Вычислить натуральный логарифм каждого элемента, увеличенного на единицу.

Вычисляет log(1 + x), но обеспечивает большую численную устойчивость, когда x близко к нулю.

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

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").log1p())
shape: (3, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.693147 │
│ 1.098612 │
│ 1.386294 │
└──────────┘

lower_bound() → Expr

Вычислить нижнюю границу.

Возвращает Series из одного элемента с наименьшим возможным значением для типа данных этого выражения.

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

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3, 2, 1]})
>>> df.select(pl.col("a").lower_bound())
shape: (1, 1)
┌──────────────────────┐
│ a                    │
│ ---                  │
│ i64                  │
╞══════════════════════╡
│ -9223372036854775808 │
└──────────────────────┘

lt(
    other: Any,
) → Expr

Эквивалент метода для оператора «меньше» expr < other.

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

Параметры:

other: Литерал или значение выражения для сравнения.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 3.0],
...         "y": [2.0, 2.0, float("nan"), 4.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").lt(pl.col("y")).alias("x < y"),
... )
shape: (4, 3)
┌─────┬─────┬───────┐
│ x   ┆ y   ┆ x < y │
│ --- ┆ --- ┆ ---   │
│ f64 ┆ f64 ┆ bool  │
╞═════╪═════╪═══════╡
│ 1.0 ┆ 2.0 ┆ true  │
│ 2.0 ┆ 2.0 ┆ false │
│ NaN ┆ NaN ┆ false │
│ 3.0 ┆ 4.0 ┆ true  │
└─────┴─────┴───────┘

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

Сначала выполнить implode при групповой агрегации.

Устарело с версии 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        │
└─────┴─────┴───────────┘

map_elements(
    function: Callable[[Any],
    Any],
    return_dtype: PolarsDataType | DataTypeExpr | None = None,
    *,
    skip_nulls: bool = True,
    pass_name: bool = False,
    strategy: MapElementsStrategy = 'thread_local',
    returns_scalar: bool = False,
) → Expr

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

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

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

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

Для отображения элементов series рассмотрите: pl.col("col_name").sqrt().
Для отображения внутренних элементов списков рассмотрите: pl.col("col_name").list.eval(pl.element().sqrt()).
Для отображения элементов полей struct рассмотрите: pl.col("col_name").struct.field("field_name").sqrt().

Чтобы заменить исходный столбец или поле, рассмотрите .with_columns и .with_fields.

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

Параметры:

function

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

return_dtype

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

skip_nulls

Не применять функцию к значениям, содержащим null (это быстрее).

pass_name

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

returns_scalar

Устарело с версии 1.32.0: Игнорируется и будет удалено в версии 2.0.

strategy{‘thread_local’, ‘threading’}

Стратегия многопоточности.

‘thread_local’: выполнять функцию Python в одном потоке.
‘threading’: выполнять функцию Python в отдельных потоках. Используйте с осторожностью, так как это может снизить производительность. Ускорение возможно только в том случае, если объём работы для каждого элемента значителен, а функция Python освобождает GIL (например, вызывая функцию C).

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

Эта функциональность считается нестабильной. Она может измениться в любой момент без объявления таких изменений нарушающими совместимость.

Примечания

Настоятельно не рекомендуется использовать map_elements, поскольку фактически вы будете выполнять циклы Python «for», что будет очень медленно. Для максимальной производительности по возможности используйте встроенный API выражений.
Если ваша функция затратна и вы не хотите вызывать её более одного раза для одного входного значения, рассмотрите возможность применения к ней декоратора @lru_cache. Если данные подходят, это может дать значительное ускорение.
Применение оконной функции с помощью over здесь считается контекстом GroupBy, поэтому map_elements можно использовать для отображения функций на группы окон.
UDF, передаваемая в map_elements, должна быть чистой, то есть не должна изменять состояние, отличное от её аргументов, или зависеть от него. Polars может вызывать функцию с произвольными входными данными.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 1],
...         "b": ["a", "b", "c", "c"],
...     }
... )

Функция применяется к каждому элементу столбца 'a':

>>> df.with_columns(  
...     pl.col("a")
...     .map_elements(lambda x: x * 2, return_dtype=pl.self_dtype())
...     .alias("a_times_2"),
... )
shape: (4, 3)
┌─────┬─────┬───────────┐
│ a   ┆ b   ┆ a_times_2 │
│ --- ┆ --- ┆ ---       │
│ i64 ┆ str ┆ i64       │
╞═════╪═════╪═══════════╡
│ 1   ┆ a   ┆ 2         │
│ 2   ┆ b   ┆ 4         │
│ 3   ┆ c   ┆ 6         │
│ 1   ┆ c   ┆ 2         │
└─────┴─────┴───────────┘

Совет: лучше реализовать это с помощью выражения:

>>> df.with_columns(
...     (pl.col("a") * 2).alias("a_times_2"),
... )

>>> (
...     df.lazy()
...     .group_by("b")
...     .agg(
...         pl.col("a")
...         .implode()
...         .map_elements(lambda x: x.sum(), return_dtype=pl.Int64)
...     )
...     .collect()
... )  
shape: (3, 2)
┌─────┬─────┐
│ b   ┆ a   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ a   ┆ 1   │
│ b   ┆ 2   │
│ c   ┆ 4   │
└─────┴─────┘

Совет: и здесь лучше реализовать это с помощью выражения:

>>> (
...     df.lazy()
...     .group_by("b", maintain_order=True)
...     .agg(pl.col("a").sum())
...     .collect()
... )

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

>>> df = pl.DataFrame(
...     {
...         "key": ["x", "x", "y", "x", "y", "z"],
...         "val": [1, 1, 1, 1, 1, 1],
...     }
... )
>>> df.with_columns(
...     scaled=pl.col("val")
...     .implode()
...     .map_elements(lambda s: s * len(s), return_dtype=pl.List(pl.Int64))
...     .explode(empty_as_null=False)
...     .over("key"),
... ).sort("key")
shape: (6, 3)
┌─────┬─────┬────────┐
│ key ┆ val ┆ scaled │
│ --- ┆ --- ┆ ---    │
│ str ┆ i64 ┆ i64    │
╞═════╪═════╪════════╡
│ x   ┆ 1   ┆ 3      │
│ x   ┆ 1   ┆ 3      │
│ x   ┆ 1   ┆ 3      │
│ y   ┆ 1   ┆ 2      │
│ y   ┆ 1   ┆ 2      │
│ z   ┆ 1   ┆ 1      │
└─────┴─────┴────────┘

Обратите внимание, что эту функцию также лучше реализовать встроенными средствами:

>>> df.with_columns(
...     scaled=(pl.col("val") * pl.col("val").count()).over("key"),
... ).sort("key")

max() → Expr

Получить максимальное значение.

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

Примеры

>>> df = pl.DataFrame({"a": [-1.0, float("nan"), 1.0]})
>>> df.select(pl.col("a").max())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
└─────┘

max_by(
    by: IntoExpr,
) → Expr

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

Если выражение by содержит несколько значений, равных максимуму, выбор значения не определён.

движок:В памятиПотоковый

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

Параметры:

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

Примеры

>>> df = pl.DataFrame({"a": [-1.0, float("nan"), 1.0], "b": ["x", "y", "z"]})
>>> df.select(pl.col("b").max_by("a"))
shape: (1, 1)
┌─────┐
│ b   │
│ --- │
│ str │
╞═════╡
│ z   │
└─────┘

mean() → Expr

Получить среднее значение.

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

Примеры

>>> df = pl.DataFrame({"a": [-1, 0, 1]})
>>> df.select(pl.col("a").mean())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
└─────┘

median() → Expr

Получить медианное значение с помощью линейной интерполяции.

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

Примеры

>>> df = pl.DataFrame({"a": [-1, 0, 1]})
>>> df.select(pl.col("a").median())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
└─────┘

min() → Expr

Получить минимальное значение.

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

Примеры

>>> df = pl.DataFrame({"a": [-1.0, float("nan"), 1.0]})
>>> df.select(pl.col("a").min())
shape: (1, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ -1.0 │
└──────┘

min_by(
    by: IntoExpr,
) → Expr

Получить минимальное значение, упорядоченное по другому выражению.

Если выражение by содержит несколько значений, равных минимуму, выбор значения не определён.

движок:В памятиПотоковый

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

Параметры:

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

Примеры

>>> df = pl.DataFrame({"a": [-1.0, float("nan"), 1.0], "b": ["x", "y", "z"]})
>>> df.select(pl.col("b").min_by("a"))
shape: (1, 1)
┌─────┐
│ b   │
│ --- │
│ str │
╞═════╡
│ x   │
└─────┘

mod(
    other: Any,
) → Expr

Эквивалент метода для оператора остатка от деления expr % other.

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

Параметры:

other: Числовой литерал или значение выражения.

Примеры

>>> df = pl.DataFrame({"x": [0, 1, 2, 3, 4]})
>>> df.with_columns(pl.col("x").mod(2).alias("x%2"))
shape: (5, 2)
┌─────┬─────┐
│ x   ┆ x%2 │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 0   ┆ 0   │
│ 1   ┆ 1   │
│ 2   ┆ 0   │
│ 3   ┆ 1   │
│ 4   ┆ 0   │
└─────┴─────┘

mode(
    *,
    maintain_order: bool = False,
) → Expr

Вычислить наиболее часто встречающееся значение (значения).

Может вернуть несколько значений.

движок:В памятиПотоковый

Параметры:

maintain_order: Сохранять порядок данных. Для этого требуется больше вычислений.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 1, 2, 3],
...         "b": [1, 1, 2, 2],
...     }
... )
>>> df.select(pl.all().mode().first())  
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 1   │
└─────┴─────┘

mul(
    other: Any,
) → Expr

Эквивалент метода для оператора умножения expr * other.

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

Параметры:

other: Числовой литерал или значение выражения.

Примеры

>>> df = pl.DataFrame({"x": [1, 2, 4, 8, 16]})
>>> df.with_columns(
...     pl.col("x").mul(2).alias("x*2"),
...     pl.col("x").mul(pl.col("x").log(2)).alias("x * xlog2"),
... )
shape: (5, 3)
┌─────┬─────┬───────────┐
│ x   ┆ x*2 ┆ x * xlog2 │
│ --- ┆ --- ┆ ---       │
│ i64 ┆ i64 ┆ f64       │
╞═════╪═════╪═══════════╡
│ 1   ┆ 2   ┆ 0.0       │
│ 2   ┆ 4   ┆ 2.0       │
│ 4   ┆ 8   ┆ 8.0       │
│ 8   ┆ 16  ┆ 24.0      │
│ 16  ┆ 32  ┆ 64.0      │
└─────┴─────┴───────────┘

n_unique() → Expr

Подсчитать уникальные значения.

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

Примечания

Для этой операции null считается уникальным значением.

Примеры

>>> df = pl.DataFrame({"x": [1, 1, 2, 2, 3], "y": [1, 1, 1, None, None]})
>>> df.select(
...     x_unique=pl.col("x").n_unique(),
...     y_unique=pl.col("y").n_unique(),
... )
shape: (1, 2)
┌──────────┬──────────┐
│ x_unique ┆ y_unique │
│ ---      ┆ ---      │
│ u32      ┆ u32      │
╞══════════╪══════════╡
│ 3        ┆ 2        │
└──────────┴──────────┘

nan_max() → Expr

Получить максимальное значение, распространяя/передавая далее встреченные значения NaN.

Это отличается от nanmax в numpy: по умолчанию numpy распространяет значения NaN, тогда как polars по умолчанию игнорирует их.

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

Примеры

>>> df = pl.DataFrame({"a": [0.0, float("nan")]})
>>> df.select(pl.col("a").nan_max())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ NaN │
└─────┘

nan_min() → Expr

Получить минимальное значение, распространяя/передавая далее встреченные значения NaN.

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

Примеры

>>> df = pl.DataFrame({"a": [0.0, float("nan")]})
>>> df.select(pl.col("a").nan_min())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ NaN │
└─────┘

ne(
    other: Any,
) → Expr

Эквивалент метода для оператора неравенства expr != other.

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

Параметры:

other: Литерал или значение выражения для сравнения.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 4.0],
...         "y": [2.0, 2.0, float("nan"), 4.0],
...     }
... )
>>> df.with_columns(
...     pl.col("x").ne(pl.col("y")).alias("x != y"),
... )
shape: (4, 3)
┌─────┬─────┬────────┐
│ x   ┆ y   ┆ x != y │
│ --- ┆ --- ┆ ---    │
│ f64 ┆ f64 ┆ bool   │
╞═════╪═════╪════════╡
│ 1.0 ┆ 2.0 ┆ true   │
│ 2.0 ┆ 2.0 ┆ false  │
│ NaN ┆ NaN ┆ false  │
│ 4.0 ┆ 4.0 ┆ false  │
└─────┴─────┴────────┘

ne_missing(
    other: Any,
) → Expr

Эквивалент метода для оператора равенства expr != other, где None == None.

Отличается от стандартного ne, при котором значения null распространяются.

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

Параметры:

other: Литерал или значение выражения для сравнения.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [1.0, 2.0, float("nan"), 4.0, None, None],
...         "y": [2.0, 2.0, float("nan"), 4.0, 5.0, None],
...     }
... )
>>> df.with_columns(
...     pl.col("x").ne(pl.col("y")).alias("x ne y"),
...     pl.col("x").ne_missing(pl.col("y")).alias("x ne_missing y"),
... )
shape: (6, 4)
┌──────┬──────┬────────┬────────────────┐
│ x    ┆ y    ┆ x ne y ┆ x ne_missing y │
│ ---  ┆ ---  ┆ ---    ┆ ---            │
│ f64  ┆ f64  ┆ bool   ┆ bool           │
╞══════╪══════╪════════╪════════════════╡
│ 1.0  ┆ 2.0  ┆ true   ┆ true           │
│ 2.0  ┆ 2.0  ┆ false  ┆ false          │
│ NaN  ┆ NaN  ┆ false  ┆ false          │
│ 4.0  ┆ 4.0  ┆ false  ┆ false          │
│ null ┆ 5.0  ┆ null   ┆ true           │
│ null ┆ null ┆ null   ┆ false          │
└──────┴──────┴────────┴────────────────┘

neg() → Expr

Эквивалент метода для унарного оператора минус -expr.

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

Примеры

>>> df = pl.DataFrame({"a": [-1, 0, 2, None]})
>>> df.with_columns(pl.col("a").neg())
shape: (4, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ 1    │
│ 0    │
│ -2   │
│ null │
└──────┘

not_() → Expr

Эквивалент метода для побитового оператора «not» ~expr.

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

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "label": ["aa", "bb", "cc", "dd", "ee"],
...         "valid": [True, False, None, False, True],
...         "int_code": [1, 0, 2, None, -1],
...     }
... )

Применение «not» к булеву выражению (инвертирует значение) и целочисленному выражению (выполняет побитовую операцию):

>>> df.with_columns(
...     not_valid=pl.col("valid").not_(),
...     not_int_code=pl.col("int_code").not_(),
... )
shape: (5, 5)
┌───────┬───────┬──────────┬───────────┬──────────────┐
│ label ┆ valid ┆ int_code ┆ not_valid ┆ not_int_code │
│ ---   ┆ ---   ┆ ---      ┆ ---       ┆ ---          │
│ str   ┆ bool  ┆ i64      ┆ bool      ┆ i64          │
╞═══════╪═══════╪══════════╪═══════════╪══════════════╡
│ aa    ┆ true  ┆ 1        ┆ false     ┆ -2           │
│ bb    ┆ false ┆ 0        ┆ true      ┆ -1           │
│ cc    ┆ null  ┆ 2        ┆ null      ┆ -3           │
│ dd    ┆ false ┆ null     ┆ true      ┆ null         │
│ ee    ┆ true  ┆ -1       ┆ false     ┆ 0            │
└───────┴───────┴──────────┴───────────┴──────────────┘

null_count() → Expr

Подсчитать значения null.

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [None, 1, None],
...         "b": [10, None, 300],
...         "c": [350, 650, 850],
...     }
... )
>>> df.select(pl.all().null_count())
shape: (1, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ u32 ┆ u32 ┆ u32 │
╞═════╪═════╪═════╡
│ 2   ┆ 1   ┆ 0   │
└─────┴─────┴─────┘

or_(
    *others: Any,
) → Expr

Эквивалент метода для побитового оператора «или» expr | other | ....

Это позволяет объединять логические булевы выражения, но выполняет побитовые операции над целыми числами.

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

Параметры:

*others: Одно или несколько целочисленных или булевых выражений для вычисления/объединения.

Примеры

>>> df = pl.DataFrame(
...     data={
...         "x": [5, 6, 7, 4, 8],
...         "y": [1.5, 2.5, 1.0, 4.0, -5.75],
...         "z": [-9, 2, -1, 4, 8],
...     }
... )

Объединение логических условий «или»:

>>> df.select(
...     (pl.col("x") == pl.col("y"))
...     .or_(
...         pl.col("x") == pl.col("y"),
...         pl.col("y") == pl.col("z"),
...         pl.col("y").cast(int) == pl.col("z"),
...     )
...     .alias("any")
... )
shape: (5, 1)
┌───────┐
│ any   │
│ ---   │
│ bool  │
╞═══════╡
│ false │
│ true  │
│ false │
│ true  │
│ false │
└───────┘

Побитовая операция «или» над целочисленными столбцами:

>>> df.select("x", "z", x_or_z=pl.col("x").or_(pl.col("z")))
shape: (5, 3)
┌─────┬─────┬────────┐
│ x   ┆ z   ┆ x_or_z │
│ --- ┆ --- ┆ ---    │
│ i64 ┆ i64 ┆ i64    │
╞═════╪═════╪════════╡
│ 5   ┆ -9  ┆ -9     │
│ 6   ┆ 2   ┆ 6      │
│ 7   ┆ -1  ┆ -1     │
│ 4   ┆ 4   ┆ 4      │
│ 8   ┆ 8   ┆ 8      │
└─────┴─────┴────────┘

over(
    partition_by: IntoExpr | Iterable[IntoExpr] | None = None,
    *more_exprs: IntoExpr,
    order_by: IntoExpr | Iterable[IntoExpr] | None = None,
    descending: bool = False,
    nulls_last: bool = False,
    mapping_strategy: WindowMappingStrategy = 'group_to_rows',
) → Expr

Вычисление выражений для заданных групп.

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

Результат аналогичен работе оконных функций в PostgreSQL.

движок:В памяти

Параметры:

partition_by

Столбец или столбцы для группировки. Принимает выражение. Строки интерпретируются как имена столбцов.

*more_exprs

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

order_by

Сортировка строк внутри каждой группы-раздела перед вычислением выражения. Полезно для операций, чувствительных к порядку, таких как cum_sum() или diff().

descending

Если задан параметр ‘order_by’, указывает, следует ли сортировать по возрастанию или убыванию.

nulls_last

Если задан параметр ‘order_by’, указывает, следует ли помещать значения null в конец.

mapping_strategy: {‘group_to_rows’, ‘join’, ‘explode’}

group_to_rows

Если агрегация возвращает несколько значений для каждой группы, сопоставляет их позициям строк в DataFrame. Это возможно только в том случае, если каждая группа содержит одинаковое число элементов до и после агрегации. Если агрегация возвращает одно скалярное значение для каждой группы, это значение будет сопоставлено каждой строке.
join

Если агрегация может возвращать несколько значений для каждой группы, присоединяет эти значения к каждой позиции строки в виде ‘List<group_dtype>’. Предупреждение: это может потребовать значительного объёма памяти. Если агрегация всегда возвращает одно скалярное значение для каждой группы, присоединяет это значение к каждой позиции строки в виде ‘<group_dtype>’.
explode

Если агрегация может возвращать несколько значений для каждой группы, сопоставляет каждое значение новой строке, аналогично результатам group_by + agg + explode. Если агрегация всегда возвращает одно скалярное значение для каждой группы, сопоставляет его одной позиции строки. Если группы не входят в оконную операцию, их необходимо отсортировать, иначе результат не будет иметь смысла. Эта операция изменяет число строк.

Примеры

Передайте имя столбца, чтобы вычислить выражение для этого столбца.

>>> df = pl.DataFrame(
...     {
...         "a": ["a", "a", "b", "b", "b"],
...         "b": [1, 2, 3, 5, 3],
...         "c": [5, 4, 3, 2, 1],
...     }
... )
>>> df.with_columns(c_max=pl.col("c").max().over("a"))
shape: (5, 4)
┌─────┬─────┬─────┬───────┐
│ a   ┆ b   ┆ c   ┆ c_max │
│ --- ┆ --- ┆ --- ┆ ---   │
│ str ┆ i64 ┆ i64 ┆ i64   │
╞═════╪═════╪═════╪═══════╡
│ a   ┆ 1   ┆ 5   ┆ 5     │
│ a   ┆ 2   ┆ 4   ┆ 5     │
│ b   ┆ 3   ┆ 3   ┆ 3     │
│ b   ┆ 5   ┆ 2   ┆ 3     │
│ b   ┆ 3   ┆ 1   ┆ 3     │
└─────┴─────┴─────┴───────┘

Также поддерживается передача выражения.

>>> df.with_columns(c_max=pl.col("c").max().over(pl.col("b") // 2))
shape: (5, 4)
┌─────┬─────┬─────┬───────┐
│ a   ┆ b   ┆ c   ┆ c_max │
│ --- ┆ --- ┆ --- ┆ ---   │
│ str ┆ i64 ┆ i64 ┆ i64   │
╞═════╪═════╪═════╪═══════╡
│ a   ┆ 1   ┆ 5   ┆ 5     │
│ a   ┆ 2   ┆ 4   ┆ 4     │
│ b   ┆ 3   ┆ 3   ┆ 4     │
│ b   ┆ 5   ┆ 2   ┆ 2     │
│ b   ┆ 3   ┆ 1   ┆ 4     │
└─────┴─────┴─────┴───────┘

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

>>> df.with_columns(c_min=pl.col("c").min().over("a", pl.col("b") % 2))
shape: (5, 4)
┌─────┬─────┬─────┬───────┐
│ a   ┆ b   ┆ c   ┆ c_min │
│ --- ┆ --- ┆ --- ┆ ---   │
│ str ┆ i64 ┆ i64 ┆ i64   │
╞═════╪═════╪═════╪═══════╡
│ a   ┆ 1   ┆ 5   ┆ 5     │
│ a   ┆ 2   ┆ 4   ┆ 4     │
│ b   ┆ 3   ┆ 3   ┆ 1     │
│ b   ┆ 5   ┆ 2   ┆ 1     │
│ b   ┆ 3   ┆ 1   ┆ 1     │
└─────┴─────┴─────┴───────┘

Стратегия сопоставления join объединяет значения по группам.

>>> df.with_columns(
...     c_pairs=pl.col("c").head(2).over("a", mapping_strategy="join")
... )
shape: (5, 4)
┌─────┬─────┬─────┬───────────┐
│ a   ┆ b   ┆ c   ┆ c_pairs   │
│ --- ┆ --- ┆ --- ┆ ---       │
│ str ┆ i64 ┆ i64 ┆ list[i64] │
╞═════╪═════╪═════╪═══════════╡
│ a   ┆ 1   ┆ 5   ┆ [5, 4]    │
│ a   ┆ 2   ┆ 4   ┆ [5, 4]    │
│ b   ┆ 3   ┆ 3   ┆ [3, 2]    │
│ b   ┆ 5   ┆ 2   ┆ [3, 2]    │
│ b   ┆ 3   ┆ 1   ┆ [3, 2]    │
└─────┴─────┴─────┴───────────┘

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

>>> df.select(
...     c_first_2=pl.col("c").head(2).over("a", mapping_strategy="explode")
... )
shape: (4, 1)
┌───────────┐
│ c_first_2 │
│ ---       │
│ i64       │
╞═══════════╡
│ 5         │
│ 4         │
│ 3         │
│ 2         │
└───────────┘

С помощью over можно также использовать выражения, которые не применяются поэлементно. По умолчанию они вычисляются с учётом порядка строк, но его можно изменить с помощью order_by.

>>> from datetime import date
>>> df = pl.DataFrame(
...     {
...         "store_id": ["a", "a", "b", "b"],
...         "date": [
...             date(2024, 9, 18),
...             date(2024, 9, 17),
...             date(2024, 9, 18),
...             date(2024, 9, 16),
...         ],
...         "sales": [7, 9, 8, 10],
...     }
... )
>>> df.with_columns(
...     cumulative_sales=pl.col("sales")
...     .cum_sum()
...     .over("store_id", order_by="date")
... )
shape: (4, 4)
┌──────────┬────────────┬───────┬──────────────────┐
│ store_id ┆ date       ┆ sales ┆ cumulative_sales │
│ ---      ┆ ---        ┆ ---   ┆ ---              │
│ str      ┆ date       ┆ i64   ┆ i64              │
╞══════════╪════════════╪═══════╪══════════════════╡
│ a        ┆ 2024-09-18 ┆ 7     ┆ 16               │
│ a        ┆ 2024-09-17 ┆ 9     ┆ 9                │
│ b        ┆ 2024-09-18 ┆ 8     ┆ 18               │
│ b        ┆ 2024-09-16 ┆ 10    ┆ 10               │
└──────────┴────────────┴───────┴──────────────────┘

Если сохранение порядка групп не требуется, более производительным вариантом будет mapping_strategy='explode'. Однако используйте его только в операторе select, а не в операторе with_columns.

>>> window = {
...     "partition_by": "store_id",
...     "order_by": "date",
...     "mapping_strategy": "explode",
... }
>>> df.select(
...     pl.all().over(**window),
...     cumulative_sales=pl.col("sales").cum_sum().over(**window),
... )
shape: (4, 4)
┌──────────┬────────────┬───────┬──────────────────┐
│ store_id ┆ date       ┆ sales ┆ cumulative_sales │
│ ---      ┆ ---        ┆ ---   ┆ ---              │
│ str      ┆ date       ┆ i64   ┆ i64              │
╞══════════╪════════════╪═══════╪══════════════════╡
│ a        ┆ 2024-09-17 ┆ 9     ┆ 9                │
│ a        ┆ 2024-09-18 ┆ 7     ┆ 16               │
│ b        ┆ 2024-09-16 ┆ 10    ┆ 10               │
│ b        ┆ 2024-09-18 ┆ 8     ┆ 18               │
└──────────┴────────────┴───────┴──────────────────┘

pct_change(
    n: int | IntoExprColumn = 1,
) → Expr

Вычисляет процентное изменение между значениями.

Процентное изменение (в виде дроби) между текущим элементом и ближайшим предшествующим ненулевым элементом, находящимся как минимум на n период(а) раньше текущего элемента.

По умолчанию вычисляет изменение относительно предыдущей строки.

движок:В памяти

Параметры:

n: Число периодов для сдвига при вычислении процентного изменения.

Примечания

Значения null сохраняются. Если вы переходите с pandas, поведение соответствует fill_method=None.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [10, 11, 12, None, 12],
...     }
... )
>>> df.with_columns(pl.col("a").pct_change().alias("pct_change"))
shape: (5, 2)
┌──────┬────────────┐
│ a    ┆ pct_change │
│ ---  ┆ ---        │
│ i64  ┆ f64        │
╞══════╪════════════╡
│ 10   ┆ null       │
│ 11   ┆ 0.1        │
│ 12   ┆ 0.090909   │
│ null ┆ null       │
│ 12   ┆ null       │
└──────┴────────────┘

peak_max() → Expr

Возвращает булеву маску локальных максимумов.

движок:В памяти

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3, 4, 5]})
>>> df.select(pl.col("a").peak_max())
shape: (5, 1)
┌───────┐
│ a     │
│ ---   │
│ bool  │
╞═══════╡
│ false │
│ false │
│ false │
│ false │
│ true  │
└───────┘

peak_min() → Expr

Возвращает булеву маску локальных минимумов.

движок:В памяти

Примеры

>>> df = pl.DataFrame({"a": [4, 1, 3, 2, 5]})
>>> df.select(pl.col("a").peak_min())
shape: (5, 1)
┌───────┐
│ a     │
│ ---   │
│ bool  │
╞═══════╡
│ false │
│ true  │
│ false │
│ true  │
│ false │
└───────┘

pipe(
    function: Callable[Concatenate[Expr,
    P],
    T],
    *args: P.args,
    **kwargs: P.kwargs,
) → T

Предоставляет структурированный способ применения последовательности пользовательских функций (UDF).

Параметры:

function: Вызываемый объект; получит выражение первым параметром, за которым следуют переданные аргументы args/kwargs.
*args: Аргументы, передаваемые в UDF.
**kwargs: Именованные аргументы, передаваемые в UDF.

Примеры

>>> def extract_number(expr: pl.Expr) -> pl.Expr:
...     """Extract the digits from a string."""
...     return expr.str.extract(r"\d+", 0).cast(pl.Int64)
>>>
>>> def scale_negative_even(expr: pl.Expr, *, n: int = 1) -> pl.Expr:
...     """Set even numbers negative, and scale by a user-supplied value."""
...     expr = pl.when(expr % 2 == 0).then(-expr).otherwise(expr)
...     return expr * n
>>>
>>> df = pl.DataFrame({"val": ["a: 1", "b: 2", "c: 3", "d: 4"]})
>>> df.with_columns(
...     udfs=(
...         pl.col("val").pipe(extract_number).pipe(scale_negative_even, n=5)
...     ),
... )
shape: (4, 2)
┌──────┬──────┐
│ val  ┆ udfs │
│ ---  ┆ ---  │
│ str  ┆ i64  │
╞══════╪══════╡
│ a: 1 ┆ 5    │
│ b: 2 ┆ -10  │
│ c: 3 ┆ 15   │
│ d: 4 ┆ -20  │
└──────┴──────┘

pow(
    exponent: IntoExprColumn | int | float,
) → Expr

Эквивалент метода для оператора возведения в степень expr ** exponent.

Если показатель степени имеет тип float, результат будет иметь тип данных показателя. В противном случае он будет иметь тип данных основания.

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

Параметры:

exponent: Числовой литерал или выражение, задающее показатель степени.

Примеры

>>> df = pl.DataFrame({"x": [1, 2, 4, 8]})
>>> df.with_columns(
...     pl.col("x").pow(3).alias("cube"),
...     pl.col("x").pow(pl.col("x").log(2)).alias("x ** xlog2"),
... )
shape: (4, 3)
┌─────┬──────┬────────────┐
│ x   ┆ cube ┆ x ** xlog2 │
│ --- ┆ ---  ┆ ---        │
│ i64 ┆ i64  ┆ f64        │
╞═════╪══════╪════════════╡
│ 1   ┆ 1    ┆ 1.0        │
│ 2   ┆ 8    ┆ 2.0        │
│ 4   ┆ 64   ┆ 16.0       │
│ 8   ┆ 512  ┆ 512.0      │
└─────┴──────┴────────────┘

Возведение целого числа в положительную целую степень возвращает целое число. Чтобы возвести его в отрицательную целую степень, сначала преобразуйте основание или показатель степени в float:

>>> df.with_columns(
...     x_squared=pl.col("x").pow(2),
...     x_inverse=pl.col("x").pow(-1.0),
... )
shape: (4, 3)
┌─────┬───────────┬───────────┐
│ x   ┆ x_squared ┆ x_inverse │
│ --- ┆ ---       ┆ ---       │
│ i64 ┆ i64       ┆ f64       │
╞═════╪═══════════╪═══════════╡
│ 1   ┆ 1         ┆ 1.0       │
│ 2   ┆ 4         ┆ 0.5       │
│ 4   ┆ 16        ┆ 0.25      │
│ 8   ┆ 64        ┆ 0.125     │
└─────┴───────────┴───────────┘

product() → Expr

Вычисляет произведение выражения.

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

Примечания

Если нет ненулевых значений, результатом будет 1. Если требуется, чтобы для пустого произведения возвращалось None, используйте pl.when(expr.count()>0).then(expr.product()) вместо expr.product().

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").product())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 6   │
└─────┘

qcut(
    quantiles: Sequence[float] | int,
    *,
    labels: Sequence[str_] | None = None,
    left_closed: bool = False,
    allow_duplicates: bool = False,
    include_breaks: bool = False,
) → Expr

Разбивает непрерывные значения на дискретные категории на основе квантилей.

движок:В памяти

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без объявления таких изменений обратно несовместимыми.

Параметры:

quantiles: Список вероятностей квантилей от 0 до 1 или положительное целое число, определяющее количество интервалов с равномерными вероятностями.
labels: Названия категорий. Число меток должно совпадать с числом категорий.
left_closed: Задаёт интервалы с включённой левой границей вместо правой.
allow_duplicates: Если задано значение True, повторяющиеся значения в результирующих квантилях удаляются, а не вызывают DuplicateError. Это может произойти даже при уникальных вероятностях, в зависимости от данных.
include_breaks: Добавляет столбец с правой границей интервала, в который попадает каждое наблюдение. В результате тип данных будет изменён с Categorical на Struct.

Возвращает:

Expr: Выражение типа данных Categorical, если для include_breaks задано значение False (по умолчанию); в противном случае — выражение типа данных Struct.

См. также

cut

Примеры

Разделите столбец на три категории в соответствии с заранее заданными вероятностями квантилей.

>>> df = pl.DataFrame({"foo": [-2, -1, 0, 1, 2]})
>>> df.with_columns(
...     pl.col("foo").qcut([0.25, 0.75], labels=["a", "b", "c"]).alias("qcut")
... )
shape: (5, 2)
┌─────┬──────┐
│ foo ┆ qcut │
│ --- ┆ ---  │
│ i64 ┆ cat  │
╞═════╪══════╡
│ -2  ┆ a    │
│ -1  ┆ a    │
│ 0   ┆ b    │
│ 1   ┆ b    │
│ 2   ┆ c    │
└─────┴──────┘

Разделите столбец на две категории, используя равномерные вероятности квантилей.

>>> df.with_columns(
...     pl.col("foo")
...     .qcut(2, labels=["low", "high"], left_closed=True)
...     .alias("qcut")
... )
shape: (5, 2)
┌─────┬──────┐
│ foo ┆ qcut │
│ --- ┆ ---  │
│ i64 ┆ cat  │
╞═════╪══════╡
│ -2  ┆ low  │
│ -1  ┆ low  │
│ 0   ┆ high │
│ 1   ┆ high │
│ 2   ┆ high │
└─────┴──────┘

Добавьте категорию и границу интервала.

>>> df.with_columns(
...     pl.col("foo").qcut([0.25, 0.75], include_breaks=True).alias("qcut")
... ).unnest("qcut")
shape: (5, 3)
┌─────┬────────────┬────────────┐
│ foo ┆ breakpoint ┆ category   │
│ --- ┆ ---        ┆ ---        │
│ i64 ┆ f64        ┆ cat        │
╞═════╪════════════╪════════════╡
│ -2  ┆ -1.0       ┆ (-inf, -1] │
│ -1  ┆ -1.0       ┆ (-inf, -1] │
│ 0   ┆ 1.0        ┆ (-1, 1]    │
│ 1   ┆ 1.0        ┆ (-1, 1]    │
│ 2   ┆ inf        ┆ (1, inf]   │
└─────┴────────────┴────────────┘

quantile(
    quantile: float | list_[float] | Expr,
    interpolation: QuantileMethod = 'nearest',
) → Expr

Получает значение квантиля.

движок:В памяти

Параметры:

quantile

Квантиль или квантили от 0.0 до 1.0. Может быть одним числом с плавающей точкой или списком таких чисел.

Если передано одно число с плавающей точкой, для каждой строки возвращается одно значение f64.
Если передан список чисел с плавающей точкой, для каждой строки возвращается список значений f64 (по одному значению на квантиль).

interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’, ‘equiprobable’}

Метод интерполяции.

Примеры

>>> df = pl.DataFrame({"a": [0, 1, 2, 3, 4, 5]})
>>> df.select(pl.col("a").quantile(0.3))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 2.0 │
└─────┘
>>> df.select(pl.col("a").quantile(0.3, interpolation="higher"))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 2.0 │
└─────┘
>>> df.select(pl.col("a").quantile(0.3, interpolation="lower"))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
└─────┘
>>> df.select(pl.col("a").quantile(0.3, interpolation="midpoint"))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.5 │
└─────┘
>>> df.select(pl.col("a").quantile(0.3, interpolation="linear"))
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.5 │
└─────┘
>>> df.select(pl.col("a").quantile([0.25, 0.75], interpolation="linear"))
shape: (1, 1)
┌──────────────┐
│ a            │
│ ---          │
│ list[f64]    │
╞══════════════╡
│ [1.25, 3.75] │
└──────────────┘

radians() → Expr

Преобразует градусы в радианы.

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

Возвращает:

Expr: Выражение типа данных Float64.

Примеры

>>> df = pl.DataFrame({"a": [-720, -540, -360, -180, 0, 180, 360, 540, 720]})
>>> df.select(pl.col("a").radians())
shape: (9, 1)
┌────────────┐
│ a          │
│ ---        │
│ f64        │
╞════════════╡
│ -12.566371 │
│ -9.424778  │
│ -6.283185  │
│ -3.141593  │
│ 0.0        │
│ 3.141593   │
│ 6.283185   │
│ 9.424778   │
│ 12.566371  │
└────────────┘

rank(
    method: RankMethod = 'average',
    *,
    descending: bool = False,
    seed: int | None = None,
) → Expr

Присваивает данным ранги с корректной обработкой совпадающих значений.

движок:В памяти

Параметры:

method{‘average’, ‘min’, ‘max’, ‘dense’, ‘ordinal’, ‘random’}

Метод присвоения рангов элементам с одинаковыми значениями. Доступны следующие методы (по умолчанию используется ‘average’):

‘average’ : Каждому значению присваивается среднее значение рангов, которые были бы присвоены всем совпадающим значениям.
‘min’ : Каждому значению присваивается наименьший из рангов, которые были бы присвоены всем совпадающим значениям. (Также называется ранжированием «соревнования».)
‘max’ : Каждому значению присваивается наибольший из рангов, которые были бы присвоены всем совпадающим значениям.
‘dense’ : Аналогично ‘min’, но следующему по величине элементу присваивается ранг, следующий непосредственно за рангами совпадающих элементов.
‘ordinal’ : Всем значениям присваиваются разные ранги в соответствии с порядком их появления в Series.
‘random’ : Аналогично ‘ordinal’, но ранг совпадающих значений не зависит от порядка их появления в Series.

descending

Ранжировать по убыванию.

seed

Если задано значение method="random", использовать его как начальное значение.

Примечания

Если вы переходите с SQL, вы можете ожидать, что значения null будут ранжироваться последними. Однако Polars присваивает ранги только ненулевым значениям, а значения null сохраняет без изменений.

Примеры

Метод ‘average’:

>>> df = pl.DataFrame({"a": [3, 6, 1, 1, 6]})
>>> df.select(pl.col("a").rank())
shape: (5, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 3.0 │
│ 4.5 │
│ 1.5 │
│ 1.5 │
│ 4.5 │
└─────┘

Метод ‘ordinal’:

>>> df = pl.DataFrame({"a": [3, 6, 1, 1, 6]})
>>> df.select(pl.col("a").rank("ordinal"))
shape: (5, 1)
┌─────┐
│ a   │
│ --- │
│ u32 │
╞═════╡
│ 3   │
│ 4   │
│ 1   │
│ 2   │
│ 5   │
└─────┘

Используйте ‘rank’ с ‘over’, чтобы ранжировать значения внутри групп:

>>> df = pl.DataFrame({"a": [1, 1, 2, 2, 2], "b": [6, 7, 5, 14, 11]})
>>> df.with_columns(pl.col("b").rank().over("a").alias("rank"))
shape: (5, 3)
┌─────┬─────┬──────┐
│ a   ┆ b   ┆ rank │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ i64 ┆ f64  │
╞═════╪═════╪══════╡
│ 1   ┆ 6   ┆ 1.0  │
│ 1   ┆ 7   ┆ 2.0  │
│ 2   ┆ 5   ┆ 1.0  │
│ 2   ┆ 14  ┆ 3.0  │
│ 2   ┆ 11  ┆ 2.0  │
└─────┴─────┴──────┘

Разделите на длину или число ненулевых значений, чтобы вычислить процентильный ранг.

>>> df = pl.DataFrame({"a": [6, 7, None, 14, 11]})
>>> df.with_columns(
...     pct=pl.col("a").rank() / pl.len(),
...     pct_valid=pl.col("a").rank() / pl.count("a"),
... )
shape: (5, 3)
┌──────┬──────┬───────────┐
│ a    ┆ pct  ┆ pct_valid │
│ ---  ┆ ---  ┆ ---       │
│ i64  ┆ f64  ┆ f64       │
╞══════╪══════╪═══════════╡
│ 6    ┆ 0.2  ┆ 0.25      │
│ 7    ┆ 0.4  ┆ 0.5       │
│ null ┆ null ┆ null      │
│ 14   ┆ 0.8  ┆ 1.0       │
│ 11   ┆ 0.6  ┆ 0.75      │
└──────┴──────┴───────────┘

rechunk() → Expr

Создаёт один блок памяти для этой Series.

Примеры

>>> df = pl.DataFrame({"a": [1, 1, 2]})

Создайте Series с тремя значениями null, добавьте столбец a, а затем выполните перекомпоновку блоков.

>>> df.select(pl.repeat(None, 3).append(pl.col("a")).rechunk())
shape: (6, 1)
┌────────┐
│ repeat │
│ ---    │
│ i64    │
╞════════╡
│ null   │
│ null   │
│ null   │
│ 1      │
│ 1      │
│ 2      │
└────────┘

register_plugin(
    *,
    lib: str_,
    symbol: str_,
    args: list_[IntoExpr] | None = None,
    kwargs: dict[Any,
    Any] | None = None,
    is_elementwise: bool = False,
    input_wildcard_expansion: bool = False,
    returns_scalar: bool = False,
    cast_to_supertypes: bool = False,
    pass_name_to_apply: bool = False,
    changes_length: bool = False,
) → Expr

Регистрирует функцию плагина.

Устарело с версии 0.20.16: Вместо этого используйте polars.plugins.register_plugin_function().

Дополнительные сведения о плагинах см. в руководстве пользователя.

Параметры:

lib: Библиотека для загрузки.
symbol: Функция для загрузки.
args: Аргументы (кроме self), передаваемые этой функции. Они должны иметь тип Expression.
kwargs: Аргументы, не являющиеся выражениями. Они должны поддерживать сериализацию в JSON.
is_elementwise: Если функция работает только со скалярами, это позволит использовать быстрые пути выполнения.
input_wildcard_expansion: Разворачивать выражения в качестве входных данных этой функции.
returns_scalar: Автоматически раскрывать результат длины 1, если функция выполнялась как финальная агрегация. Это относится к таким агрегациям, как sum, min, covariance и т. д.
cast_to_supertypes: Преобразовывать входные типы данных к их супертипу.
pass_name_to_apply: Если задано, Series, переданный функции в операции group_by, гарантирует установку имени. Это приводит к дополнительному выделению памяти в куче для каждой группы.
changes_length: Например, unique или slice

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

Этот метод устарел. Вместо него используйте новую функцию polars.plugins.register_plugin_function.

Это крайне небезопасно, поскольку метод вызывает функцию C, загруженную с помощью lib::symbol.

Параметры, которые вы задаёте, определяют способ обработки функции в Polars. Убедитесь, что они указаны правильно!

reinterpret(
    *,
    signed: bool | None = None,
    dtype: PolarsDataType | None = None,
) → Expr

Интерпретирует базовые биты как целое число со знаком или без знака либо как число с плавающей точкой.

Эта операция допустима только для числовых типов одинакового размера. Для чисел с меньшим количеством битов можно безопасно использовать операцию преобразования типа.

Можно указать signed или dtype. В противном случае по умолчанию используется signed=True.

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

Параметры:

signed: Если True, интерпретировать как целое число со знаком. В противном случае интерпретировать как целое число без знака.
dtype: Тип данных, в который следует выполнить интерпретацию.

Примеры

>>> s = pl.Series("a", [1, 1, 2], dtype=pl.UInt64)
>>> df = pl.DataFrame([s])
>>> df.select(
...     [
...         pl.col("a").reinterpret(dtype=pl.Int64).alias("reinterpreted"),
...         pl.col("a").alias("original"),
...     ]
... )
shape: (3, 2)
┌───────────────┬──────────┐
│ reinterpreted ┆ original │
│ ---           ┆ ---      │
│ i64           ┆ u64      │
╞═══════════════╪══════════╡
│ 1             ┆ 1        │
│ 1             ┆ 1        │
│ 2             ┆ 2        │
└───────────────┴──────────┘

repeat_by(
    by: Series | Expr | str_ | int,
) → Expr

Повторяет элементы этой Series указанное в заданном выражении число раз.

движок:В памяти

Повторённые элементы разворачиваются в List.

Параметры:

by: Числовой столбец, определяющий количество повторений значений. Столбец будет преобразован в UInt32. Укажите этот тип данных, чтобы преобразование не выполнялось.

Возвращает:

Expr: Выражение типа данных List, внутренний тип данных которого совпадает с исходным типом данных.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": ["x", "y", "z"],
...         "n": [1, 2, 3],
...     }
... )
>>> df.select(pl.col("a").repeat_by("n"))
shape: (3, 1)
┌─────────────────┐
│ a               │
│ ---             │
│ list[str]       │
╞═════════════════╡
│ ["x"]           │
│ ["y", "y"]      │
│ ["z", "z", "z"] │
└─────────────────┘

replace(
    old: IntoExpr | Sequence[Any] | Mapping[Any,
    Any],
    new: IntoExpr | Sequence[Any] | NoDefault = <no_default>,
    *,
    default: IntoExpr | NoDefault = <no_default>,
    return_dtype: PolarsDataType | None = None,
) → Expr

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

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

Параметры:

old: Значение или последовательность значений для замены. Принимает выражение. Последовательности интерпретируются как Series, другие входные данные, не являющиеся выражениями, интерпретируются как литералы. Также принимает словарь соответствий значений и замен в качестве синтаксического сокращения для replace(old=Series(mapping.keys()), new=Series(mapping.values())).
new: Значение или последовательность значений, которыми выполняется замена. Принимает выражение. Последовательности интерпретируются как Series, другие входные данные, не являющиеся выражениями, интерпретируются как литералы. Длина должна совпадать с длиной old или равняться 1.
default: Задаёт значение для элементов, которые не были заменены. По умолчанию сохраняется исходное значение. Принимает выражение. Входные данные, не являющиеся выражениями, интерпретируются как литералы.

Устарело с версии 1.0.0: Чтобы задать значение по умолчанию при замене значений, используйте replace_strict().
return_dtype: Тип данных результирующего выражения. Если задано значение None (по умолчанию), сохраняется тип данных исходного столбца.

Устарело с версии 1.0.0: Чтобы задать тип данных результата при замене значений, используйте replace_strict() либо явно вызовите cast() для результата.

См. также

replace_strict
str.replace

Примеры

Замените одно значение другим. Значения, которые не были заменены, остаются без изменений.

>>> df = pl.DataFrame({"a": [1, 2, 2, 3]})
>>> df.with_columns(replaced=pl.col("a").replace(2, 100))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 1        │
│ 2   ┆ 100      │
│ 2   ┆ 100      │
│ 3   ┆ 3        │
└─────┴──────────┘

Замените несколько значений, передав последовательности в параметры old и new.

>>> df.with_columns(replaced=pl.col("a").replace([2, 3], [100, 200]))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 1        │
│ 2   ┆ 100      │
│ 2   ┆ 100      │
│ 3   ┆ 200      │
└─────┴──────────┘

Также поддерживается передача словаря замен в качестве синтаксического сокращения.

>>> mapping = {2: 100, 3: 200}
>>> df.with_columns(replaced=pl.col("a").replace(mapping))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 1        │
│ 2   ┆ 100      │
│ 2   ┆ 100      │
│ 3   ┆ 200      │
└─────┴──────────┘

При замене на значения другого типа данных исходный тип данных сохраняется. Чтобы выполнить замену с изменением типа данных результата, используйте replace_strict().

>>> df = pl.DataFrame({"a": ["x", "y", "z"]})
>>> mapping = {"x": 1, "y": 2, "z": 3}
>>> df.with_columns(replaced=pl.col("a").replace(mapping))
shape: (3, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ str ┆ str      │
╞═════╪══════════╡
│ x   ┆ 1        │
│ y   ┆ 2        │
│ z   ┆ 3        │
└─────┴──────────┘

Поддерживается передача выражения.

>>> df = pl.DataFrame({"a": [1, 2, 2, 3], "b": [1.5, 2.5, 5.0, 1.0]})
>>> df.with_columns(
...     replaced=pl.col("a").replace(
...         old=pl.col("a").max(),
...         new=pl.col("b").sum(),
...     )
... )
shape: (4, 3)
┌─────┬─────┬──────────┐
│ a   ┆ b   ┆ replaced │
│ --- ┆ --- ┆ ---      │
│ i64 ┆ f64 ┆ i64      │
╞═════╪═════╪══════════╡
│ 1   ┆ 1.5 ┆ 1        │
│ 2   ┆ 2.5 ┆ 2        │
│ 2   ┆ 5.0 ┆ 2        │
│ 3   ┆ 1.0 ┆ 10       │
└─────┴─────┴──────────┘

replace_strict(
    old: IntoExpr | Sequence[Any] | Mapping[Any,
    Any],
    new: IntoExpr | Sequence[Any] | NoDefault = <no_default>,
    *,
    default: IntoExpr | NoDefault = <no_default>,
    return_dtype: PolarsDataType | DataTypeExpr | None = None,
) → Expr

Заменяет все значения другими значениями.

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

Параметры:

old: Значение или последовательность значений для замены. Принимает выражение. Последовательности интерпретируются как Series, другие входные данные, не являющиеся выражениями, интерпретируются как литералы. Также принимает словарь соответствий значений и замен в качестве синтаксического сокращения для replace_strict(old=Series(mapping.keys()), new=Series(mapping.values())).
new: Значение или последовательность значений, которыми выполняется замена. Принимает выражение. Последовательности интерпретируются как Series, другие входные данные, не являющиеся выражениями, интерпретируются как литералы. Длина должна совпадать с длиной old или равняться 1.
default: Задаёт значение для элементов, которые не были заменены. Если значение по умолчанию не указано (по умолчанию), возникает ошибка, если какие-либо значения не были заменены. Принимает выражение. Входные данные, не являющиеся выражениями, интерпретируются как литералы.
return_dtype: Тип данных результирующего выражения. Если задано значение None (по умолчанию), тип данных определяется автоматически на основе остальных входных данных.

Вызывает исключение:

InvalidOperationError: Если какие-либо ненулевые значения исходного столбца не были заменены и не задан параметр default.

См. также

replace
str.replace

Примеры

Замените значения, передав последовательности в параметры old и new.

>>> df = pl.DataFrame({"a": [1, 2, 2, 3]})
>>> df.with_columns(
...     replaced=pl.col("a").replace_strict([1, 2, 3], [100, 200, 300])
... )
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 100      │
│ 2   ┆ 200      │
│ 2   ┆ 200      │
│ 3   ┆ 300      │
└─────┴──────────┘

Также поддерживается передача словаря замен в качестве синтаксического сокращения.

>>> mapping = {1: 100, 2: 200, 3: 300}
>>> df.with_columns(replaced=pl.col("a").replace_strict(mapping))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ 100      │
│ 2   ┆ 200      │
│ 2   ┆ 200      │
│ 3   ┆ 300      │
└─────┴──────────┘

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

>>> mapping = {2: 200, 3: 300}
>>> df.with_columns(
...     replaced=pl.col("a").replace_strict(mapping)
... )  
Traceback (most recent call last):
...
polars.exceptions.InvalidOperationError: incomplete mapping specified for `replace_strict`
>>> df.with_columns(replaced=pl.col("a").replace_strict(mapping, default=-1))
shape: (4, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ i64 ┆ i64      │
╞═════╪══════════╡
│ 1   ┆ -1       │
│ 2   ┆ 200      │
│ 2   ┆ 200      │
│ 3   ┆ 300      │
└─────┴──────────┘

При замене на значения другого типа данных тип результата определяется на основе сочетания типа данных new и типа данных default.

>>> df = pl.DataFrame({"a": ["x", "y", "z"]})
>>> mapping = {"x": 1, "y": 2, "z": 3}
>>> df.with_columns(replaced=pl.col("a").replace_strict(mapping))
shape: (3, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ str ┆ i64      │
╞═════╪══════════╡
│ x   ┆ 1        │
│ y   ┆ 2        │
│ z   ┆ 3        │
└─────┴──────────┘
>>> df.with_columns(replaced=pl.col("a").replace_strict(mapping, default="x"))
shape: (3, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ str ┆ str      │
╞═════╪══════════╡
│ x   ┆ 1        │
│ y   ┆ 2        │
│ z   ┆ 3        │
└─────┴──────────┘

Задайте параметр return_dtype, чтобы напрямую управлять типом данных результата.

>>> df.with_columns(
...     replaced=pl.col("a").replace_strict(mapping, return_dtype=pl.UInt8)
... )
shape: (3, 2)
┌─────┬──────────┐
│ a   ┆ replaced │
│ --- ┆ ---      │
│ str ┆ u8       │
╞═════╪══════════╡
│ x   ┆ 1        │
│ y   ┆ 2        │
│ z   ┆ 3        │
└─────┴──────────┘

Для всех параметров поддерживается передача выражения.

>>> df = pl.DataFrame({"a": [1, 2, 2, 3], "b": [1.5, 2.5, 5.0, 1.0]})
>>> df.with_columns(
...     replaced=pl.col("a").replace_strict(
...         old=pl.col("a").max(),
...         new=pl.col("b").sum(),
...         default=pl.col("b"),
...     )
... )
shape: (4, 3)
┌─────┬─────┬──────────┐
│ a   ┆ b   ┆ replaced │
│ --- ┆ --- ┆ ---      │
│ i64 ┆ f64 ┆ f64      │
╞═════╪═════╪══════════╡
│ 1   ┆ 1.5 ┆ 1.5      │
│ 2   ┆ 2.5 ┆ 2.5      │
│ 2   ┆ 5.0 ┆ 5.0      │
│ 3   ┆ 1.0 ┆ 10.0     │
└─────┴─────┴──────────┘

reshape(
    dimensions: tuple[int,
    ...],
) → Expr

Преобразует форму этого Expr в плоский столбец или столбец Array.

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

Параметры:

dimensions: Кортеж размеров измерений. Если для первого измерения указано значение -1, его размер определяется автоматически. Поскольку размер столбца может быть неизвестен заранее, использовать -1 можно только для первого измерения.

Возвращает:

Expr: Если указано одно измерение, результатом будет выражение исходного типа данных. Если указано несколько измерений, результатом будет выражение типа данных Array с формой dimensions.

См. также

Expr.list.explode: Раскрывает столбец со списками.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5, 6, 7, 8, 9]})
>>> square = df.select(pl.col("foo").reshape((3, 3)))
>>> square
shape: (3, 1)
┌───────────────┐
│ foo           │
│ ---           │
│ array[i64, 3] │
╞═══════════════╡
│ [1, 2, 3]     │
│ [4, 5, 6]     │
│ [7, 8, 9]     │
└───────────────┘
>>> square.select(pl.col("foo").reshape((9,)))
shape: (9, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
│ 4   │
│ 5   │
│ 6   │
│ 7   │
│ 8   │
│ 9   │
└─────┘

reverse() → Expr

Обращает порядок выборки.

движок:В памяти

Примеры

>>> df = pl.DataFrame(
...     {
...         "A": [1, 2, 3, 4, 5],
...         "fruits": ["banana", "banana", "apple", "apple", "banana"],
...         "B": [5, 4, 3, 2, 1],
...         "cars": ["beetle", "audi", "beetle", "beetle", "beetle"],
...     }
... )
>>> df.select(
...     [
...         pl.all(),
...         pl.all().reverse().name.suffix("_reverse"),
...     ]
... )
shape: (5, 8)
┌─────┬────────┬─────┬────────┬───────────┬────────────────┬───────────┬──────────────┐
│ A   ┆ fruits ┆ B   ┆ cars   ┆ A_reverse ┆ fruits_reverse ┆ B_reverse ┆ cars_reverse │
│ --- ┆ ---    ┆ --- ┆ ---    ┆ ---       ┆ ---            ┆ ---       ┆ ---          │
│ i64 ┆ str    ┆ i64 ┆ str    ┆ i64       ┆ str            ┆ i64       ┆ str          │
╞═════╪════════╪═════╪════════╪═══════════╪════════════════╪═══════════╪══════════════╡
│ 1   ┆ banana ┆ 5   ┆ beetle ┆ 5         ┆ banana         ┆ 1         ┆ beetle       │
│ 2   ┆ banana ┆ 4   ┆ audi   ┆ 4         ┆ apple          ┆ 2         ┆ beetle       │
│ 3   ┆ apple  ┆ 3   ┆ beetle ┆ 3         ┆ apple          ┆ 3         ┆ beetle       │
│ 4   ┆ apple  ┆ 2   ┆ beetle ┆ 2         ┆ banana         ┆ 4         ┆ audi         │
│ 5   ┆ banana ┆ 1   ┆ beetle ┆ 1         ┆ banana         ┆ 5         ┆ beetle       │
└─────┴────────┴─────┴────────┴───────────┴────────────────┴───────────┴──────────────┘

rle() → Expr

Сжимает данные столбца с помощью кодирования длин серий.

Кодирование длин серий (RLE) сжимает данные, представляя каждую серию одинаковых значений одним значением и её длиной.

движок:В памятиПотоковый

Возвращает:

Expr: Выражение типа данных Struct с полями len типа данных UInt32 и value исходного типа данных.

См. также

rle_id

Примеры

>>> df = pl.DataFrame({"a": [1, 1, 2, 1, None, 1, 3, 3]})
>>> df.select(pl.col("a").rle()).unnest("a")
shape: (6, 2)
┌─────┬───────┐
│ len ┆ value │
│ --- ┆ ---   │
│ u32 ┆ i64   │
╞═════╪═══════╡
│ 2   ┆ 1     │
│ 1   ┆ 2     │
│ 1   ┆ 1     │
│ 1   ┆ null  │
│ 1   ┆ 1     │
│ 2   ┆ 3     │
└─────┴───────┘

rle_id() → Expr

Возвращает отдельный целочисленный идентификатор для каждой серии одинаковых значений.

Идентификатор начинается с 0 и увеличивается на единицу при каждом изменении значения столбца.

движок:В памятиПотоковый

Возвращает:

Expr: Выражение типа данных UInt32.

См. также

rle

Примечания

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 1, 1, 1],
...         "b": ["x", "x", None, "y", "y"],
...     }
... )
>>> df.with_columns(
...     rle_id_a=pl.col("a").rle_id(),
...     rle_id_ab=pl.struct("a", "b").rle_id(),
... )
shape: (5, 4)
┌─────┬──────┬──────────┬───────────┐
│ a   ┆ b    ┆ rle_id_a ┆ rle_id_ab │
│ --- ┆ ---  ┆ ---      ┆ ---       │
│ i64 ┆ str  ┆ u32      ┆ u32       │
╞═════╪══════╪══════════╪═══════════╡
│ 1   ┆ x    ┆ 0        ┆ 0         │
│ 2   ┆ x    ┆ 1        ┆ 1         │
│ 1   ┆ null ┆ 2        ┆ 2         │
│ 1   ┆ y    ┆ 2        ┆ 3         │
│ 1   ┆ y    ┆ 2        ┆ 3         │
└─────┴──────┴──────────┴───────────┘

rolling(
    index_column: IntoExprColumn,
    *,
    period: str_ | timedelta,
    offset: str_ | timedelta | None = None,
    closed: ClosedInterval = 'right',
) → Expr

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

Если у вас есть временной ряд <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 часа из-за перехода на летнее время). То же относится к «календарной неделе», «календарному месяцу», «календарному кварталу» и «календарному году».

движок:В памяти

Параметры:

index_column: Столбец, используемый для группировки по временному окну. Часто имеет тип Date/Datetime. Этот столбец должен быть отсортирован по возрастанию. При скользящей группировке по индексам тип данных должен быть одним из следующих: {UInt32, UInt64, Int32, Int64}. Обратите внимание, что первые три типа временно приводятся к Int64, поэтому, если важна производительность, используйте столбец типа Int64.
period: Длина окна — должна быть неотрицательной.
offset: Смещение окна. Значение по умолчанию — -period.
closed{‘right’, ‘left’, ‘both’, ‘none’}: Задаёт, какие границы временного интервала являются закрытыми (включительными).

Примеры

>>> 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()
... )
>>> df.with_columns(
...     sum_a=pl.sum("a").rolling(index_column="dt", period="2d"),
...     min_a=pl.min("a").rolling(index_column="dt", period="2d"),
...     max_a=pl.max("a").rolling(index_column="dt", period="2d"),
... )
shape: (6, 5)
┌─────────────────────┬─────┬───────┬───────┬───────┐
│ dt                  ┆ a   ┆ sum_a ┆ min_a ┆ max_a │
│ ---                 ┆ --- ┆ ---   ┆ ---   ┆ ---   │
│ datetime[μs]        ┆ i64 ┆ i64   ┆ i64   ┆ i64   │
╞═════════════════════╪═════╪═══════╪═══════╪═══════╡
│ 2020-01-01 13:45:48 ┆ 3   ┆ 3     ┆ 3     ┆ 3     │
│ 2020-01-01 16:42:13 ┆ 7   ┆ 10    ┆ 3     ┆ 7     │
│ 2020-01-01 16:45:09 ┆ 5   ┆ 15    ┆ 3     ┆ 7     │
│ 2020-01-02 18:12:48 ┆ 9   ┆ 24    ┆ 3     ┆ 9     │
│ 2020-01-03 19:45:32 ┆ 2   ┆ 11    ┆ 2     ┆ 9     │
│ 2020-01-08 23:16:43 ┆ 1   ┆ 1     ┆ 1     ┆ 1     │
└─────────────────────┴─────┴───────┴───────┴───────┘

rolling_kurtosis(
    window_size: int,
    *,
    fisher: bool = True,
    bias: bool = True,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычисляет скользящий эксцесс.

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без предупреждения о нарушении обратной совместимости.

Окно для заданной строки включает саму строку и window_size - 1 предшествующих элементов.

движок:В памяти

Параметры:

window_size: Целочисленный размер скользящего окна.
fisherbool, optional: Если True, используется определение Фишера (для нормального распределения ==> 0.0). Если False, используется определение Пирсона (для нормального распределения ==> 3.0).
biasbool, optional: Если False, вычисления корректируются с учётом статистического смещения.
min_samples: Количество значений в окне, которые не должны быть null, чтобы вычислить результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Размещает метки в центре окна.

См. также

Expr.kurtosis

Примеры

>>> df = pl.DataFrame({"a": [1, 4, 2, 9]})
>>> df.select(pl.col("a").rolling_kurtosis(3))
shape: (4, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ null │
│ -1.5 │
│ -1.5 │
└──────┘

rolling_map(
    function: Callable[[Series],
    Any],
    window_size: int,
    weights: list_[float] | None = None,
    *,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычисляет пользовательскую функцию для скользящего окна.

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

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памяти

Параметры:

function: Пользовательская функция агрегации.
window_size: Длина окна в количестве элементов.
weights: Необязательный срез той же длины, что и окно. Его элементы перемножаются с соответствующими значениями в окне.
min_samples: Количество значений в окне, которые не должны быть null, чтобы вычислить результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Размещает метки в центре окна.

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

Вычисление пользовательских функций выполняется крайне медленно. По возможности используйте специализированные функции скользящего окна, например Expr.rolling_sum().

Примеры

>>> from numpy import nansum
>>> df = pl.DataFrame({"a": [11.0, 2.0, 9.0, float("nan"), 8.0]})
>>> df.select(pl.col("a").rolling_map(nansum, window_size=3))
shape: (5, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ null │
│ null │
│ 22.0 │
│ 11.0 │
│ 17.0 │
└──────┘

rolling_max(
    window_size: int,
    weights: list_[float] | None = None,
    *,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычисляет скользящий максимум для значений в этом массиве.

По массиву проходит окно длиной window_size. Значения, попавшие в это окно, могут умножаться на соответствующие веса из вектора weights. Затем для полученных значений вычисляется максимум.

Окно для заданной строки включает саму строку и window_size - 1 предшествующих элементов.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

window_size: Длина окна в количестве элементов.
weights: Необязательный срез той же длины, что и окно. Его элементы перемножаются с соответствующими значениями в окне.
min_samples: Количество значений в окне, которые не должны быть null, чтобы вычислить результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Размещает метки в центре окна.

Примечания

Если требуется вычислить несколько статистик агрегации для одного динамического окна, рассмотрите возможность использования rolling — этот метод может кэшировать вычисление размера окна.

Примеры

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_max=pl.col("A").rolling_max(window_size=2),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_max │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 2.0         │
│ 3.0 ┆ 3.0         │
│ 4.0 ┆ 4.0         │
│ 5.0 ┆ 5.0         │
│ 6.0 ┆ 6.0         │
└─────┴─────────────┘

Задайте веса, на которые будут умножаться значения в окне:

>>> df.with_columns(
...     rolling_max=pl.col("A").rolling_max(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_max │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.5         │
│ 3.0 ┆ 2.25        │
│ 4.0 ┆ 3.0         │
│ 5.0 ┆ 3.75        │
│ 6.0 ┆ 4.5         │
└─────┴─────────────┘

Разместите значения в центре окна

>>> df.with_columns(
...     rolling_max=pl.col("A").rolling_max(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_max │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 3.0         │
│ 3.0 ┆ 4.0         │
│ 4.0 ┆ 5.0         │
│ 5.0 ┆ 6.0         │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_max_by(
    by: IntoExpr,
    window_size: timedelta | str_,
    *,
    min_samples: int = 1,
    closed: ClosedInterval = 'right',
) → Expr

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

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

Для столбца by <t_0, t_1, ..., t_n> значение closed="right" (по умолчанию) означает, что окна будут следующими:

(t_0 - window_size, t_0]
(t_1 - window_size, t_1]
…
(t_n - window_size, t_n]

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памяти

Параметры:

by

Тип данных должен быть DateTime, Date, UInt64, UInt32, Int64 или Int32 (обратите внимание, что для целочисленных типов в window size необходимо использовать 'i').

window_size

Длина окна. Может быть динамическим временным интервалом, заданным объектом 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 индекс)

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

min_samples

Количество значений в окне, которые не должны быть null, чтобы вычислить результат.

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

Задаёт, какие границы временного интервала являются закрытыми (включительными); по умолчанию используется 'right'.

Примечания

Примеры

Создайте DataFrame со столбцом datetime и столбцом с номером строки

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Вычислите скользящий максимум с временными окнами, закрытыми справа (по умолчанию)

>>> df_temporal.with_columns(
...     rolling_row_max=pl.col("index").rolling_max_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_max │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 1               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 2               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 3               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 4               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 20              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 21              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 22              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 23              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 24              │
└───────┴─────────────────────┴─────────────────┘

Вычислите скользящий максимум с окнами, закрытыми с обеих сторон

>>> df_temporal.with_columns(
...     rolling_row_max=pl.col("index").rolling_max_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_max │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 1               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 2               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 3               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 4               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 20              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 21              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 22              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 23              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 24              │
└───────┴─────────────────────┴─────────────────┘

rolling_mean(
    window_size: int,
    weights: list_[float] | None = None,
    *,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычисляет скользящее среднее для значений в этом массиве.

Окно для заданной строки включает саму строку и window_size - 1 предшествующих элементов.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

window_size: Длина окна в количестве элементов.
weights: Необязательный срез той же длины, что и окно. Его элементы после нормализации так, чтобы их сумма равнялась 1, перемножаются с соответствующими значениями в окне.
min_samples: Количество значений в окне, которые не должны быть null, чтобы вычислить результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Размещает метки в центре окна.

Примечания

Примеры

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_mean=pl.col("A").rolling_mean(window_size=2),
... )
shape: (6, 2)
┌─────┬──────────────┐
│ A   ┆ rolling_mean │
│ --- ┆ ---          │
│ f64 ┆ f64          │
╞═════╪══════════════╡
│ 1.0 ┆ null         │
│ 2.0 ┆ 1.5          │
│ 3.0 ┆ 2.5          │
│ 4.0 ┆ 3.5          │
│ 5.0 ┆ 4.5          │
│ 6.0 ┆ 5.5          │
└─────┴──────────────┘

Задайте веса, на которые будут умножаться значения в окне:

>>> df.with_columns(
...     rolling_mean=pl.col("A").rolling_mean(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬──────────────┐
│ A   ┆ rolling_mean │
│ --- ┆ ---          │
│ f64 ┆ f64          │
╞═════╪══════════════╡
│ 1.0 ┆ null         │
│ 2.0 ┆ 1.75         │
│ 3.0 ┆ 2.75         │
│ 4.0 ┆ 3.75         │
│ 5.0 ┆ 4.75         │
│ 6.0 ┆ 5.75         │
└─────┴──────────────┘

Разместите значения в центре окна

>>> df.with_columns(
...     rolling_mean=pl.col("A").rolling_mean(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬──────────────┐
│ A   ┆ rolling_mean │
│ --- ┆ ---          │
│ f64 ┆ f64          │
╞═════╪══════════════╡
│ 1.0 ┆ null         │
│ 2.0 ┆ 2.0          │
│ 3.0 ┆ 3.0          │
│ 4.0 ┆ 4.0          │
│ 5.0 ┆ 5.0          │
│ 6.0 ┆ null         │
└─────┴──────────────┘

rolling_mean_by(
    by: IntoExpr,
    window_size: timedelta | str_,
    *,
    min_samples: int = 1,
    closed: ClosedInterval = 'right',
) → Expr

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

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

Для столбца by <t_0, t_1, ..., t_n> значение closed="right" (по умолчанию) означает, что окна будут следующими:

(t_0 - window_size, t_0]
(t_1 - window_size, t_1]
…
(t_n - window_size, t_n]

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памяти

Параметры:

by

window_size

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

min_samples

Количество значений в окне, которые не должны быть null, чтобы вычислить результат.

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

Примечания

Примеры

Создайте DataFrame со столбцом datetime и столбцом с номером строки

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Вычислите скользящее среднее с временными окнами, закрытыми справа (по умолчанию)

>>> df_temporal.with_columns(
...     rolling_row_mean=pl.col("index").rolling_mean_by(
...         "date", window_size="2h"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬──────────────────┐
│ index ┆ date                ┆ rolling_row_mean │
│ ---   ┆ ---                 ┆ ---              │
│ u32   ┆ datetime[μs]        ┆ f64              │
╞═══════╪═════════════════════╪══════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0.0              │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5              │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.5              │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2.5              │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3.5              │
│ …     ┆ …                   ┆ …                │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19.5             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20.5             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21.5             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22.5             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23.5             │
└───────┴─────────────────────┴──────────────────┘

Вычислите скользящее среднее с окнами, закрытыми с обеих сторон

>>> df_temporal.with_columns(
...     rolling_row_mean=pl.col("index").rolling_mean_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬──────────────────┐
│ index ┆ date                ┆ rolling_row_mean │
│ ---   ┆ ---                 ┆ ---              │
│ u32   ┆ datetime[μs]        ┆ f64              │
╞═══════╪═════════════════════╪══════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0.0              │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5              │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.0              │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2.0              │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3.0              │
│ …     ┆ …                   ┆ …                │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19.0             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20.0             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21.0             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22.0             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23.0             │
└───────┴─────────────────────┴──────────────────┘

rolling_median(
    window_size: int,
    weights: list_[float] | None = None,
    *,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычисляет скользящую медиану.

Окно для заданной строки включает саму строку и window_size - 1 предшествующих элементов.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

window_size: Длина окна в количестве элементов.
weights: Необязательный срез той же длины, что и окно. Его элементы перемножаются с соответствующими значениями в окне.
min_samples: Количество значений в окне, которые не должны быть null, чтобы вычислить результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Размещает метки в центре окна.

Примечания

Примеры

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_median=pl.col("A").rolling_median(window_size=2),
... )
shape: (6, 2)
┌─────┬────────────────┐
│ A   ┆ rolling_median │
│ --- ┆ ---            │
│ f64 ┆ f64            │
╞═════╪════════════════╡
│ 1.0 ┆ null           │
│ 2.0 ┆ 1.5            │
│ 3.0 ┆ 2.5            │
│ 4.0 ┆ 3.5            │
│ 5.0 ┆ 4.5            │
│ 6.0 ┆ 5.5            │
└─────┴────────────────┘

Задайте веса для значений в каждом окне:

>>> df.with_columns(
...     rolling_median=pl.col("A").rolling_median(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬────────────────┐
│ A   ┆ rolling_median │
│ --- ┆ ---            │
│ f64 ┆ f64            │
╞═════╪════════════════╡
│ 1.0 ┆ null           │
│ 2.0 ┆ 1.5            │
│ 3.0 ┆ 2.5            │
│ 4.0 ┆ 3.5            │
│ 5.0 ┆ 4.5            │
│ 6.0 ┆ 5.5            │
└─────┴────────────────┘

Разместите значения в центре окна

>>> df.with_columns(
...     rolling_median=pl.col("A").rolling_median(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬────────────────┐
│ A   ┆ rolling_median │
│ --- ┆ ---            │
│ f64 ┆ f64            │
╞═════╪════════════════╡
│ 1.0 ┆ null           │
│ 2.0 ┆ 2.0            │
│ 3.0 ┆ 3.0            │
│ 4.0 ┆ 4.0            │
│ 5.0 ┆ 5.0            │
│ 6.0 ┆ null           │
└─────┴────────────────┘

rolling_median_by(
    by: IntoExpr,
    window_size: timedelta | str_,
    *,
    min_samples: int = 1,
    closed: ClosedInterval = 'right',
) → Expr

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

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

Для столбца by <t_0, t_1, ..., t_n> значение closed="right" (по умолчанию) означает, что окна будут следующими:

(t_0 - window_size, t_0]
(t_1 - window_size, t_1]
…
(t_n - window_size, t_n]

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памяти

Параметры:

by

window_size

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

min_samples

Количество значений в окне, которые не должны быть null, чтобы вычислить результат.

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

Примечания

Примеры

Создайте DataFrame со столбцом datetime и столбцом с номером строки

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

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

>>> df_temporal.with_columns(
...     rolling_row_median=pl.col("index").rolling_median_by(
...         "date", window_size="2h"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬────────────────────┐
│ index ┆ date                ┆ rolling_row_median │
│ ---   ┆ ---                 ┆ ---                │
│ u32   ┆ datetime[μs]        ┆ f64                │
╞═══════╪═════════════════════╪════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0.0                │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5                │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.5                │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2.5                │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3.5                │
│ …     ┆ …                   ┆ …                  │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19.5               │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20.5               │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21.5               │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22.5               │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23.5               │
└───────┴─────────────────────┴────────────────────┘

rolling_min(
    window_size: int,
    weights: list_[float] | None = None,
    *,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычисляет скользящий минимум для значений в этом массиве.

Окно для заданной строки включает саму строку и window_size - 1 предшествующих элементов.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

window_size: Длина окна в количестве элементов.
weights: Необязательный срез той же длины, что и окно. Его элементы перемножаются с соответствующими значениями в окне.
min_samples: Количество значений в окне, которые не должны быть null, чтобы вычислить результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Размещает метки в центре окна.

Примечания

Примеры

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_min=pl.col("A").rolling_min(window_size=2),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_min │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.0         │
│ 3.0 ┆ 2.0         │
│ 4.0 ┆ 3.0         │
│ 5.0 ┆ 4.0         │
│ 6.0 ┆ 5.0         │
└─────┴─────────────┘

Задайте веса, на которые будут умножаться значения в окне:

>>> df.with_columns(
...     rolling_min=pl.col("A").rolling_min(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_min │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.25        │
│ 3.0 ┆ 0.5         │
│ 4.0 ┆ 0.75        │
│ 5.0 ┆ 1.0         │
│ 6.0 ┆ 1.25        │
└─────┴─────────────┘

Разместите значения в центре окна

>>> df.with_columns(
...     rolling_min=pl.col("A").rolling_min(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_min │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.0         │
│ 3.0 ┆ 2.0         │
│ 4.0 ┆ 3.0         │
│ 5.0 ┆ 4.0         │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_min_by(
    by: IntoExpr,
    window_size: timedelta | str_,
    *,
    min_samples: int = 1,
    closed: ClosedInterval = 'right',
) → Expr

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

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

Для столбца by <t_0, t_1, ..., t_n> значение closed="right" (по умолчанию) означает, что окна будут следующими:

(t_0 - window_size, t_0]
(t_1 - window_size, t_1]
…
(t_n - window_size, t_n]

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памяти

Параметры:

by

window_size

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

min_samples

Количество значений в окне, которые не должны быть null, чтобы вычислить результат.

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

Примечания

Примеры

Создайте DataFrame со столбцом datetime и столбцом с номером строки

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Вычислите скользящий минимум с временными окнами, закрытыми справа (по умолчанию)

>>> df_temporal.with_columns(
...     rolling_row_min=pl.col("index").rolling_min_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_min │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23              │
└───────┴─────────────────────┴─────────────────┘

rolling_quantile(
    quantile: float,
    interpolation: QuantileMethod = 'nearest',
    window_size: int = 2,
    weights: list_[float] | None = None,
    *,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычисляет скользящую квантиль.

Окно для заданной строки включает саму строку и window_size - 1 предшествующих элементов.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

quantile: Квантиль от 0.0 до 1.0.
interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’, ‘equiprobable’}: Метод интерполяции.
window_size: Длина окна в количестве элементов.
weights: Необязательный срез той же длины, что и окно. Его элементы перемножаются с соответствующими значениями в окне.
min_samples: Количество значений в окне, которые не должны быть null, чтобы вычислить результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Размещает метки в центре окна.

Примечания

Примеры

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_quantile=pl.col("A").rolling_quantile(
...         quantile=0.25, window_size=4
...     ),
... )
shape: (6, 2)
┌─────┬──────────────────┐
│ A   ┆ rolling_quantile │
│ --- ┆ ---              │
│ f64 ┆ f64              │
╞═════╪══════════════════╡
│ 1.0 ┆ null             │
│ 2.0 ┆ null             │
│ 3.0 ┆ null             │
│ 4.0 ┆ 2.0              │
│ 5.0 ┆ 3.0              │
│ 6.0 ┆ 4.0              │
└─────┴──────────────────┘

Задайте веса для значений в каждом окне:

>>> df.with_columns(
...     rolling_quantile=pl.col("A").rolling_quantile(
...         quantile=0.25, window_size=4, weights=[0.2, 0.4, 0.4, 0.2]
...     ),
... )
shape: (6, 2)
┌─────┬──────────────────┐
│ A   ┆ rolling_quantile │
│ --- ┆ ---              │
│ f64 ┆ f64              │
╞═════╪══════════════════╡
│ 1.0 ┆ null             │
│ 2.0 ┆ null             │
│ 3.0 ┆ null             │
│ 4.0 ┆ 2.0              │
│ 5.0 ┆ 3.0              │
│ 6.0 ┆ 4.0              │
└─────┴──────────────────┘

Задайте веса и метод интерполяции

>>> df.with_columns(
...     rolling_quantile=pl.col("A").rolling_quantile(
...         quantile=0.25,
...         window_size=4,
...         weights=[0.2, 0.4, 0.4, 0.2],
...         interpolation="linear",
...     ),
... )
shape: (6, 2)
┌─────┬──────────────────┐
│ A   ┆ rolling_quantile │
│ --- ┆ ---              │
│ f64 ┆ f64              │
╞═════╪══════════════════╡
│ 1.0 ┆ null             │
│ 2.0 ┆ null             │
│ 3.0 ┆ null             │
│ 4.0 ┆ 1.625            │
│ 5.0 ┆ 2.625            │
│ 6.0 ┆ 3.625            │
└─────┴──────────────────┘

Разместите значения в центре окна

>>> df.with_columns(
...     rolling_quantile=pl.col("A").rolling_quantile(
...         quantile=0.2, window_size=5, center=True
...     ),
... )
shape: (6, 2)
┌─────┬──────────────────┐
│ A   ┆ rolling_quantile │
│ --- ┆ ---              │
│ f64 ┆ f64              │
╞═════╪══════════════════╡
│ 1.0 ┆ null             │
│ 2.0 ┆ null             │
│ 3.0 ┆ 2.0              │
│ 4.0 ┆ 3.0              │
│ 5.0 ┆ null             │
│ 6.0 ┆ null             │
└─────┴──────────────────┘

rolling_quantile_by(
    by: IntoExpr,
    window_size: timedelta | str_,
    *,
    quantile: float,
    interpolation: QuantileMethod = 'nearest',
    min_samples: int = 1,
    closed: ClosedInterval = 'right',
) → Expr

Вычислить скользящий квантиль на основе другого столбца.

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

Эта функциональность считается нестабильной. Она может быть изменена в любой момент без того, чтобы это считалось несовместимым изменением.

Для столбца by <t_0, t_1, ..., t_n> значение closed="right" (по умолчанию) означает, что окна будут следующими:

(t_0 - window_size, t_0]
(t_1 - window_size, t_1]
…
(t_n - window_size, t_n]

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памяти

Параметры:

by

Должен иметь тип данных DateTime, Date, UInt64, UInt32, Int64 или Int32 (обратите внимание, что для целочисленных типов требуется использовать 'i' в window size).

quantile

Квантиль от 0.0 до 1.0.

interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’, ‘equiprobable’}

Метод интерполяции.

window_size

Длина окна. Может быть динамическим временным интервалом, заданным объектом 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 индекс)

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

min_samples

Количество значений в окне, которые должны быть не-null, прежде чем будет вычислен результат.

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

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

Примечания

Если нужно вычислить несколько агрегатных статистик для одного и того же динамического окна, рассмотрите возможность использования rolling — этот метод может кэшировать вычисление размера окна.

Примеры

Создание DataFrame со столбцом datetime и столбцом с номерами строк

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Вычисление скользящего квантиля с временными окнами, закрытыми справа:

>>> df_temporal.with_columns(
...     rolling_row_quantile=pl.col("index").rolling_quantile_by(
...         "date", window_size="2h", quantile=0.3
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬──────────────────────┐
│ index ┆ date                ┆ rolling_row_quantile │
│ ---   ┆ ---                 ┆ ---                  │
│ u32   ┆ datetime[μs]        ┆ f64                  │
╞═══════╪═════════════════════╪══════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0.0                  │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.0                  │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.0                  │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 2.0                  │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 3.0                  │
│ …     ┆ …                   ┆ …                    │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 19.0                 │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 20.0                 │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 21.0                 │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 22.0                 │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 23.0                 │
└───────┴─────────────────────┴──────────────────────┘

rolling_rank(
    window_size: int,
    method: RankMethod = 'average',
    *,
    seed: int | None = None,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычислить скользящий ранг.

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

По массиву проходит окно длины window_size. Значения в этом окне ранжируются в соответствии с параметром method. Результирующие значения будут рангами элементов, находящихся в конце скользящего окна.

движок:В памяти

Параметры:

window_size

Целочисленный размер скользящего окна.

method{‘average’, ‘min’, ‘max’, ‘dense’, ‘random’}

Метод присвоения рангов элементам с одинаковыми значениями. Доступны следующие методы (по умолчанию — ‘average’):

‘average’ : Каждому значению присваивается среднее значение рангов, которые были бы присвоены всем совпадающим значениям.
‘min’ : Каждому значению присваивается минимальный из рангов, которые были бы присвоены всем совпадающим значениям. (Также называется ранжированием «соревновательного» типа.)
‘max’ : Каждому значению присваивается максимальный из рангов, которые были бы присвоены всем совпадающим значениям.
‘dense’ : Аналогично ‘min’, но следующему по величине элементу присваивается ранг, следующий непосредственно за рангами совпадающих элементов.
‘random’ : Каждому из совпадающих значений присваивается случайный ранг.

seed

Начальное значение генератора случайных чисел, используемое при method='random'. Если задано None (по умолчанию), для каждой операции вычисления скользящего ранга генерируется случайное начальное значение.

min_samples

Количество значений в окне, которые должны быть не-null, прежде чем будет вычислен результат. Если задано None (по умолчанию), оно будет равно window_size.

center

Разместить метки в центре окна.

Возвращает:

Expr: Expr с типом данных Float64, если method равно "average", иначе — размер индекса (см. get_index_type()).

Примеры

>>> df = pl.DataFrame({"a": [1, 4, 4, 1, 9]})
>>> df.select(pl.col("a").rolling_rank(3, method="average"))
    shape: (5, 1)
    ┌──────┐
    │ a    │
    │ ---  │
    │ f64  │
    ╞══════╡
    │ null │
    │ null │
    │ 2.5  │
    │ 1.0  │
    │ 3.0  │
    └──────┘

rolling_rank_by(
    by: IntoExpr,
    window_size: timedelta | str_,
    method: RankMethod = 'average',
    *,
    seed: int | None = None,
    min_samples: int = 1,
    closed: ClosedInterval = 'right',
) → Expr

Вычислить скользящий ранг на основе другого столбца.

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

Для столбца by <t_0, t_1, ..., t_n> значение closed="right" (по умолчанию) означает, что окна будут следующими:

(t_0 - window_size, t_0]
(t_1 - window_size, t_1]
…
(t_n - window_size, t_n]

движок:В памяти

Параметры:

by

window_size

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

method{‘average’, ‘min’, ‘max’, ‘dense’, ‘random’}

‘average’ : Каждому значению присваивается среднее значение рангов, которые были бы присвоены всем совпадающим значениям.
‘min’ : Каждому значению присваивается минимальный из рангов, которые были бы присвоены всем совпадающим значениям. (Также называется ранжированием «соревновательного» типа.)
‘max’ : Каждому значению присваивается максимальный из рангов, которые были бы присвоены всем совпадающим значениям.
‘dense’ : Аналогично ‘min’, но следующему по величине элементу присваивается ранг, следующий непосредственно за рангами совпадающих элементов.
‘random’ : Каждому из совпадающих значений присваивается случайный ранг.

seed

min_samples

Количество значений в окне, которые должны быть не-null, прежде чем будет вычислен результат.

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

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

Возвращает:

Expr: Expr с типом данных Float64, если method равно "average", иначе — размер индекса (см. get_index_type()).

rolling_skew(
    window_size: int,
    *,
    bias: bool = True,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычислить скользящую асимметрию.

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

Окно для заданной строки включает саму строку и window_size - 1 предшествующих ей элементов.

движок:В памяти

Параметры:

window_size

Целочисленный размер скользящего окна.

bias

Если False, расчёты корректируются с учётом статистического смещения.: bias: bool = True,

min_samples

center

Разместить метки в центре окна.

См. также

Expr.skew

Примеры

>>> df = pl.DataFrame({"a": [1, 4, 2, 9]})
>>> df.select(pl.col("a").rolling_skew(3))
shape: (4, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ null     │
│ null     │
│ 0.381802 │
│ 0.47033  │
└──────────┘

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

>>> pl.Series([1, 4, 2]).skew(), pl.Series([4, 2, 9]).skew()
(0.38180177416060584, 0.47033046033698594)

rolling_std(
    window_size: int,
    weights: list_[float] | None = None,
    *,
    min_samples: int | None = None,
    center: bool = False,
    ddof: int = 1,
) → Expr

Вычислить скользящее стандартное отклонение.

По массиву проходит окно длины window_size. Значения в этом окне могут быть умножены на веса, заданные вектором weights. Полученные значения агрегируются для вычисления стандартного отклонения. Веса нормализуются так, чтобы их сумма равнялась 1.

Окно для заданной строки включает саму строку и window_size - 1 предшествующих ей элементов.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

window_size: Длина окна в количестве элементов.
weights: Необязательный срез той же длины, что и окно. После нормализации до суммы 1 его элементы поэлементно умножаются на значения в окне.
min_samples: Количество значений в окне, которые должны быть не-null, прежде чем будет вычислен результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Разместить метки в центре окна.
ddof: «Поправка на число степеней свободы»: делитель для окна длины N равен N - ddof

Примечания

Примеры

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_std=pl.col("A").rolling_std(window_size=2),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_std │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.707107    │
│ 3.0 ┆ 0.707107    │
│ 4.0 ┆ 0.707107    │
│ 5.0 ┆ 0.707107    │
│ 6.0 ┆ 0.707107    │
└─────┴─────────────┘

Задание весов для умножения на значения в окне:

>>> df.with_columns(
...     rolling_std=pl.col("A").rolling_std(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_std │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.433013    │
│ 3.0 ┆ 0.433013    │
│ 4.0 ┆ 0.433013    │
│ 5.0 ┆ 0.433013    │
│ 6.0 ┆ 0.433013    │
└─────┴─────────────┘

Центрирование значений в окне

>>> df.with_columns(
...     rolling_std=pl.col("A").rolling_std(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_std │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.0         │
│ 3.0 ┆ 1.0         │
│ 4.0 ┆ 1.0         │
│ 5.0 ┆ 1.0         │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_std_by(
    by: IntoExpr,
    window_size: timedelta | str_,
    *,
    min_samples: int = 1,
    closed: ClosedInterval = 'right',
    ddof: int = 1,
) → Expr

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

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

Для столбца by <t_0, t_1, ..., t_n> значение closed="right" (по умолчанию) означает, что окна будут следующими:

(t_0 - window_size, t_0]
(t_1 - window_size, t_1]
…
(t_n - window_size, t_n]

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памяти

Параметры:

by

window_size

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

min_samples

Количество значений в окне, которые должны быть не-null, прежде чем будет вычислен результат.

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

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

ddof

«Поправка на число степеней свободы»: делитель для окна длины N равен N - ddof

Примечания

Примеры

Создание DataFrame со столбцом datetime и столбцом с номерами строк

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Вычисление скользящего стандартного отклонения с временными окнами, закрытыми справа (по умолчанию)

>>> df_temporal.with_columns(
...     rolling_row_std=pl.col("index").rolling_std_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_std │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ f64             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ null            │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.707107        │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 0.707107        │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 0.707107        │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 0.707107        │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 0.707107        │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 0.707107        │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 0.707107        │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 0.707107        │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 0.707107        │
└───────┴─────────────────────┴─────────────────┘

Вычисление скользящего стандартного отклонения с окнами, закрытыми с обеих сторон

>>> df_temporal.with_columns(
...     rolling_row_std=pl.col("index").rolling_std_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_std │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ f64             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ null            │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.707107        │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.0             │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 1.0             │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 1.0             │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 1.0             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 1.0             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 1.0             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 1.0             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 1.0             │
└───────┴─────────────────────┴─────────────────┘

rolling_sum(
    window_size: int,
    weights: list_[float] | None = None,
    *,
    min_samples: int | None = None,
    center: bool = False,
) → Expr

Вычислить скользящую сумму (скользящую сумму) значений этого массива.

Окно для заданной строки включает саму строку и window_size - 1 предшествующих ей элементов.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

window_size: Длина окна в количестве элементов.
weights: Необязательный срез той же длины, что и окно, элементы которого поэлементно умножаются на значения в окне.
min_samples: Количество значений в окне, которые должны быть не-null, прежде чем будет вычислен результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Разместить метки в центре окна.

Примечания

Примеры

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_sum=pl.col("A").rolling_sum(window_size=2),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_sum │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 3.0         │
│ 3.0 ┆ 5.0         │
│ 4.0 ┆ 7.0         │
│ 5.0 ┆ 9.0         │
│ 6.0 ┆ 11.0        │
└─────┴─────────────┘

Задание весов для умножения на значения в окне:

>>> df.with_columns(
...     rolling_sum=pl.col("A").rolling_sum(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_sum │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.75        │
│ 3.0 ┆ 2.75        │
│ 4.0 ┆ 3.75        │
│ 5.0 ┆ 4.75        │
│ 6.0 ┆ 5.75        │
└─────┴─────────────┘

Центрирование значений в окне

>>> df.with_columns(
...     rolling_sum=pl.col("A").rolling_sum(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_sum │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 6.0         │
│ 3.0 ┆ 9.0         │
│ 4.0 ┆ 12.0        │
│ 5.0 ┆ 15.0        │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_sum_by(
    by: IntoExpr,
    window_size: timedelta | str_,
    *,
    min_samples: int = 0,
    closed: ClosedInterval = 'right',
) → Expr

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

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

Для столбца by <t_0, t_1, ..., t_n> значение closed="right" (по умолчанию) означает, что окна будут следующими:

(t_0 - window_size, t_0]
(t_1 - window_size, t_1]
…
(t_n - window_size, t_n]

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памяти

Параметры:

window_size

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

min_samples

Количество значений в окне, которые должны быть не-null, прежде чем будет вычислен результат.

by

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

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

Примечания

Примеры

Создание DataFrame со столбцом datetime и столбцом с номерами строк

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Вычисление скользящей суммы с временными окнами, закрытыми справа (по умолчанию)

>>> df_temporal.with_columns(
...     rolling_row_sum=pl.col("index").rolling_sum_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_sum │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 1               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 3               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 5               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 7               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 39              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 41              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 43              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 45              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 47              │
└───────┴─────────────────────┴─────────────────┘

Вычисление скользящей суммы с окнами, закрытыми с обеих сторон

>>> df_temporal.with_columns(
...     rolling_row_sum=pl.col("index").rolling_sum_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_sum │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ u32             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ 0               │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 1               │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 3               │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 6               │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 9               │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 57              │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 60              │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 63              │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 66              │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 69              │
└───────┴─────────────────────┴─────────────────┘

rolling_var(
    window_size: int,
    weights: list_[float] | None = None,
    *,
    min_samples: int | None = None,
    center: bool = False,
    ddof: int = 1,
) → Expr

Вычислить скользящую дисперсию.

По массиву проходит окно длины window_size. Значения в этом окне могут быть умножены на веса, заданные вектором weights. Полученные значения агрегируются для вычисления дисперсии. Веса нормализуются так, чтобы их сумма равнялась 1.

Окно для заданной строки включает саму строку и window_size - 1 предшествующих ей элементов.

движок:В памяти

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

Параметры:

window_size: Длина окна в количестве элементов.
weights: Необязательный срез той же длины, что и окно. После нормализации до суммы 1 его элементы поэлементно умножаются на значения в окне.
min_samples: Количество значений в окне, которые должны быть не-null, прежде чем будет вычислен результат. Если задано None (по умолчанию), оно будет равно window_size.
center: Разместить метки в центре окна.
ddof: «Поправка на число степеней свободы»: делитель для окна длины N равен N - ddof

Примечания

Примеры

>>> df = pl.DataFrame({"A": [1.0, 2.0, 3.0, 4.0, 5.0, 6.0]})
>>> df.with_columns(
...     rolling_var=pl.col("A").rolling_var(window_size=2),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_var │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.5         │
│ 3.0 ┆ 0.5         │
│ 4.0 ┆ 0.5         │
│ 5.0 ┆ 0.5         │
│ 6.0 ┆ 0.5         │
└─────┴─────────────┘

Задание весов для умножения на значения в окне:

>>> df.with_columns(
...     rolling_var=pl.col("A").rolling_var(
...         window_size=2, weights=[0.25, 0.75]
...     ),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_var │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 0.1875      │
│ 3.0 ┆ 0.1875      │
│ 4.0 ┆ 0.1875      │
│ 5.0 ┆ 0.1875      │
│ 6.0 ┆ 0.1875      │
└─────┴─────────────┘

Центрирование значений в окне

>>> df.with_columns(
...     rolling_var=pl.col("A").rolling_var(window_size=3, center=True),
... )
shape: (6, 2)
┌─────┬─────────────┐
│ A   ┆ rolling_var │
│ --- ┆ ---         │
│ f64 ┆ f64         │
╞═════╪═════════════╡
│ 1.0 ┆ null        │
│ 2.0 ┆ 1.0         │
│ 3.0 ┆ 1.0         │
│ 4.0 ┆ 1.0         │
│ 5.0 ┆ 1.0         │
│ 6.0 ┆ null        │
└─────┴─────────────┘

rolling_var_by(
    by: IntoExpr,
    window_size: timedelta | str_,
    *,
    min_samples: int = 1,
    closed: ClosedInterval = 'right',
    ddof: int = 1,
) → Expr

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

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

Для столбца by <t_0, t_1, ..., t_n> значение closed="right" (по умолчанию) означает, что окна будут следующими:

(t_0 - window_size, t_0]
(t_1 - window_size, t_1]
…
(t_n - window_size, t_n]

Изменено в версии 1.21.0: Параметр min_periods переименован в min_samples.

движок:В памяти

Параметры:

by

window_size

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

min_samples

Количество значений в окне, которые должны быть не-null, прежде чем будет вычислен результат.

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

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

ddof

«Поправка на число степеней свободы»: делитель для окна длины N равен N - ddof

Примечания

Примеры

Создание DataFrame со столбцом datetime и столбцом с номерами строк

>>> from datetime import timedelta, datetime
>>> start = datetime(2001, 1, 1)
>>> stop = datetime(2001, 1, 2)
>>> df_temporal = pl.DataFrame(
...     {"date": pl.datetime_range(start, stop, "1h", eager=True)}
... ).with_row_index()
>>> df_temporal
shape: (25, 2)
┌───────┬─────────────────────┐
│ index ┆ date                │
│ ---   ┆ ---                 │
│ u32   ┆ datetime[μs]        │
╞═══════╪═════════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 │
│ 1     ┆ 2001-01-01 01:00:00 │
│ 2     ┆ 2001-01-01 02:00:00 │
│ 3     ┆ 2001-01-01 03:00:00 │
│ 4     ┆ 2001-01-01 04:00:00 │
│ …     ┆ …                   │
│ 20    ┆ 2001-01-01 20:00:00 │
│ 21    ┆ 2001-01-01 21:00:00 │
│ 22    ┆ 2001-01-01 22:00:00 │
│ 23    ┆ 2001-01-01 23:00:00 │
│ 24    ┆ 2001-01-02 00:00:00 │
└───────┴─────────────────────┘

Вычисление скользящей дисперсии с временными окнами, закрытыми справа (по умолчанию)

>>> df_temporal.with_columns(
...     rolling_row_var=pl.col("index").rolling_var_by("date", window_size="2h")
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_var │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ f64             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ null            │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5             │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 0.5             │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 0.5             │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 0.5             │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 0.5             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 0.5             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 0.5             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 0.5             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 0.5             │
└───────┴─────────────────────┴─────────────────┘

Вычисление скользящей дисперсии с окнами, закрытыми с обеих сторон

>>> df_temporal.with_columns(
...     rolling_row_var=pl.col("index").rolling_var_by(
...         "date", window_size="2h", closed="both"
...     )
... )
shape: (25, 3)
┌───────┬─────────────────────┬─────────────────┐
│ index ┆ date                ┆ rolling_row_var │
│ ---   ┆ ---                 ┆ ---             │
│ u32   ┆ datetime[μs]        ┆ f64             │
╞═══════╪═════════════════════╪═════════════════╡
│ 0     ┆ 2001-01-01 00:00:00 ┆ null            │
│ 1     ┆ 2001-01-01 01:00:00 ┆ 0.5             │
│ 2     ┆ 2001-01-01 02:00:00 ┆ 1.0             │
│ 3     ┆ 2001-01-01 03:00:00 ┆ 1.0             │
│ 4     ┆ 2001-01-01 04:00:00 ┆ 1.0             │
│ …     ┆ …                   ┆ …               │
│ 20    ┆ 2001-01-01 20:00:00 ┆ 1.0             │
│ 21    ┆ 2001-01-01 21:00:00 ┆ 1.0             │
│ 22    ┆ 2001-01-01 22:00:00 ┆ 1.0             │
│ 23    ┆ 2001-01-01 23:00:00 ┆ 1.0             │
│ 24    ┆ 2001-01-02 00:00:00 ┆ 1.0             │
└───────┴─────────────────────┴─────────────────┘

round(
    decimals: int = 0,
    mode: RoundMode = 'half_to_even',
) → Expr

Округлить базовые данные с плавающей точкой до decimals знаков.

движок:В памятиПотоковая обработкаРаспределённая обработка

Параметры:

decimals

Количество знаков после запятой для округления.

mode{‘half_to_even’, ‘half_away_from_zero’, ‘to_zero’}

Используемая стратегия округления. «Округлённое значение» — это значение, имеющее не более decimals знаков после запятой (например, целые числа при decimals=0, кратные 0.1 при decimals=1, кратные 0.01 при decimals=2 и так далее).

Стратегии, начинающиеся с half_, округляют все значения до ближайшего округлённого значения и используют стратегию только для разрешения равенства, когда значение находится ровно посередине между двумя округлёнными значениями (например, 0.5 при decimals=0, 0.05 при decimals=1). Другие стратегии округления явно определяют, какое округлённое значение выбрать, и применяются всегда, а не только при равенстве.

half_to_even (по умолчанию)

Округлить до ближайшего значения; при равенстве выбрать ближайшее чётное значение. Например, 0.5 округляется до 0, 1.5 — до 2, 2.5 — до 2. Также называется «банковским округлением»; оно используется по умолчанию, поскольку помогает минимизировать накопление погрешности округления.
half_away_from_zero

Округлить до ближайшего значения; при равенстве округлить от нуля. Например, 0.5 округляется до 1, -0.5 — до -1, 2.5 — до 3. Также называется «коммерческим округлением».
to_zero

Всегда округлять (усекать) в сторону нуля, отбрасывая дробную часть после decimals. Например, 0.9 округляется до 0, -0.9 — до 0, 1.29 — до 1.2 (при decimals=1). Эквивалентно методу truncate().

См. также

ceil: Округлить вверх до ближайшего целого числа.
floor: Округлить вниз до ближайшего целого числа.
round_sig_figs: Округлить до заданного количества значащих цифр.
truncate: Усечь до заданного количества знаков после запятой.

Примеры

>>> df = pl.DataFrame({"a": [0.33, 0.52, 1.02, 1.17]})
>>> df.select(pl.col("a").round(1))
shape: (4, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.3 │
│ 0.5 │
│ 1.0 │
│ 1.2 │
└─────┘

>>> df = pl.DataFrame(
...     {
...         "f64": [-3.5, -2.5, -1.5, -0.5, 0.5, 1.5, 2.5, 3.5],
...         "d": ["-3.5", "-2.5", "-1.5", "-0.5", "0.5", "1.5", "2.5", "3.5"],
...     },
...     schema_overrides={"d": pl.Decimal(scale=1)},
... )
>>> df.with_columns(
...     pl.all().round(mode="half_away_from_zero").name.suffix("_away"),
...     pl.all().round(mode="half_to_even").name.suffix("_to_even"),
... )
shape: (8, 6)
┌──────┬───────────────┬──────────┬───────────────┬─────────────┬───────────────┐
│ f64  ┆ d             ┆ f64_away ┆ d_away        ┆ f64_to_even ┆ d_to_even     │
│ ---  ┆ ---           ┆ ---      ┆ ---           ┆ ---         ┆ ---           │
│ f64  ┆ decimal[38,1] ┆ f64      ┆ decimal[38,1] ┆ f64         ┆ decimal[38,1] │
╞══════╪═══════════════╪══════════╪═══════════════╪═════════════╪═══════════════╡
│ -3.5 ┆ -3.5          ┆ -4.0     ┆ -4.0          ┆ -4.0        ┆ -4.0          │
│ -2.5 ┆ -2.5          ┆ -3.0     ┆ -3.0          ┆ -2.0        ┆ -2.0          │
│ -1.5 ┆ -1.5          ┆ -2.0     ┆ -2.0          ┆ -2.0        ┆ -2.0          │
│ -0.5 ┆ -0.5          ┆ -1.0     ┆ -1.0          ┆ -0.0        ┆ 0.0           │
│ 0.5  ┆ 0.5           ┆ 1.0      ┆ 1.0           ┆ 0.0         ┆ 0.0           │
│ 1.5  ┆ 1.5           ┆ 2.0      ┆ 2.0           ┆ 2.0         ┆ 2.0           │
│ 2.5  ┆ 2.5           ┆ 3.0      ┆ 3.0           ┆ 2.0         ┆ 2.0           │
│ 3.5  ┆ 3.5           ┆ 4.0      ┆ 4.0           ┆ 4.0         ┆ 4.0           │
└──────┴───────────────┴──────────┴───────────────┴─────────────┴───────────────┘

round_sig_figs(
    digits: int,
) → Expr

Округлить до заданного количества значащих цифр.

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

Параметры:

digits: Количество значащих цифр для округления.

См. также

ceil: Округлить вверх до ближайшего целого числа.
floor: Округлить вниз до ближайшего целого числа.
round: Округлить до заданного количества десятичных знаков.
truncate: Усечь до заданного количества десятичных знаков.

Примеры

>>> df = pl.DataFrame({"a": [0.01234, 3.333, 1234.0]})
>>> df.with_columns(pl.col("a").round_sig_figs(2).alias("round_sig_figs"))
shape: (3, 2)
┌─────────┬────────────────┐
│ a       ┆ round_sig_figs │
│ ---     ┆ ---            │
│ f64     ┆ f64            │
╞═════════╪════════════════╡
│ 0.01234 ┆ 0.012          │
│ 3.333   ┆ 3.3            │
│ 1234.0  ┆ 1200.0         │
└─────────┴────────────────┘

sample(
    n: int | IntoExprColumn | None = None,
    *,
    fraction: float | IntoExprColumn | None = None,
    with_replacement: bool = False,
    shuffle: bool | None = None,
    seed: int | None = None,
) → Expr

Выбрать случайную выборку из этого выражения.

движок:В памяти

Параметры:

n: Количество элементов для возврата. Нельзя использовать вместе с fraction. По умолчанию равно 1, если fraction равно None.
fraction: Доля элементов для возврата. Нельзя использовать вместе с n.
with_replacement: Разрешить выбирать значения более одного раза.
shuffle: Определяет порядок выбранных элементов. Если значение True, выбранные элементы явно перемешиваются. Если False, относительный порядок выбранных элементов сохраняется (то есть они появляются в том же порядке, что и во входных данных). Если значение None (по умолчанию), порядок не гарантируется; используется наиболее производительный алгоритм.
seed: Начальное значение для генератора случайных чисел. Если задано None (по умолчанию), для каждой операции выборки генерируется случайное начальное значение.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(
...     pl.col("a").sample(
...         fraction=1.0, with_replacement=True, shuffle=False, seed=1
...     )
... )
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 3   │
│ 3   │
│ 1   │
└─────┘

search_sorted(
    element: IntoExpr | np.ndarray[Any,
    Any],
    side: SearchSortedSide = 'any',
    *,
    descending: bool = False,
) → Expr

Найти индексы, по которым следует вставить элементы для сохранения порядка.

\[a[i-1] < v <= a[i]\]

движок:В памяти

Параметры:

element: Выражение или скалярное значение.
side{‘any’, ‘left’, ‘right’}: Если значение равно ‘any’, возвращается индекс первого найденного подходящего места. Если значение равно ‘left’, возвращается индекс самого левого найденного подходящего места. Если значение равно ‘right’, возвращается индекс самого правого найденного подходящего места.
descending: Логическое значение, указывающее, отсортированы ли значения по убыванию (в любом случае они должны быть отсортированы).

Примеры

>>> df = pl.DataFrame(
...     {
...         "values": [1, 2, 3, 5],
...     }
... )
>>> df.select(
...     [
...         pl.col("values").search_sorted(0).alias("zero"),
...         pl.col("values").search_sorted(3).alias("three"),
...         pl.col("values").search_sorted(6).alias("six"),
...     ]
... )
shape: (1, 3)
┌──────┬───────┬─────┐
│ zero ┆ three ┆ six │
│ ---  ┆ ---   ┆ --- │
│ u32  ┆ u32   ┆ u32 │
╞══════╪═══════╪═════╡
│ 0    ┆ 2     ┆ 4   │
└──────┴───────┴─────┘

set_sorted(
    *,
    descending: bool = False,
    nulls_last: bool = False,
) → Expr

Помечает выражение как «отсортированное».

Позволяет последующему коду использовать быстрые пути для отсортированных массивов. Рекомендуется также указать, является ли nulls_last True или False, поскольку это позволяет использовать множество внутренних оптимизаций.

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

Параметры:

descending: Указывает, отсортирован ли порядок Series по убыванию.
nulls_last: Указывает, находятся ли значения null в конце.

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

Это может привести к неправильным результатам, если данные НЕ отсортированы! Используйте с осторожностью.

Примеры

>>> df = pl.DataFrame({"values": [1, 2, 3]})
>>> df.select(pl.col("values").set_sorted().max())
shape: (1, 1)
┌────────┐
│ values │
│ ---    │
│ i64    │
╞════════╡
│ 3      │
└────────┘

shift(
    n: int | IntoExprColumn = 1,
    *,
    fill_value: IntoExpr | None = None,
) → Expr

Сдвинуть значения на заданное количество индексов.

движок:В памятиПотоковая обработка

Параметры:

n: Количество индексов для сдвига вперёд. Если передано отрицательное значение, значения сдвигаются в противоположном направлении.
fill_value: Заполнить получившиеся значения null этим скалярным значением.

См. также

fill_null

Примечания

Этот метод аналогичен операции LAG в SQL, если значение n положительное. При отрицательном значении n он аналогичен LEAD.

Примеры

По умолчанию значения сдвигаются вперёд на один индекс.

>>> df = pl.DataFrame({"a": [1, 2, 3, 4]})
>>> df.with_columns(shift=pl.col("a").shift())
shape: (4, 2)
┌─────┬───────┐
│ a   ┆ shift │
│ --- ┆ ---   │
│ i64 ┆ i64   │
╞═════╪═══════╡
│ 1   ┆ null  │
│ 2   ┆ 1     │
│ 3   ┆ 2     │
│ 4   ┆ 3     │
└─────┴───────┘

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

>>> df.with_columns(shift=pl.col("a").shift(-2))
shape: (4, 2)
┌─────┬───────┐
│ a   ┆ shift │
│ --- ┆ ---   │
│ i64 ┆ i64   │
╞═════╪═══════╡
│ 1   ┆ 3     │
│ 2   ┆ 4     │
│ 3   ┆ null  │
│ 4   ┆ null  │
└─────┴───────┘

Укажите fill_value, чтобы заполнить получившиеся значения null.

>>> df.with_columns(shift=pl.col("a").shift(-2, fill_value=100))
shape: (4, 2)
┌─────┬───────┐
│ a   ┆ shift │
│ --- ┆ ---   │
│ i64 ┆ i64   │
╞═════╪═══════╡
│ 1   ┆ 3     │
│ 2   ┆ 4     │
│ 3   ┆ 100   │
│ 4   ┆ 100   │
└─────┴───────┘

shrink_dtype() → Expr

Сократить числовые столбцы до минимально необходимого типа данных.

Сократить до типа данных, необходимого для хранения экстремальных значений этого [Series]. Это можно использовать для снижения нагрузки на память.

Изменено в версии 1.33.0: Устарел и стал пустой операцией. Во время ленивого выполнения эта операция не соответствует модели данных Polars, поскольку тип данных результата нельзя определить без проверки данных.

Вместо этого используйте Series.shrink_dtype.

Примеры

>>> pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": [1, 2, 2 << 32],
...         "c": [-1, 2, 1 << 30],
...         "d": [-112, 2, 112],
...         "e": [-112, 2, 129],
...         "f": ["a", "b", "c"],
...         "g": [0.1, 1.32, 0.12],
...         "h": [True, None, False],
...     }
... ).select(pl.all().shrink_dtype())  
shape: (3, 8)
┌─────┬────────────┬────────────┬──────┬──────┬─────┬──────┬───────┐
│ a   ┆ b          ┆ c          ┆ d    ┆ e    ┆ f   ┆ g    ┆ h     │
│ --- ┆ ---        ┆ ---        ┆ ---  ┆ ---  ┆ --- ┆ ---  ┆ ---   │
│ i8  ┆ i64        ┆ i32        ┆ i8   ┆ i16  ┆ str ┆ f32  ┆ bool  │
╞═════╪════════════╪════════════╪══════╪══════╪═════╪══════╪═══════╡
│ 1   ┆ 1          ┆ -1         ┆ -112 ┆ -112 ┆ a   ┆ 0.1  ┆ true  │
│ 2   ┆ 2          ┆ 2          ┆ 2    ┆ 2    ┆ b   ┆ 1.32 ┆ null  │
│ 3   ┆ 8589934592 ┆ 1073741824 ┆ 112  ┆ 129  ┆ c   ┆ 0.12 ┆ false │
└─────┴────────────┴────────────┴──────┴──────┴─────┴──────┴───────┘

shuffle(
    seed: int | None = None,
) → Expr

Перемешать содержимое этого выражения.

Обратите внимание: перемешивание выполняется независимо от любых других столбцов или выражений. Если нужно сохранить соответствие строк, используйте df.sample(shuffle=True)

движок:В памяти

Параметры:

seed: Начальное значение для генератора случайных чисел. Если задано None (по умолчанию), при каждом вызове перемешивания генерируется случайное начальное значение.

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> df.select(pl.col("a").shuffle(seed=1))
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
│ 3   │
│ 1   │
└─────┘

sign() → Expr

Вычислить поэлементную функцию знака для числовых типов.

Возвращаемое значение вычисляется следующим образом:

-1, если x < 0.
1, если x > 0.
В остальных случаях x (обычно 0, но может быть NaN, если таким является входное значение).

Значения null сохраняются без изменений, тип данных входного значения сохраняется.

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

Примеры

>>> df = pl.DataFrame({"a": [-9.0, -0.0, 0.0, 4.0, float("nan"), None]})
>>> df.select(pl.col.a.sign())
shape: (6, 1)
┌──────┐
│ a    │
│ ---  │
│ f64  │
╞══════╡
│ -1.0 │
│ -0.0 │
│ 0.0  │
│ 1.0  │
│ NaN  │
│ null │
└──────┘

sin() → Expr

Вычислить поэлементное значение синуса.

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

Возвращает:

Expr: Выражение с типом данных Float64.

Примечания

Аргумент должен быть задан в радианах. Чтобы преобразовать градусы в радианы, вызовите .radians().

Примеры

>>> from math import pi
>>> df = pl.DataFrame({"a": [0.0, pi / 2]})
>>> df.select(pl.col("a").sin())
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
│ 1.0 │
└─────┘
>>> df = pl.DataFrame({"a": [0.0, 90]})
>>> df.select(pl.col("a").radians().sin())
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
│ 1.0 │
└─────┘

sinh() → Expr

Вычислить поэлементное значение гиперболического синуса.

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

Возвращает:

Expr: Выражение с типом данных Float64.

Примеры

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").sinh())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 1.175201 │
└──────────┘

skew(
    *,
    bias: bool = True,
) → Expr

Вычислить выборочную асимметрию набора данных.

Для нормально распределённых данных асимметрия должна быть близка к нулю. Для непрерывных унимодальных распределений значение асимметрии больше нуля означает, что в правом хвосте распределения сосредоточено больше веса. Функцию skewtest можно использовать, чтобы с точки зрения статистики определить, достаточно ли близко значение асимметрии к нулю.

Дополнительные сведения см. в scipy.stats.

движок:В памятиПотоковая обработка

Параметры:

biasbool, optional: Если значение False, вычисления корректируются с учётом статистического смещения.

Примечания

Выборочная асимметрия вычисляется как коэффициент асимметрии Фишера—Пирсона, то есть

\[g_1=\frac{m_3}{m_2^{3/2}}\]

где

\[m_i=\frac{1}{N}\sum_{n=1}^N(x[n]-\bar{x})^i\]

— смещённый выборочный центральный момент порядка $i\texttt{th}$, а $\bar{x}$ — выборочное среднее. Если bias равно False, вычисления корректируются с учётом смещения, а вычисляемое значение представляет собой скорректированный стандартизованный моментный коэффициент Фишера—Пирсона, то есть

\[G_1 = \frac{k_3}{k_2^{3/2}} = \frac{\sqrt{N(N-1)}}{N-2}\frac{m_3}{m_2^{3/2}}\]

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3, 2, 1]})
>>> df.select(pl.col("a").skew())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.343622 │
└──────────┘

slice(
    offset: int | Expr,
    length: int | Expr | None = None,
) → Expr

Получить срез этого выражения.

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

Параметры:

offset: Начальный индекс. Поддерживается отрицательная индексация.
length: Длина среза. Если задано None, будут выбраны все строки, начиная с указанного смещения.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [8, 9, 10, 11],
...         "b": [None, 4, 4, 4],
...     }
... )
>>> df.select(pl.all().slice(1, 2))
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 9   ┆ 4   │
│ 10  ┆ 4   │
└─────┴─────┘

sort(
    *,
    descending: bool = False,
    nulls_last: bool = False,
) → Expr

Отсортировать этот столбец.

В контексте проекции/выбора сортируется весь столбец. В контексте группировки сортируются группы.

движок:В памятиЧастичная потоковая обработка

Параметры:

descending: Сортировать по убыванию.
nulls_last: Поместить значения null в конец.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, None, 3, 2],
...     }
... )
>>> df.select(pl.col("a").sort())
shape: (4, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ null │
│ 1    │
│ 2    │
│ 3    │
└──────┘
>>> df.select(pl.col("a").sort(descending=True))
shape: (4, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ null │
│ 3    │
│ 2    │
│ 1    │
└──────┘
>>> df.select(pl.col("a").sort(nulls_last=True))
shape: (4, 1)
┌──────┐
│ a    │
│ ---  │
│ i64  │
╞══════╡
│ 1    │
│ 2    │
│ 3    │
│ null │
└──────┘

При сортировке в контексте группировки сортируются группы.

>>> df = pl.DataFrame(
...     {
...         "group": ["one", "one", "one", "two", "two", "two"],
...         "value": [1, 98, 2, 3, 99, 4],
...     }
... )
>>> df.group_by("group").agg(pl.col("value").sort())  
shape: (2, 2)
┌───────┬────────────┐
│ group ┆ value      │
│ ---   ┆ ---        │
│ str   ┆ list[i64]  │
╞═══════╪════════════╡
│ two   ┆ [3, 4, 99] │
│ one   ┆ [1, 2, 98] │
└───────┴────────────┘

sort_by(
    by: IntoExpr | Iterable[IntoExpr],
    *more_by: IntoExpr,
    descending: bool | Sequence[bool] = False,
    nulls_last: bool | Sequence[bool] = False,
    multithreaded: bool = True,
    maintain_order: bool = False,
) → Expr

Отсортировать этот столбец в соответствии с порядком других столбцов.

движок:В памятиЧастичная потоковая обработка

В контексте проекции/выбора сортируется весь столбец. В контексте группировки сортируются группы.

Параметры:

by: Столбец (столбцы), по которому выполняется сортировка. Принимает выражение. Строки интерпретируются как имена столбцов.
*more_by: Дополнительные столбцы для сортировки, задаваемые позиционными аргументами.
descending: Сортировать по убыванию. При сортировке по нескольким столбцам можно задать значение для каждого столбца, передав последовательность логических значений.
nulls_last: Поместить значения null в конец; можно задать одно логическое значение для всех столбцов или последовательность логических значений для каждого столбца.
multithreaded: Выполнять сортировку в несколько потоков.
maintain_order: Сохранять ли порядок элементов с одинаковыми значениями.

Примеры

Передайте имя одного столбца, чтобы сортировать по нему.

>>> df = pl.DataFrame(
...     {
...         "group": ["a", "a", "b", "b"],
...         "value1": [1, 3, 4, 2],
...         "value2": [8, 7, 6, 5],
...     }
... )
>>> df.select(pl.col("group").sort_by("value1"))
shape: (4, 1)
┌───────┐
│ group │
│ ---   │
│ str   │
╞═══════╡
│ a     │
│ b     │
│ a     │
│ b     │
└───────┘

Также поддерживается сортировка по выражениям.

>>> df.select(pl.col("group").sort_by(pl.col("value1") + pl.col("value2")))
shape: (4, 1)
┌───────┐
│ group │
│ ---   │
│ str   │
╞═══════╡
│ b     │
│ a     │
│ a     │
│ b     │
└───────┘

Чтобы сортировать по нескольким столбцам, передайте список столбцов.

>>> df.select(pl.col("group").sort_by(["value1", "value2"], descending=True))
shape: (4, 1)
┌───────┐
│ group │
│ ---   │
│ str   │
╞═══════╡
│ b     │
│ a     │
│ b     │
│ a     │
└───────┘

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

>>> df.select(pl.col("group").sort_by("value1", "value2"))
shape: (4, 1)
┌───────┐
│ group │
│ ---   │
│ str   │
╞═══════╡
│ a     │
│ b     │
│ a     │
│ b     │
└───────┘

При сортировке в контексте группировки сортируются группы.

>>> df.group_by("group").agg(
...     pl.col("value1").sort_by("value2")
... )  
shape: (2, 2)
┌───────┬───────────┐
│ group ┆ value1    │
│ ---   ┆ ---       │
│ str   ┆ list[i64] │
╞═══════╪═══════════╡
│ a     ┆ [3, 1]    │
│ b     ┆ [2, 4]    │
└───────┴───────────┘

Выбрать одну строку из каждой группы, в которой столбец принимает минимальное значение в этой группе.

>>> df.group_by("group").agg(
...     pl.all().sort_by("value2").first()
... )  
shape: (2, 3)
┌───────┬────────┬────────┐
│ group ┆ value1 ┆ value2 |
│ ---   ┆ ---    ┆ ---    │
│ str   ┆ i64    ┆ i64    |
╞═══════╪════════╪════════╡
│ a     ┆ 3      ┆ 7      |
│ b     ┆ 2      ┆ 5      |
└───────┴────────┴────────┘

sqrt() → Expr

Вычислить квадратный корень элементов.

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

Примеры

>>> df = pl.DataFrame({"values": [1.0, 2.0, 4.0]})
>>> df.select(pl.col("values").sqrt())
shape: (3, 1)
┌──────────┐
│ values   │
│ ---      │
│ f64      │
╞══════════╡
│ 1.0      │
│ 1.414214 │
│ 2.0      │
└──────────┘

std(
    ddof: int = 1,
) → Expr

Вычислить стандартное отклонение.

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

Параметры:

ddof: «Число степеней свободы»: делитель, используемый в вычислениях, равен N - ddof, где N — количество элементов. По умолчанию ddof равен 1.

Примеры

>>> df = pl.DataFrame({"a": [-1, 0, 1]})
>>> df.select(pl.col("a").std())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
└─────┘

sub(
    other: Any,
) → Expr

Эквивалент метода для оператора вычитания expr - other.

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

Параметры:

other: Числовой литерал или значение выражения.

Примеры

>>> df = pl.DataFrame({"x": [0, 1, 2, 3, 4]})
>>> df.with_columns(
...     pl.col("x").sub(2).alias("x-2"),
...     pl.col("x").sub(pl.col("x").cum_sum()).alias("x-expr"),
... )
shape: (5, 3)
┌─────┬─────┬────────┐
│ x   ┆ x-2 ┆ x-expr │
│ --- ┆ --- ┆ ---    │
│ i64 ┆ i64 ┆ i64    │
╞═════╪═════╪════════╡
│ 0   ┆ -2  ┆ 0      │
│ 1   ┆ -1  ┆ 0      │
│ 2   ┆ 0   ┆ -1     │
│ 3   ┆ 1   ┆ -3     │
│ 4   ┆ 2   ┆ -6     │
└─────┴─────┴────────┘

sum() → Expr

Получить сумму.

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

Примечания

Типы данных из {Int8, UInt8, Int16, UInt16} перед суммированием преобразуются в Int64 во избежание переполнения.
Если нет ни одного значения, отличного от null, результатом будет 0. Если нужно, чтобы пустые суммы возвращали None, вместо expr.sum() можно использовать pl.when(expr.count()>0).then(expr.sum()).

Примеры

>>> df = pl.DataFrame({"a": [-1, 0, 1]})
>>> df.select(pl.col("a").sum())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│  0  │
└─────┘

tail(
    n: int | Expr = 10,
) → Expr

Получить последние n строк.

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

Параметры:

n: Количество строк для возврата.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5, 6, 7]})
>>> df.select(pl.col("foo").tail(3))
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 5   │
│ 6   │
│ 7   │
└─────┘

tan() → Expr

Вычислить поэлементное значение тангенса.

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

Возвращает:

Expr: Выражение с типом данных Float64.

Примечания

Аргумент должен быть задан в радианах. Чтобы преобразовать градусы в радианы, вызовите .radians().

Примеры

>>> from math import pi
>>> df = pl.DataFrame({"a": [0.0, pi / 4]})
>>> df.select(pl.col("a").tan())
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
│ 1.0 │
└─────┘
>>> df = pl.DataFrame({"a": [0.0, 45]})
>>> df.select(pl.col("a").radians().tan())
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 0.0 │
│ 1.0 │
└─────┘

tanh() → Expr

Вычислить поэлементное значение гиперболического тангенса.

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

Возвращает:

Expr: Выражение с типом данных Float64.

Примеры

>>> df = pl.DataFrame({"a": [1.0]})
>>> df.select(pl.col("a").tanh())
shape: (1, 1)
┌──────────┐
│ a        │
│ ---      │
│ f64      │
╞══════════╡
│ 0.761594 │
└──────────┘

to_physical() → Expr

Преобразовать к физическому представлению логического типа данных.

polars.datatypes.Date() -> polars.datatypes.Int32()
polars.datatypes.Datetime() -> polars.datatypes.Int64()
polars.datatypes.Time() -> polars.datatypes.Int64()
polars.datatypes.Duration() -> polars.datatypes.Int64()
polars.datatypes.Categorical() -> polars.datatypes.UInt32()
List(inner) -> List(physical of inner)
Array(inner) -> Struct(physical of inner)
Struct(fields) -> Array(physical of fields)

Другие типы данных остаются без изменений.

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

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

Физические представления являются деталью реализации, и их стабильность не гарантируется.

Примеры

Воспроизведение работы функции pandas pd.factorize.

>>> pl.DataFrame({"vals": ["a", "x", None, "a"]}).with_columns(
...     pl.col("vals").cast(pl.Categorical),
...     pl.col("vals")
...     .cast(pl.Categorical)
...     .to_physical()
...     .alias("vals_physical"),
... )
shape: (4, 2)
┌──────┬───────────────┐
│ vals ┆ vals_physical │
│ ---  ┆ ---           │
│ cat  ┆ u32           │
╞══════╪═══════════════╡
│ a    ┆ 0             │
│ x    ┆ 1             │
│ null ┆ null          │
│ a    ┆ 0             │
└──────┴───────────────┘

top_k(
    k: int | IntoExprColumn = 5,
) → Expr

Вернуть k наибольших элементов.

Ненулевые элементы всегда имеют приоритет над значениями null. Порядок результата не гарантируется; если нужно отсортировать результат, вызовите после этой функции sort().

Временная сложность:

\[O(n)\]

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

Параметры:

k: Количество элементов для возврата.

См. также

top_k_by
bottom_k
bottom_k_by

Примеры

Получить 5 наибольших значений в серии.

>>> df = pl.DataFrame({"value": [1, 98, 2, 3, 99, 4]})
>>> df.select(
...     pl.col("value").top_k().alias("top_k"),
...     pl.col("value").bottom_k().alias("bottom_k"),
... )
shape: (5, 2)
┌───────┬──────────┐
│ top_k ┆ bottom_k │
│ ---   ┆ ---      │
│ i64   ┆ i64      │
╞═══════╪══════════╡
│ 4     ┆ 1        │
│ 98    ┆ 98       │
│ 2     ┆ 2        │
│ 3     ┆ 3        │
│ 99    ┆ 4        │
└───────┴──────────┘

top_k_by(
    by: IntoExpr | Iterable[IntoExpr],
    k: int | IntoExprColumn = 5,
    *,
    reverse: bool | Sequence[bool] = False,
) → Expr

Вернуть элементы, соответствующие k наибольшим элементам столбца (столбцов) by.

Ненулевые элементы всегда имеют приоритет над значениями null независимо от значения reverse. Порядок результата не гарантируется; если нужно отсортировать результат, вызовите после этой функции sort().

Временная сложность:

\[O(n \log{n})\]

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

Изменено в версии 1.0.0: Параметр descending переименован в reverse.

Параметры:

by: Столбец (столбцы), используемый для определения наибольших элементов. Принимает выражение. Строки интерпретируются как имена столбцов.
k: Количество элементов для возврата.
reverse: Рассматривать k наименьших элементов столбца (столбцов) by (вместо k наибольших). Значение можно задать отдельно для каждого столбца, передав последовательность логических значений.

См. также

top_k
bottom_k
bottom_k_by

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 4, 5, 6],
...         "b": [6, 5, 4, 3, 2, 1],
...         "c": ["Apple", "Orange", "Apple", "Apple", "Banana", "Banana"],
...     }
... )
>>> df
shape: (6, 3)
┌─────┬─────┬────────┐
│ a   ┆ b   ┆ c      │
│ --- ┆ --- ┆ ---    │
│ i64 ┆ i64 ┆ str    │
╞═════╪═════╪════════╡
│ 1   ┆ 6   ┆ Apple  │
│ 2   ┆ 5   ┆ Orange │
│ 3   ┆ 4   ┆ Apple  │
│ 4   ┆ 3   ┆ Apple  │
│ 5   ┆ 2   ┆ Banana │
│ 6   ┆ 1   ┆ Banana │
└─────┴─────┴────────┘

Получить 2 верхние строки по столбцу a или b.

>>> df.select(
...     pl.all().top_k_by("a", 2).name.suffix("_top_by_a"),
...     pl.all().top_k_by("b", 2).name.suffix("_top_by_b"),
... )
shape: (2, 6)
┌────────────┬────────────┬────────────┬────────────┬────────────┬────────────┐
│ a_top_by_a ┆ b_top_by_a ┆ c_top_by_a ┆ a_top_by_b ┆ b_top_by_b ┆ c_top_by_b │
│ ---        ┆ ---        ┆ ---        ┆ ---        ┆ ---        ┆ ---        │
│ i64        ┆ i64        ┆ str        ┆ i64        ┆ i64        ┆ str        │
╞════════════╪════════════╪════════════╪════════════╪════════════╪════════════╡
│ 6          ┆ 1          ┆ Banana     ┆ 1          ┆ 6          ┆ Apple      │
│ 5          ┆ 2          ┆ Banana     ┆ 2          ┆ 5          ┆ Orange     │
└────────────┴────────────┴────────────┴────────────┴────────────┴────────────┘

Получить 2 верхние строки по нескольким столбцам с заданным порядком.

>>> df.select(
...     pl.all()
...     .top_k_by(["c", "a"], 2, reverse=[False, True])
...     .name.suffix("_by_ca"),
...     pl.all()
...     .top_k_by(["c", "b"], 2, reverse=[False, True])
...     .name.suffix("_by_cb"),
... )
shape: (2, 6)
┌─────────┬─────────┬─────────┬─────────┬─────────┬─────────┐
│ a_by_ca ┆ b_by_ca ┆ c_by_ca ┆ a_by_cb ┆ b_by_cb ┆ c_by_cb │
│ ---     ┆ ---     ┆ ---     ┆ ---     ┆ ---     ┆ ---     │
│ i64     ┆ i64     ┆ str     ┆ i64     ┆ i64     ┆ str     │
╞═════════╪═════════╪═════════╪═════════╪═════════╪═════════╡
│ 2       ┆ 5       ┆ Orange  ┆ 2       ┆ 5       ┆ Orange  │
│ 5       ┆ 2       ┆ Banana  ┆ 6       ┆ 1       ┆ Banana  │
└─────────┴─────────┴─────────┴─────────┴─────────┴─────────┘

Получить 2 верхние строки по столбцу a в каждой группе.

>>> (
...     df.group_by("c", maintain_order=True)
...     .agg(pl.all().top_k_by("a", 2))
...     .explode(pl.all().exclude("c"))
... )
shape: (5, 3)
┌────────┬─────┬─────┐
│ c      ┆ a   ┆ b   │
│ ---    ┆ --- ┆ --- │
│ str    ┆ i64 ┆ i64 │
╞════════╪═════╪═════╡
│ Apple  ┆ 4   ┆ 3   │
│ Apple  ┆ 3   ┆ 4   │
│ Orange ┆ 2   ┆ 5   │
│ Banana ┆ 6   ┆ 1   │
│ Banana ┆ 5   ┆ 2   │
└────────┴─────┴─────┘

truediv(
    other: Any,
) → Expr

Эквивалент метода для оператора деления с плавающей точкой expr / other.

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

Параметры:

other: Числовой литерал или значение выражения.

См. также

floordiv

Примечания

Поведение при делении на ноль соответствует IEEE-754:

0/0: недопустимая операция — математически не определена, возвращает NaN. n/0: для конечных операндов даёт точный бесконечный результат, например ±infinity.

Примеры

>>> df = pl.DataFrame(
...     data={"x": [-2, -1, 0, 1, 2], "y": [0.5, 0.0, 0.0, -4.0, -0.5]}
... )
>>> df.with_columns(
...     pl.col("x").truediv(2).alias("x/2"),
...     pl.col("x").truediv(pl.col("y")).alias("x/y"),
... )
shape: (5, 4)
┌─────┬──────┬──────┬───────┐
│ x   ┆ y    ┆ x/2  ┆ x/y   │
│ --- ┆ ---  ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ f64  ┆ f64   │
╞═════╪══════╪══════╪═══════╡
│ -2  ┆ 0.5  ┆ -1.0 ┆ -4.0  │
│ -1  ┆ 0.0  ┆ -0.5 ┆ -inf  │
│ 0   ┆ 0.0  ┆ 0.0  ┆ NaN   │
│ 1   ┆ -4.0 ┆ 0.5  ┆ -0.25 │
│ 2   ┆ -0.5 ┆ 1.0  ┆ -4.0  │
└─────┴──────┴──────┴───────┘

truncate(
    decimals: int = 0,
) → Expr

Усечь числовые данные в сторону нуля до decimals знаков после запятой.

движок:В памятиПотоковая обработкаРаспределенный

Параметры:

decimals: Количество знаков после запятой для усечения.

См. также

ceil: Округлить вверх до ближайшего целого числа.
floor: Округлить вниз до ближайшего целого числа.
round: Округлить до заданного количества знаков после запятой.
round_sig_figs: Округлить до заданного количества значащих цифр.

Примечания

При усечении отбрасывается дробная часть, выходящая за заданное количество знаков после запятой. Например, при округлении до 0 знаков числа 0.25, -0.25, 0.99 и -0.99 округляются до 0. При округлении до 1 знака число 1.9999 округляется до 1.9, а -1.9999 — до -1.9. Для значений посередине не применяется правило выбора способа округления, как в round(), поэтому 0.5 и -0.5 также округляются до 0 при decimals=1.
Этот метод выполняет числовое усечение. Для усечения временных данных (дат/даты-времени) используйте вместо него Expr.dt.truncate().

Примеры

>>> df = pl.DataFrame({"n": [-9.9999, 0.12345, 1.0251, 8.8765]})
>>> df.with_columns(
...     t0=pl.col("n").truncate(0),
...     t1=pl.col("n").truncate(1),
...     t2=pl.col("n").truncate(2),
...     t3=pl.col("n").truncate(3),
...     t4=pl.col("n").truncate(4),
... )
shape: (4, 6)
┌─────────┬──────┬──────┬───────┬────────┬─────────┐
│ n       ┆ t0   ┆ t1   ┆ t2    ┆ t3     ┆ t4      │
│ ---     ┆ ---  ┆ ---  ┆ ---   ┆ ---    ┆ ---     │
│ f64     ┆ f64  ┆ f64  ┆ f64   ┆ f64    ┆ f64     │
╞═════════╪══════╪══════╪═══════╪════════╪═════════╡
│ -9.9999 ┆ -9.0 ┆ -9.9 ┆ -9.99 ┆ -9.999 ┆ -9.9999 │
│ 0.12345 ┆ 0.0  ┆ 0.1  ┆ 0.12  ┆ 0.123  ┆ 0.1234  │
│ 1.0251  ┆ 1.0  ┆ 1.0  ┆ 1.02  ┆ 1.025  ┆ 1.025   │
│ 8.8765  ┆ 8.0  ┆ 8.8  ┆ 8.87  ┆ 8.876  ┆ 8.8765  │
└─────────┴──────┴──────┴───────┴────────┴─────────┘

unique(
    *,
    maintain_order: bool = False,
) → Expr

Получить уникальные значения этого выражения.

Для целей этой операции null считается уникальным значением.

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

Параметры:

maintain_order: Сохранять порядок данных. Это требует дополнительных вычислений.

Примеры

>>> df = pl.DataFrame({"a": [1, 1, 2]})
>>> df.select(pl.col("a").unique())  
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 2   │
│ 1   │
└─────┘
>>> df.select(pl.col("a").unique(maintain_order=True))
shape: (2, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
└─────┘

unique_counts() → Expr

Вернуть количество уникальных значений в порядке их появления.

Этот метод отличается от value_counts тем, что возвращает не значения, а только их количество, и может работать быстрее.

движок:В памятиПотоковая обработка

Примеры

>>> df = pl.DataFrame(
...     {
...         "id": ["a", "b", "b", "c", "c", "c"],
...     }
... )
>>> df.select(pl.col("id").unique_counts())
shape: (3, 1)
┌─────┐
│ id  │
│ --- │
│ u32 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

Обратите внимание, что group_by можно использовать для подсчета значений.

>>> df.group_by("id", maintain_order=True).len().select("len")
shape: (3, 1)
┌─────┐
│ len │
│ --- │
│ u32 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

Чтобы добавить количество в новый столбец, pl.len() можно использовать как оконную функцию.

>>> df.with_columns(pl.len().over("id"))
shape: (6, 2)
┌─────┬─────┐
│ id  ┆ len │
│ --- ┆ --- │
│ str ┆ u32 │
╞═════╪═════╡
│ a   ┆ 1   │
│ b   ┆ 2   │
│ b   ┆ 2   │
│ c   ┆ 3   │
│ c   ┆ 3   │
│ c   ┆ 3   │
└─────┴─────┘

upper_bound() → Expr

Вычислить верхнюю границу.

Возвращает Series из одной строки с наибольшим возможным значением для типа данных этого выражения.

движок:В памятиПотоковая обработкаРаспределенный

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3, 2, 1]})
>>> df.select(pl.col("a").upper_bound())
shape: (1, 1)
┌─────────────────────┐
│ a                   │
│ ---                 │
│ i64                 │
╞═════════════════════╡
│ 9223372036854775807 │
└─────────────────────┘

value_counts(
    *,
    sort: bool = False,
    parallel: bool = False,
    name: str_ | None = None,
    normalize: bool = False,
) → Expr

Подсчитать количество вхождений уникальных значений.

движок:В памятиПотоковая обработка

Параметры:

sort: Отсортировать результат по количеству в порядке убывания. Если установлено значение False (по умолчанию), порядок не детерминирован.
parallel: Выполнить вычисление параллельно.

Примечание

Вероятно, этот параметр не следует включать в контексте group_by, поскольку вычисление уже будет выполняться параллельно для каждой группы.
name: Задать имя столбца с результатом подсчета; если normalize имеет значение True, по умолчанию используется имя «proportion», в противном случае — «count».
normalize: Если значение True, количество возвращается как относительная частота уникальных значений, нормализованная до 1.0.

Возвращает:

Expr: Выражение типа Struct, сопоставляющее уникальные значения с их количеством (или долей).

Примеры

>>> df = pl.DataFrame(
...     {"color": ["red", "blue", "red", "green", "blue", "blue"]}
... )
>>> df_count = df.select(pl.col("color").value_counts())
>>> df_count  
shape: (3, 1)
┌─────────────┐
│ color       │
│ ---         │
│ struct[2]   │
╞═════════════╡
│ {"green",1} │
│ {"blue",3}  │
│ {"red",2}   │
└─────────────┘

>>> df_count.unnest("color")  
shape: (3, 2)
┌───────┬───────┐
│ color ┆ count │
│ ---   ┆ ---   │
│ str   ┆ u32   │
╞═══════╪═══════╡
│ green ┆ 1     │
│ blue  ┆ 3     │
│ red   ┆ 2     │
└───────┴───────┘

Отсортировать результат по количеству (в порядке убывания), задать имя поля и нормализовать количество до относительной доли (от 1.0).

>>> df_count = df.select(
...     pl.col("color").value_counts(
...         name="fraction",
...         normalize=True,
...         sort=True,
...     )
... )
>>> df_count
shape: (3, 1)
┌────────────────────┐
│ color              │
│ ---                │
│ struct[2]          │
╞════════════════════╡
│ {"blue",0.5}       │
│ {"red",0.333333}   │
│ {"green",0.166667} │
└────────────────────┘

>>> df_count.unnest("color")
shape: (3, 2)
┌───────┬──────────┐
│ color ┆ fraction │
│ ---   ┆ ---      │
│ str   ┆ f64      │
╞═══════╪══════════╡
│ blue  ┆ 0.5      │
│ red   ┆ 0.333333 │
│ green ┆ 0.166667 │
└───────┴──────────┘

Обратите внимание, что group_by можно использовать для подсчета значений.

>>> df.group_by("color").len()  
shape: (3, 2)
┌───────┬─────┐
│ color ┆ len │
│ ---   ┆ --- │
│ str   ┆ u32 │
╞═══════╪═════╡
│ red   ┆ 2   │
│ green ┆ 1   │
│ blue  ┆ 3   │
└───────┴─────┘

Чтобы добавить количество в новый столбец, pl.len() можно использовать как оконную функцию.

>>> df.with_columns(pl.len().over("color"))
shape: (6, 2)
┌───────┬─────┐
│ color ┆ len │
│ ---   ┆ --- │
│ str   ┆ u32 │
╞═══════╪═════╡
│ red   ┆ 2   │
│ blue  ┆ 3   │
│ red   ┆ 2   │
│ green ┆ 1   │
│ blue  ┆ 3   │
│ blue  ┆ 3   │
└───────┴─────┘

>>> df.with_columns((pl.len().over("color") / pl.len()).alias("fraction"))
shape: (6, 2)
┌───────┬──────────┐
│ color ┆ fraction │
│ ---   ┆ ---      │
│ str   ┆ f64      │
╞═══════╪══════════╡
│ red   ┆ 0.333333 │
│ blue  ┆ 0.5      │
│ red   ┆ 0.333333 │
│ green ┆ 0.166667 │
│ blue  ┆ 0.5      │
│ blue  ┆ 0.5      │
└───────┴──────────┘

var(
    ddof: int = 1,
) → Expr

Получить дисперсию.

движок:В памятиПотоковая обработкаРаспределенный

Параметры:

ddof: «Поправка на число степеней свободы»: делитель, используемый при вычислении, равен N - ddof, где N — количество элементов. По умолчанию ddof равен 1.

Примеры

>>> df = pl.DataFrame({"a": [-1, 0, 1]})
>>> df.select(pl.col("a").var())
shape: (1, 1)
┌─────┐
│ a   │
│ --- │
│ f64 │
╞═════╡
│ 1.0 │
└─────┘

where(
    predicate: Expr,
) → Expr

Отфильтровать один столбец.

Устарело с версии 0.20.4: Вместо этого используйте метод filter().

Псевдоним для filter().

Параметры:

predicate: Булево выражение.

Примеры

>>> df = pl.DataFrame(
...     {
...         "group_col": ["g1", "g1", "g2"],
...         "b": [1, 2, 3],
...     }
... )
>>> df.group_by("group_col").agg(  
...     [
...         pl.col("b").where(pl.col("b") < 2).sum().alias("lt"),
...         pl.col("b").where(pl.col("b") >= 2).sum().alias("gte"),
...     ]
... ).sort("group_col")
shape: (2, 3)
┌───────────┬─────┬─────┐
│ group_col ┆ lt  ┆ gte │
│ ---       ┆ --- ┆ --- │
│ str       ┆ i64 ┆ i64 │
╞═══════════╪═════╪═════╡
│ g1        ┆ 1   ┆ 2   │
│ g2        ┆ 0   ┆ 3   │
└───────────┴─────┴─────┘

xor(
    other: Any,
) → Expr

Метод, эквивалентный оператору побитового исключающего ИЛИ expr ^ other.

движок:В памятиПотоковая обработкаРаспределенный

Параметры:

other: Целочисленное или булево значение; допускается ввод выражения.

Примеры

>>> df = pl.DataFrame(
...     {"x": [True, False, True, False], "y": [True, True, False, False]}
... )
>>> df.with_columns(pl.col("x").xor(pl.col("y")).alias("x ^ y"))
shape: (4, 3)
┌───────┬───────┬───────┐
│ x     ┆ y     ┆ x ^ y │
│ ---   ┆ ---   ┆ ---   │
│ bool  ┆ bool  ┆ bool  │
╞═══════╪═══════╪═══════╡
│ true  ┆ true  ┆ false │
│ false ┆ true  ┆ true  │
│ true  ┆ false ┆ true  │
│ false ┆ false ┆ false │
└───────┴───────┴───────┘

>>> def binary_string(n: int) -> str:
...     return bin(n)[2:].zfill(8)
>>>
>>> df = pl.DataFrame(
...     data={"x": [10, 8, 250, 66], "y": [1, 2, 3, 4]},
...     schema={"x": pl.UInt8, "y": pl.UInt8},
... )
>>> df.with_columns(
...     pl.col("x")
...     .map_elements(binary_string, return_dtype=pl.String)
...     .alias("bin_x"),
...     pl.col("y")
...     .map_elements(binary_string, return_dtype=pl.String)
...     .alias("bin_y"),
...     pl.col("x").xor(pl.col("y")).alias("xor_xy"),
...     pl.col("x")
...     .xor(pl.col("y"))
...     .map_elements(binary_string, return_dtype=pl.String)
...     .alias("bin_xor_xy"),
... )
shape: (4, 6)
┌─────┬─────┬──────────┬──────────┬────────┬────────────┐
│ x   ┆ y   ┆ bin_x    ┆ bin_y    ┆ xor_xy ┆ bin_xor_xy │
│ --- ┆ --- ┆ ---      ┆ ---      ┆ ---    ┆ ---        │
│ u8  ┆ u8  ┆ str      ┆ str      ┆ u8     ┆ str        │
╞═════╪═════╪══════════╪══════════╪════════╪════════════╡
│ 10  ┆ 1   ┆ 00001010 ┆ 00000001 ┆ 11     ┆ 00001011   │
│ 8   ┆ 2   ┆ 00001000 ┆ 00000010 ┆ 10     ┆ 00001010   │
│ 250 ┆ 3   ┆ 11111010 ┆ 00000011 ┆ 249    ┆ 11111001   │
│ 66  ┆ 4   ┆ 01000010 ┆ 00000100 ┆ 70     ┆ 01000110   │
└─────┴─────┴──────────┴──────────┴────────┴────────────┘

© 2020 Ritchie Vink
© 2022 Polars contributors
Licensed under the MIT License.
https://docs.pola.rs/api/python/stable/reference/expressions/index.html