DataFrame

На этой странице представлен обзор всех общедоступных методов DataFrame.

class polars.DataFrame(
    data: FrameInitTypes | None = None,
    schema: SchemaDefinition | None = None,
    *,
    schema_overrides: SchemaDict | None = None,
    strict: bool = True,
    orient: Orientation | None = None,
    infer_schema_length: int | None = 100,
    nan_to_null: bool = False,
    height: int | None = None,
)

Двумерная структура данных, представляющая данные в виде таблицы со строками и столбцами.

Параметры:

datadict, Sequence, ndarray, Series, or pandas.DataFrame

Двумерные данные в различных форматах; входной словарь должен содержать последовательности, генераторы или range. Последовательность может содержать Series или другие последовательности.

schemaSequence of str, (str,DataType) pairs, or a {str:DataType,} dict

Схема результирующего DataFrame. Схему можно задать несколькими способами:

• В виде словаря пар {имя:тип}; если тип равен None, он будет определён автоматически.
• В виде списка имён столбцов; в этом случае типы определяются автоматически.
• В виде списка пар (имя,тип); это эквивалентно форме словаря.

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

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

Если задано значение None (по умолчанию), схема выводится из данных.

schema_overridesdict, default None

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

Количество записей в схеме должно соответствовать размерностям исходных данных, если только не передаётся последовательность словарей; в этом случае можно задать частичную схему, чтобы предотвратить загрузку определённых полей.

strictbool, default True

Вызывает ошибку, если какое-либо значение data не соответствует в точности заданному или выведенному типу данных для этого столбца. Если задано значение False, значения, не соответствующие типу данных, приводятся к этому типу или, если приведение невозможно, заменяются на null.

orient{‘col’, ‘row’}, default None

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

infer_schema_lengthint or None

Максимальное количество строк, просматриваемых при выводе схемы. Если задано значение None, могут быть просмотрены все данные (это может занять много времени). Этот параметр применяется только в том случае, если входные данные представляют собой последовательность или генератор строк; остальные входные данные считываются как есть.

nan_to_nullbool, default False

Если данные получены из одного или нескольких массивов numpy, можно преобразовать значения np.nan во входных данных в null. Для всех остальных входных данных этот параметр ничего не делает.

heightint or None, default None

Позволяет создавать DataFrame с нулевой шириной и заданной высотой. Если передан вместе с данными, гарантирует, что результирующий DataFrame будет иметь эту высоту.

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

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

Примечания

Polars явно не поддерживает наследование от своих основных типов данных. Возможные обходные решения описаны в следующем обсуждении на GitHub: pola-rs/polars#2846

Примеры

Создание DataFrame из словаря:

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

Обратите внимание, что типы данных автоматически определяются как polars Int64:

>>> df.dtypes
[Int64, Int64]

Чтобы задать более подробную/точную схему таблицы, можно передать параметр schema со словарём пар (имя,тип)…

>>> data = {"col1": [0, 2], "col2": [3, 7]}
>>> df2 = pl.DataFrame(data, schema={"col1": pl.Float32, "col2": pl.Int64})
>>> df2
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 0.0  ┆ 3    │
│ 2.0  ┆ 7    │
└──────┴──────┘

…последовательностью пар (имя,тип)…

>>> data = {"col1": [1, 2], "col2": [3, 4]}
>>> df3 = pl.DataFrame(data, schema=[("col1", pl.Float32), ("col2", pl.Int64)])
>>> df3
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

…или списком типизированных Series.

>>> data = [
...     pl.Series("col1", [1, 2], dtype=pl.Float32),
...     pl.Series("col2", [3, 4], dtype=pl.Int64),
... ]
>>> df4 = pl.DataFrame(data)
>>> df4
shape: (2, 2)
┌──────┬──────┐
│ col1 ┆ col2 │
│ ---  ┆ ---  │
│ f32  ┆ i64  │
╞══════╪══════╡
│ 1.0  ┆ 3    │
│ 2.0  ┆ 4    │
└──────┴──────┘

Создание DataFrame из массива numpy ndarray с указанием имён столбцов:

>>> import numpy as np
>>> data = np.array([(1, 2), (3, 4)], dtype=np.int64)
>>> df5 = pl.DataFrame(data, schema=["a", "b"], orient="col")
>>> df5
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 3   │
│ 2   ┆ 4   │
└─────┴─────┘

Создание DataFrame из списка списков с указанием ориентации по строкам:

>>> data = [[1, 2, 3], [4, 5, 6]]
>>> df6 = pl.DataFrame(data, schema=["a", "b", "c"], orient="row")
>>> df6
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

Методы:

approx_n_unique	Приблизительное количество уникальных значений.
bottom_k	Возвращает k наименьших строк.
cast	Преобразует типы данных столбцов DataFrame в указанные типы.
clear	Создаёт пустую копию DataFrame (n=0) или копию из n строк, заполненных null-значениями (n>0).
clone	Создаёт копию этого DataFrame.
collect_schema	Возвращает упорядоченное отображение имён столбцов на соответствующие типы данных.
corr	Возвращает парные коэффициенты корреляции Пирсона между столбцами.
count	Возвращает количество ненулевых элементов в каждом столбце.
describe	Сводная статистика DataFrame.
deserialize	Считывает сериализованный DataFrame из файла.
drop	Удаляет столбцы из DataFrame.
drop_in_place	Удаляет один столбец на месте и возвращает удалённый столбец.
drop_nans	Удаляет все строки, содержащие одно или несколько значений NaN.
drop_nulls	Удаляет все строки, содержащие одно или несколько null-значений.
equals	Проверяет, равен ли DataFrame другому DataFrame.
estimated_size	Возвращает оценку общего размера памяти (кучи), выделенной для DataFrame.
explode	Преобразует DataFrame в длинный формат, разворачивая указанные столбцы.
extend	Расширяет память, используемую этим DataFrame, значениями из other.
fill_nan	Заполняет значения NaN с плавающей точкой результатами вычисления выражения.
fill_null	Заполняет null-значения указанным значением или с помощью заданной стратегии.
filter	Фильтрует строки, оставляя те, которые соответствуют заданным выражениям-предикатам.
fold	Выполняет горизонтальную свёртку DataFrame.
gather	Выбирает строки этого DataFrame по заданным индексам.
gather_every	Выбирает каждую n-ю строку DataFrame и возвращает их в виде нового DataFrame.
get_column	Возвращает один столбец по имени.
get_column_index	Находит индекс столбца по имени.
get_columns	Возвращает DataFrame в виде списка Series.
glimpse	Возвращает компактный предварительный просмотр DataFrame.
group_by	Начинает операцию группировки.
group_by_dynamic	Группирует данные по временному значению (или значению индекса типа Int32, Int64).
hash_rows	Вычисляет хеши строк этого DataFrame и объединяет их.
head	Возвращает первые n строк.
hstack	Возвращает новый DataFrame, расширенный по горизонтали несколькими Series.
insert_column	Вставляет Series (или выражение) по указанному индексу столбца.
interpolate	Интерполирует промежуточные значения.
is_duplicated	Возвращает маску всех повторяющихся строк в этом DataFrame.
is_empty	Возвращает True, если DataFrame не содержит строк.
is_sorted	Проверяет, отсортирован ли DataFrame по заданным столбцам.
is_unique	Возвращает маску всех уникальных строк в этом DataFrame.
item	Возвращает DataFrame как скаляр или элемент в заданной строке и столбце.
iter_columns	Возвращает итератор по столбцам этого DataFrame.
iter_rows	Возвращает итератор по строкам DataFrame со значениями в нативном формате Python.
iter_slices	Возвращает итератор по срезам базового DataFrame без копирования.
join	Выполняет соединение по аналогии с SQL.
join_asof	Выполняет соединение типа asof.
join_where	Выполняет соединение на основе одного или нескольких предикатов равенства или неравенства.
lazy	Начинает ленивый запрос с текущего этапа.
limit	Возвращает первые n строк.
map_columns	Применяет eager-функции к столбцам DataFrame.
map_rows	Применяет пользовательскую функцию (UDF) к строкам DataFrame.
match_to_schema	Приводит схему LazyFrame к заданной схеме или изменяет её.
max	Вычисляет максимальное значение для каждого столбца DataFrame.
max_horizontal	Находит максимальное значение по горизонтали среди столбцов.
mean	Вычисляет среднее значение для каждого столбца DataFrame.
mean_horizontal	Вычисляет среднее значение по горизонтали среди всех столбцов.
median	Вычисляет медианное значение для каждого столбца DataFrame.
melt	Преобразует DataFrame из широкого формата в длинный.
merge_sorted	Объединяет два отсортированных DataFrame по отсортированному ключу.
min	Вычисляет минимальное значение для каждого столбца DataFrame.
min_horizontal	Находит минимальное значение по горизонтали среди столбцов.
n_chunks	Возвращает количество чанков, используемых ChunkedArray этого DataFrame.
n_unique	Возвращает количество уникальных строк или уникальных подмножеств строк.
null_count	Создаёт новый DataFrame с количеством null-значений в каждом столбце.
partition_by	Группирует данные по заданным столбцам и возвращает группы в виде отдельных DataFrame.
pipe	Предоставляет структурированный способ применить последовательность пользовательских функций (UDF).
pivot	Создаёт сводную таблицу в стиле электронной таблицы в виде DataFrame.
product	Вычисляет произведение значений в каждом столбце DataFrame.
quantile	Вычисляет квантиль для каждого столбца DataFrame.
rechunk	Перераспределяет данные этого DataFrame в непрерывную область памяти.
remove	Удаляет строки, соответствующие заданным выражениям-предикатам.
rename	Переименовывает столбцы.
replace_column	Заменяет столбец по указанному индексу.
reverse	Разворачивает DataFrame в обратном порядке.
rolling	Создаёт скользящие группы на основе временного столбца или столбца с целыми числами.
row	Возвращает значения одной строки по индексу или предикату.
rows	Возвращает все данные DataFrame в виде списка строк со значениями в нативном формате Python.
rows_by_key	Возвращает все данные в виде словаря со значениями в нативном формате Python, ключами которого служит указанный столбец.
sample	Выбирает случайную выборку из этого DataFrame.
select	Выбирает столбцы из этого DataFrame.
select_seq	Выбирает столбцы из этого DataFrame.
serialize	Сериализует этот DataFrame в файл или строку в формате JSON.
set_sorted	Помечает столбец как отсортированный.
shift	Сдвигает значения на указанное количество индексов.
show	Показывает первые n строк.
shrink_to_fit	Уменьшает объём памяти, используемой DataFrame.
slice	Возвращает срез этого DataFrame.
sort	Сортирует DataFrame по заданным столбцам.
sql	Выполняет SQL-запрос к DataFrame.
std	Вычисляет стандартное отклонение для каждого столбца DataFrame.
sum	Вычисляет сумму значений в каждом столбце DataFrame.
sum_horizontal	Суммирует все значения по горизонтали среди столбцов.
tail	Возвращает последние n строк.
to_arrow	Собирает базовые массивы Arrow в таблицу Arrow.
to_dict	Преобразует DataFrame в словарь, сопоставляющий имена столбцов со значениями.
to_dicts	Преобразует каждую строку в словарь со значениями в нативном формате Python.
to_dummies	Преобразует категориальные переменные в фиктивные (индикаторные) переменные.
to_init_repr	Преобразует DataFrame в строковое представление, пригодное для создания объекта.
to_jax	Преобразует DataFrame в массив Jax или словарь массивов Jax.
to_numpy	Преобразует этот DataFrame в массив NumPy ndarray.
to_pandas	Преобразует этот DataFrame в DataFrame библиотеки pandas.
to_series	Выбирает столбец как Series по указанному индексу.
to_struct	Преобразует DataFrame в Series типа Struct.
to_torch	Преобразует DataFrame в тензор, набор данных или словарь тензоров PyTorch.
top_k	Возвращает k наибольших строк.
transpose	Транспонирует DataFrame относительно диагонали.
unique	Удаляет повторяющиеся строки из этого DataFrame.
unnest	Разбивает столбцы struct на отдельные столбцы для каждого из их полей.
unpivot	Преобразует DataFrame из широкого формата в длинный.
unstack	Преобразует длинную таблицу в широкую без агрегации.
update	Обновляет значения в этом DataFrame значениями из other.
upsample	Выполняет увеличение частоты дискретизации DataFrame с регулярным интервалом.
var	Вычисляет дисперсию для каждого столбца DataFrame.
vstack	Расширяет DataFrame по вертикали, добавляя к нему другой DataFrame.
with_columns	Добавляет столбцы в этот DataFrame.
with_columns_seq	Добавляет столбцы в этот DataFrame.
with_row_count	Добавляет столбец по индексу 0 со счётчиком строк.
with_row_index	Добавляет индекс строк в качестве первого столбца DataFrame.
write_avro	Записывает данные в файл Apache Avro.
write_clipboard	Копирует DataFrame в формате CSV в системный буфер обмена с помощью write_csv.
write_csv	Записывает данные в файл с разделителями-запятыми (CSV).
write_database	Записывает данные из DataFrame Polars в базу данных.
write_delta	Записывает DataFrame как таблицу Delta.
write_excel	Записывает данные фрейма в таблицу книги или листа Excel.

write_iceberg	Записать DataFrame в таблицу Iceberg.
write_ipc	Записать данные в двоичный поток Arrow IPC или файл Feather.
write_ipc_stream	Записать данные в поток пакетов записей Arrow IPC.
write_json	Сериализовать в представление JSON.
write_ndjson	Сериализовать в представление JSON с разделителями-символами новой строки.
write_parquet	Записать данные в файл Apache Parquet.

Атрибуты:

columns	Получить или задать имена столбцов.
dtypes	Получить типы данных столбцов.
flags	Получить флаги, заданные для столбцов этого DataFrame.
height	Получить количество строк.
plot	Создать пространство имён для построения графиков.
schema	Получить упорядоченное сопоставление имён столбцов с их типами данных.
shape	Получить форму DataFrame.
style	Создать Great Table для стилизации.
width	Получить количество столбцов.

approx_n_unique() → DataFrame

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

Устарело с версии 0.20.11: Вместо этого используйте метод select(pl.all().approx_n_unique()).

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

Примеры

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

bottom_k(
    k: int,
    *,
    by: IntoExpr | Iterable[IntoExpr],
    reverse: bool | Sequence[bool] = False,
) → DataFrame

Вернуть k наименьших строк.

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

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

Параметры:

k

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

by

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

reverse

Рассматривать k наибольших элементов столбца или столбцов by (вместо k наименьших). Для каждого столбца отдельно можно передать последовательность логических значений.

См. также

top_k

Примеры

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

Получить строки, содержащие 4 наименьших значения в столбце b.

>>> df.bottom_k(4, by="b")
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 1   │
│ a   ┆ 1   │
│ c   ┆ 1   │
│ a   ┆ 2   │
└─────┴─────┘

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

>>> df.bottom_k(4, by=["a", "b"])
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ a   ┆ 1   │
│ a   ┆ 2   │
│ b   ┆ 1   │
│ b   ┆ 2   │
└─────┴─────┘

cast(
    dtypes: Mapping[ColumnNameOrSelector | PolarsDataType,
    PolarsDataType | PythonDataType] | PolarsDataType | Schema,
    *,
    strict: bool = True,
) → DataFrame

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

Параметры:

dtypes

Сопоставление имён столбцов (или селектора) с типами данных либо один тип данных, к которому будут приведены все столбцы.

strict

Вызывать исключение, если приведение типов недопустимо для строк после проталкивания предикатов. Если False, недопустимое приведение типов приведёт к значениям null.

Примеры

>>> from datetime import date
>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": [date(2020, 1, 2), date(2021, 3, 4), date(2022, 5, 6)],
...     }
... )

Привести типы данных отдельных столбцов фрейма к указанным типам:

>>> df.cast({"foo": pl.Float32, "bar": pl.UInt8})
shape: (3, 3)
┌─────┬─────┬────────────┐
│ foo ┆ bar ┆ ham        │
│ --- ┆ --- ┆ ---        │
│ f32 ┆ u8  ┆ date       │
╞═════╪═════╪════════════╡
│ 1.0 ┆ 6   ┆ 2020-01-02 │
│ 2.0 ┆ 7   ┆ 2021-03-04 │
│ 3.0 ┆ 8   ┆ 2022-05-06 │
└─────┴─────┴────────────┘

Привести тип данных всех столбцов фрейма, соответствующих одному типу (или группе типов), к другому типу:

>>> df.cast({pl.Date: pl.Datetime})
shape: (3, 3)
┌─────┬─────┬─────────────────────┐
│ foo ┆ bar ┆ ham                 │
│ --- ┆ --- ┆ ---                 │
│ i64 ┆ f64 ┆ datetime[μs]        │
╞═════╪═════╪═════════════════════╡
│ 1   ┆ 6.0 ┆ 2020-01-02 00:00:00 │
│ 2   ┆ 7.0 ┆ 2021-03-04 00:00:00 │
│ 3   ┆ 8.0 ┆ 2022-05-06 00:00:00 │
└─────┴─────┴─────────────────────┘

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

>>> import polars.selectors as cs
>>> df.cast({cs.numeric(): pl.UInt32, cs.temporal(): pl.String})
shape: (3, 3)
┌─────┬─────┬────────────┐
│ foo ┆ bar ┆ ham        │
│ --- ┆ --- ┆ ---        │
│ u32 ┆ u32 ┆ str        │
╞═════╪═════╪════════════╡
│ 1   ┆ 6   ┆ 2020-01-02 │
│ 2   ┆ 7   ┆ 2021-03-04 │
│ 3   ┆ 8   ┆ 2022-05-06 │
└─────┴─────┴────────────┘

Привести типы данных всех столбцов фрейма к указанному типу:

>>> df.cast(pl.String).to_dict(as_series=False)
{'foo': ['1', '2', '3'],
 'bar': ['6.0', '7.0', '8.0'],
 'ham': ['2020-01-02', '2021-03-04', '2022-05-06']}

clear(
    n: int = 0,
) → DataFrame

Создать пустую копию DataFrame (n=0) или копию с n строками, заполненными null (n>0).

Возвращает DataFrame с n строками, заполненными null, и идентичной схемой. n может превышать текущее количество строк в DataFrame.

Параметры:

n

Количество строк (заполненных null), возвращаемых в очищенном фрейме.

См. также

clone

Недорогое глубокое копирование/создание клона.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [None, 2, 3, 4],
...         "b": [0.5, None, 2.5, 13],
...         "c": [True, True, False, None],
...     }
... )
>>> df.clear()
shape: (0, 3)
┌─────┬─────┬──────┐
│ a   ┆ b   ┆ c    │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ f64 ┆ bool │
╞═════╪═════╪══════╡
└─────┴─────┴──────┘

>>> df.clear(n=2)
shape: (2, 3)
┌──────┬──────┬──────┐
│ a    ┆ b    ┆ c    │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ f64  ┆ bool │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ null ┆ null ┆ null │
└──────┴──────┴──────┘

clone() → DataFrame

Создать копию этого DataFrame.

Это недорогая операция, которая не копирует данные.

См. также

clear

Создать пустую копию текущего DataFrame с идентичной схемой, но без данных.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [0.5, 4, 10, 13],
...         "c": [True, True, False, True],
...     }
... )
>>> df.clone()
shape: (4, 3)
┌─────┬──────┬───────┐
│ a   ┆ b    ┆ c     │
│ --- ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  │
│ 2   ┆ 4.0  ┆ true  │
│ 3   ┆ 10.0 ┆ false │
│ 4   ┆ 13.0 ┆ true  │
└─────┴──────┴───────┘

collect_schema() → Schema

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

Это псевдоним свойства schema.

См. также

schema

Примечания

Этот метод включён для упрощения написания кода, общего для DataFrame и LazyFrame.

Примеры

Определить схему.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.collect_schema()
Schema({'foo': Int64, 'bar': Float64, 'ham': String})

Получить доступ к различным свойствам схемы с помощью объекта Schema.

>>> schema = df.collect_schema()
>>> schema["bar"]
Float64
>>> schema.names()
['foo', 'bar', 'ham']
>>> schema.dtypes()
[Int64, Float64, String]
>>> schema.len()
3

property columns: list[str]

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

Возвращает:

список str

Список, содержащий имена всех столбцов в их исходном порядке.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.columns
['foo', 'bar', 'ham']

Задать имена столбцов:

>>> df.columns = ["apple", "banana", "orange"]
>>> df
shape: (3, 3)
┌───────┬────────┬────────┐
│ apple ┆ banana ┆ orange │
│ ---   ┆ ---    ┆ ---    │
│ i64   ┆ i64    ┆ str    │
╞═══════╪════════╪════════╡
│ 1     ┆ 6      ┆ a      │
│ 2     ┆ 7      ┆ b      │
│ 3     ┆ 8      ┆ c      │
└───────┴────────┴────────┘

corr(
    *,
    label: str | None = None,
    **kwargs: Any,
) → DataFrame

Вернуть попарные коэффициенты корреляции Пирсона между столбцами.

Дополнительные сведения см. в документации numpy corrcoef: https://numpy.org/doc/stable/reference/generated/numpy.corrcoef.html

Параметры:

label

Если задано, добавляется новый столбец с указанным именем, содержащий метки (имена столбцов), связанные с каждой строкой.

**kwargs

Именованные аргументы, передаваемые в numpy.corrcoef.

Примечания

Для работы этой функциональности необходимо установить numpy.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [3, 2, 1], "ham": [7, 8, 9]})
>>> df.corr()
shape: (3, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ f64  ┆ f64  ┆ f64  │
╞══════╪══════╪══════╡
│ 1.0  ┆ -1.0 ┆ 1.0  │
│ -1.0 ┆ 1.0  ┆ -1.0 │
│ 1.0  ┆ -1.0 ┆ 1.0  │
└──────┴──────┴──────┘
>>> df.corr(label="cols")
shape: (3, 4)
┌──────┬──────┬──────┬──────┐
│ cols ┆ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  ┆ ---  │
│ str  ┆ f64  ┆ f64  ┆ f64  │
╞══════╪══════╪══════╪══════╡
│ foo  ┆ 1.0  ┆ -1.0 ┆ 1.0  │
│ bar  ┆ -1.0 ┆ 1.0  ┆ -1.0 │
│ ham  ┆ 1.0  ┆ -1.0 ┆ 1.0  │
└──────┴──────┴──────┴──────┘

count() → DataFrame

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

Примеры

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

describe(
    percentiles: Sequence[float] | float | None = (0.25,
    0.5,
    0.75,
), *, interpolation: QuantileMethod = 'nearest', ) → DataFrame

Сводная статистика DataFrame.

Параметры:

percentiles

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

interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’, ‘equiprobable’}

Метод интерполяции, используемый при вычислении процентилей.

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

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

См. также

glimpse

Примечания

По умолчанию включается медиана, соответствующая 50-му процентилю.

Примеры

>>> from datetime import date, time
>>> df = pl.DataFrame(
...     {
...         "float": [1.0, 2.8, 3.0],
...         "int": [40, 50, None],
...         "bool": [True, False, True],
...         "str": ["zz", "xx", "yy"],
...         "date": [date(2020, 1, 1), date(2021, 7, 5), date(2022, 12, 31)],
...         "time": [time(10, 20, 30), time(14, 45, 50), time(23, 15, 10)],
...     }
... )

Показать статистику фрейма по умолчанию:

>>> df.describe()
shape: (9, 7)
┌────────────┬──────────┬──────────┬──────────┬──────┬─────────────────────┬──────────┐
│ statistic  ┆ float    ┆ int      ┆ bool     ┆ str  ┆ date                ┆ time     │
│ ---        ┆ ---      ┆ ---      ┆ ---      ┆ ---  ┆ ---                 ┆ ---      │
│ str        ┆ f64      ┆ f64      ┆ f64      ┆ str  ┆ str                 ┆ str      │
╞════════════╪══════════╪══════════╪══════════╪══════╪═════════════════════╪══════════╡
│ count      ┆ 3.0      ┆ 2.0      ┆ 3.0      ┆ 3    ┆ 3                   ┆ 3        │
│ null_count ┆ 0.0      ┆ 1.0      ┆ 0.0      ┆ 0    ┆ 0                   ┆ 0        │
│ mean       ┆ 2.266667 ┆ 45.0     ┆ 0.666667 ┆ null ┆ 2021-07-02 16:00:00 ┆ 16:07:10 │
│ std        ┆ 1.101514 ┆ 7.071068 ┆ null     ┆ null ┆ null                ┆ null     │
│ min        ┆ 1.0      ┆ 40.0     ┆ 0.0      ┆ xx   ┆ 2020-01-01          ┆ 10:20:30 │
│ 25%        ┆ 2.8      ┆ 40.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
│ 50%        ┆ 2.8      ┆ 50.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
│ 75%        ┆ 3.0      ┆ 50.0     ┆ null     ┆ null ┆ 2022-12-31          ┆ 23:15:10 │
│ max        ┆ 3.0      ┆ 50.0     ┆ 1.0      ┆ zz   ┆ 2022-12-31          ┆ 23:15:10 │
└────────────┴──────────┴──────────┴──────────┴──────┴─────────────────────┴──────────┘

Настроить отображаемые процентили, используя линейную интерполяцию:

>>> with pl.Config(tbl_rows=12):
...     df.describe(
...         percentiles=[0.1, 0.3, 0.5, 0.7, 0.9],
...         interpolation="linear",
...     )
shape: (11, 7)
┌────────────┬──────────┬──────────┬──────────┬──────┬─────────────────────┬──────────┐
│ statistic  ┆ float    ┆ int      ┆ bool     ┆ str  ┆ date                ┆ time     │
│ ---        ┆ ---      ┆ ---      ┆ ---      ┆ ---  ┆ ---                 ┆ ---      │
│ str        ┆ f64      ┆ f64      ┆ f64      ┆ str  ┆ str                 ┆ str      │
╞════════════╪══════════╪══════════╪══════════╪══════╪═════════════════════╪══════════╡
│ count      ┆ 3.0      ┆ 2.0      ┆ 3.0      ┆ 3    ┆ 3                   ┆ 3        │
│ null_count ┆ 0.0      ┆ 1.0      ┆ 0.0      ┆ 0    ┆ 0                   ┆ 0        │
│ mean       ┆ 2.266667 ┆ 45.0     ┆ 0.666667 ┆ null ┆ 2021-07-02 16:00:00 ┆ 16:07:10 │
│ std        ┆ 1.101514 ┆ 7.071068 ┆ null     ┆ null ┆ null                ┆ null     │
│ min        ┆ 1.0      ┆ 40.0     ┆ 0.0      ┆ xx   ┆ 2020-01-01          ┆ 10:20:30 │
│ 10%        ┆ 1.36     ┆ 41.0     ┆ null     ┆ null ┆ 2020-04-20          ┆ 11:13:34 │
│ 30%        ┆ 2.08     ┆ 43.0     ┆ null     ┆ null ┆ 2020-11-26          ┆ 12:59:42 │
│ 50%        ┆ 2.8      ┆ 45.0     ┆ null     ┆ null ┆ 2021-07-05          ┆ 14:45:50 │
│ 70%        ┆ 2.88     ┆ 47.0     ┆ null     ┆ null ┆ 2022-02-07          ┆ 18:09:34 │
│ 90%        ┆ 2.96     ┆ 49.0     ┆ null     ┆ null ┆ 2022-09-13          ┆ 21:33:18 │
│ max        ┆ 3.0      ┆ 50.0     ┆ 1.0      ┆ zz   ┆ 2022-12-31          ┆ 23:15:10 │
└────────────┴──────────┴──────────┴──────────┴──────┴─────────────────────┴──────────┘

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

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

Параметры:

source

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

format

Формат сериализации DataFrame. Возможные варианты:

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

См. также

DataFrame.serialize

Примечания

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

Примеры

>>> import io
>>> df = pl.DataFrame({"a": [1, 2, 3], "b": [4.0, 5.0, 6.0]})
>>> bytes = df.serialize()
>>> pl.DataFrame.deserialize(io.BytesIO(bytes))
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ f64 │
╞═════╪═════╡
│ 1   ┆ 4.0 │
│ 2   ┆ 5.0 │
│ 3   ┆ 6.0 │
└─────┴─────┘

drop(
    *columns: ColumnNameOrSelector | Iterable[ColumnNameOrSelector],
    strict: bool = True,
) → DataFrame

Удалить столбцы из фрейма данных.

Параметры:

*columns

Имена столбцов, которые нужно удалить из фрейма данных. Принимает селектор столбцов.

strict

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

Примеры

Удалить один столбец, передав его имя.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.drop("ham")
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ f64 │
╞═════╪═════╡
│ 1   ┆ 6.0 │
│ 2   ┆ 7.0 │
│ 3   ┆ 8.0 │
└─────┴─────┘

Удалить несколько столбцов, передав список их имён.

>>> df.drop(["bar", "ham"])
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

Удалить несколько столбцов, передав селектор.

>>> import polars.selectors as cs
>>> df.drop(cs.numeric())
shape: (3, 1)
┌─────┐
│ ham │
│ --- │
│ str │
╞═════╡
│ a   │
│ b   │
│ c   │
└─────┘

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

>>> df.drop("foo", "ham")
shape: (3, 1)
┌─────┐
│ bar │
│ --- │
│ f64 │
╞═════╡
│ 6.0 │
│ 7.0 │
│ 8.0 │
└─────┘

drop_in_place(
    name: str,
) → Series

Удалить один столбец на месте и вернуть удалённый столбец.

Параметры:

name

Имя столбца, который нужно удалить.

Возвращает:

Series

Удалённый столбец.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.drop_in_place("ham")
shape: (3,)
Series: 'ham' [str]
[
    "a"
    "b"
    "c"
]

drop_nans(
    subset: ColumnNameOrSelector | Collection[ColumnNameOrSelector] | None = None,
) → DataFrame

Удалить все строки, содержащие одно или несколько значений NaN.

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

Параметры:

subset

Имена столбцов, в которых учитываются значения NaN; если задано None (по умолчанию), используются все столбцы (обратите внимание: значения NaN могут содержаться только в столбцах с числами с плавающей запятой).

См. также

drop_nulls

Примечания

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [-20.5, float("nan"), 80.0],
...         "bar": [float("nan"), 110.0, 25.5],
...         "ham": ["xxx", "yyy", None],
...     }
... )

По умолчанию этот метод удаляет строки, если любое из их значений равно NaN:

>>> df.drop_nans()
shape: (1, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ f64  ┆ f64  ┆ str  │
╞══════╪══════╪══════╡
│ 80.0 ┆ 25.5 ┆ null │
└──────┴──────┴──────┘

Область действия можно ограничить подмножеством столбцов, заданным по имени или селектором. Например, удалим строки, только если значение NaN находится в столбце «bar»:

>>> df.drop_nans(subset=["bar"])
shape: (2, 3)
┌──────┬───────┬──────┐
│ foo  ┆ bar   ┆ ham  │
│ ---  ┆ ---   ┆ ---  │
│ f64  ┆ f64   ┆ str  │
╞══════╪═══════╪══════╡
│ NaN  ┆ 110.0 ┆ yyy  │
│ 80.0 ┆ 25.5  ┆ null │
└──────┴───────┴──────┘

Чтобы удалять строку, только если все значения равны NaN, требуется другая формулировка:

>>> df = pl.DataFrame(
...     {
...         "a": [float("nan"), float("nan"), float("nan"), float("nan")],
...         "b": [10.0, 2.5, float("nan"), 5.25],
...         "c": [65.75, float("nan"), float("nan"), 10.5],
...     }
... )
>>> df.filter(~pl.all_horizontal(pl.all().is_nan()))
shape: (3, 3)
┌─────┬──────┬───────┐
│ a   ┆ b    ┆ c     │
│ --- ┆ ---  ┆ ---   │
│ f64 ┆ f64  ┆ f64   │
╞═════╪══════╪═══════╡
│ NaN ┆ 10.0 ┆ 65.75 │
│ NaN ┆ 2.5  ┆ NaN   │
│ NaN ┆ 5.25 ┆ 10.5  │
└─────┴──────┴───────┘

drop_nulls(
    subset: ColumnNameOrSelector | Collection[ColumnNameOrSelector] | None = None,
) → DataFrame

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

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

Параметры:

subset

Имена столбцов, в которых учитываются значения null. Если задано None (по умолчанию), используются все столбцы.

См. также

drop_nans

Примечания

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, None, 8],
...         "ham": ["a", "b", None],
...     }
... )

По умолчанию этот метод удаляет строки, если любое из их значений равно null.

>>> df.drop_nulls()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

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

>>> import polars.selectors as cs
>>> df.drop_nulls(subset=cs.integer())
shape: (2, 3)
┌─────┬─────┬──────┐
│ foo ┆ bar ┆ ham  │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ i64 ┆ str  │
╞═════╪═════╪══════╡
│ 1   ┆ 6   ┆ a    │
│ 3   ┆ 8   ┆ null │
└─────┴─────┴──────┘

Ниже приведены дополнительные примеры удаления значений null на основе других условий.

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

Удалить строку, только если все значения равны null:

>>> df.filter(~pl.all_horizontal(pl.all().is_null()))
shape: (3, 3)
┌──────┬─────┬──────┐
│ a    ┆ b   ┆ c    │
│ ---  ┆ --- ┆ ---  │
│ null ┆ i64 ┆ i64  │
╞══════╪═════╪══════╡
│ null ┆ 1   ┆ 1    │
│ null ┆ 2   ┆ null │
│ null ┆ 1   ┆ 1    │
└──────┴─────┴──────┘

Удалить столбец, если все значения равны null:

>>> df[[s.name for s in df if not (s.null_count() == df.height)]]
shape: (4, 2)
┌──────┬──────┐
│ b    ┆ c    │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ 1    ┆ 1    │
│ 2    ┆ null │
│ null ┆ null │
│ 1    ┆ 1    │
└──────┴──────┘

property dtypes: list[DataType]

Получить типы данных столбцов.

Типы данных также отображаются в заголовках столбцов при выводе DataFrame.

Возвращает:

список DataType

Список, содержащий тип данных каждого столбца в исходном порядке.

См. также

schema

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.dtypes
[Int64, Float64, String]
>>> df
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6.0 ┆ a   │
│ 2   ┆ 7.0 ┆ b   │
│ 3   ┆ 8.0 ┆ c   │
└─────┴─────┴─────┘

equals(
    other: DataFrame,
    *,
    null_equal: bool = True,
) → bool

Проверить, равен ли DataFrame другому DataFrame.

Параметры:

other

DataFrame для сравнения.

null_equal

Считать значения null равными.

См. также

polars.testing.assert_frame_equal

Примеры

>>> df1 = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df2 = pl.DataFrame(
...     {
...         "foo": [3, 2, 1],
...         "bar": [8.0, 7.0, 6.0],
...         "ham": ["c", "b", "a"],
...     }
... )
>>> df1.equals(df1)
True
>>> df1.equals(df2)
False

estimated_size(
    unit: SizeUnit = 'b',
) → int | float

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

Оценка размера возвращается в указанных единицах (по умолчанию — байтах).

Эта оценка представляет собой сумму размеров буферов и битовых карт допустимости, включая вложенные массивы. Несколько массивов могут совместно использовать буферы и битовые карты. Поэтому размер двух массивов не равен сумме размеров, вычисленных этой функцией. В частности, размер [StructArray] является верхней границей.

При срезе массива объём выделенной для него памяти остаётся неизменным, поскольку буфер не меняется. Однако эта функция возвращает меньшее значение, так как вычисляет видимый размер буфера, а не его общую ёмкость.

В эту оценку включены буферы FFI.

Параметры:

unit{‘b’, ‘kb’, ‘mb’, ‘gb’, ‘tb’}

Масштабировать возвращаемый размер согласно указанным единицам.

Примечания

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "x": list(reversed(range(1_000_000))),
...         "y": [v / 1000 for v in range(1_000_000)],
...         "z": [str(v) for v in range(1_000_000)],
...     },
...     schema=[("x", pl.UInt32), ("y", pl.Float64), ("z", pl.String)],
... )
>>> df.estimated_size()
17888890
>>> df.estimated_size("mb")
17.0601749420166

explode(
    columns: ColumnNameOrSelector | Iterable[ColumnNameOrSelector],
    *more_columns: ColumnNameOrSelector,
    empty_as_null: bool = <object object>,
    keep_nulls: bool = True,
) → DataFrame

Преобразовать фрейм данных в длинный формат, развернув указанные столбцы.

Параметры:

columns

Имена столбцов, выражения или селектор, определяющий столбцы. Тип данных разворачиваемых столбцов должен быть List или Array.

*more_columns

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

empty_as_null

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

keep_nulls

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

Возвращает:

DataFrame

Примеры

>>> df = pl.DataFrame(
...     {
...         "letters": ["a", "a", "b", "c"],
...         "numbers": [[1], [2, 3], [4, 5], [6, 7, 8]],
...     }
... )
>>> df
shape: (4, 2)
┌─────────┬───────────┐
│ letters ┆ numbers   │
│ ---     ┆ ---       │
│ str     ┆ list[i64] │
╞═════════╪═══════════╡
│ a       ┆ [1]       │
│ a       ┆ [2, 3]    │
│ b       ┆ [4, 5]    │
│ c       ┆ [6, 7, 8] │
└─────────┴───────────┘
>>> df.explode("numbers", empty_as_null=False)
shape: (8, 2)
┌─────────┬─────────┐
│ letters ┆ numbers │
│ ---     ┆ ---     │
│ str     ┆ i64     │
╞═════════╪═════════╡
│ a       ┆ 1       │
│ a       ┆ 2       │
│ a       ┆ 3       │
│ b       ┆ 4       │
│ b       ┆ 5       │
│ c       ┆ 6       │
│ c       ┆ 7       │
│ c       ┆ 8       │
└─────────┴─────────┘

extend(
    other: DataFrame,
) → DataFrame

Расширить память, используемую этим DataFrame, значениями из other.

В отличие от vstack, который добавляет фрагменты из other к фрагментам этого DataFrame, extend добавляет данные из other в базовые области памяти и поэтому может вызвать перераспределение памяти.

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

Если после одного добавления планируется выполнить запрос, предпочтительнее использовать extend, а не vstack. Например, при интерактивных операциях, когда вы добавляете n строк и повторно выполняете запрос.

Если перед выполнением запроса нужно многократно добавлять данные, предпочтительнее использовать vstack, а не extend. Например, при чтении нескольких файлов и объединении их в один DataFrame. В последнем случае завершите последовательность операций vstack вызовом rechunk.

Параметры:

other

DataFrame для добавления по вертикали.

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

Этот метод изменяет фрейм данных на месте. Фрейм данных возвращается только для удобства.

См. также

vstack

Примеры

>>> df1 = pl.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
>>> df2 = pl.DataFrame({"foo": [10, 20, 30], "bar": [40, 50, 60]})
>>> df1.extend(df2)
shape: (6, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 4   │
│ 2   ┆ 5   │
│ 3   ┆ 6   │
│ 10  ┆ 40  │
│ 20  ┆ 50  │
│ 30  ┆ 60  │
└─────┴─────┘

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

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

Параметры:

value

Значение для заполнения значений NaN.

Возвращает:

DataFrame

DataFrame, в котором значения NaN заменены заданным значением.

См. также

fill_null

Примечания

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1.5, 2, float("nan"), 4],
...         "b": [0.5, 4, float("nan"), 13],
...     }
... )
>>> df.fill_nan(99)
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ f64  ┆ f64  │
╞══════╪══════╡
│ 1.5  ┆ 0.5  │
│ 2.0  ┆ 4.0  │
│ 99.0 ┆ 99.0 │
│ 4.0  ┆ 13.0 │
└──────┴──────┘

fill_null(
    value: Any | Expr | None = None,
    strategy: FillNullStrategy | None = None,
    limit: int | None = None,
    *,
    matches_supertype: bool = True,
) → DataFrame

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

Параметры:

value

Значение для заполнения значений null.

strategy{None, ‘forward’, ‘backward’, ‘min’, ‘max’, ‘mean’, ‘zero’, ‘one’}

Стратегия заполнения значений null.

limit

Количество подряд идущих значений null для заполнения при использовании стратегии «forward» или «backward».

matches_supertype

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

Возвращает:

DataFrame

DataFrame, в котором значения None заменены согласно стратегии заполнения.

См. также

fill_nan

Примечания

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, None, 4],
...         "b": [0.5, 4, None, 13],
...     }
... )
>>> df.fill_null(99)
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 99  ┆ 99.0 │
│ 4   ┆ 13.0 │
└─────┴──────┘
>>> df.fill_null(strategy="forward")
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 2   ┆ 4.0  │
│ 4   ┆ 13.0 │
└─────┴──────┘

>>> df.fill_null(strategy="max")
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 4   ┆ 13.0 │
│ 4   ┆ 13.0 │
└─────┴──────┘

>>> df.fill_null(strategy="zero")
shape: (4, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ f64  │
╞═════╪══════╡
│ 1   ┆ 0.5  │
│ 2   ┆ 4.0  │
│ 0   ┆ 0.0  │
│ 4   ┆ 13.0 │
└─────┴──────┘

filter(
    *predicates: IntoExprColumn | Iterable[IntoExprColumn] | bool | list[bool] | np.ndarray[Any,
    Any],
    **constraints: Any,
) → DataFrame

Отфильтровать строки, оставив те, которые соответствуют заданному предикату или выражениям-предикатам.

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

Остаются только строки, для которых предикат даёт значение True; строки, для которых предикат даёт False или null, отбрасываются.

Параметры:

predicates

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

constraints

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

См. также

remove

Примечания

Если вы переходите с Pandas и выполняете фильтрацию на основе сравнения двух или более столбцов, обратите внимание: в Polars любое сравнение с участием значений null даст результат null, а не логическое значение True или False. Поэтому такие строки не сохраняются. Чтобы избежать неожиданного поведения, убедитесь, что значения null обрабатываются надлежащим образом (см. примеры ниже).

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, None, 4, None, 0],
...         "bar": [6, 7, 8, None, None, 9, 0],
...         "ham": ["a", "b", "c", None, "d", "e", "f"],
...     }
... )

Отфильтровать строки, соответствующие условию:

>>> df.filter(pl.col("foo") > 1)
shape: (3, 3)
┌─────┬──────┬─────┐
│ foo ┆ bar  ┆ ham │
│ --- ┆ ---  ┆ --- │
│ i64 ┆ i64  ┆ str │
╞═════╪══════╪═════╡
│ 2   ┆ 7    ┆ b   │
│ 3   ┆ 8    ┆ c   │
│ 4   ┆ null ┆ d   │
└─────┴──────┴─────┘

Отфильтровать строки по нескольким условиям, объединённым операторами and/or:

>>> df.filter(
...     (pl.col("foo") < 3) & (pl.col("ham") == "a"),
... )
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

>>> df.filter(
...     (pl.col("foo") == 1) | (pl.col("ham") == "c"),
... )
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

Задать несколько фильтров, используя синтаксис *args:

>>> df.filter(
...     pl.col("foo") <= 2,
...     ~pl.col("ham").is_in(["b", "c"]),
... )
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 0   ┆ 0   ┆ f   │
└─────┴─────┴─────┘

Задать несколько фильтров, используя синтаксис **kwargs:

>>> df.filter(foo=2, ham="b")
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 2   ┆ 7   ┆ b   │
└─────┴─────┴─────┘

Отфильтровать строки, сравнивая два столбца друг с другом:

>>> df.filter(
...     pl.col("foo") == pl.col("bar"),
... )
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 0   ┆ 0   ┆ f   │
└─────┴─────┴─────┘

>>> df.filter(
...     pl.col("foo") != pl.col("bar"),
... )
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

Обратите внимание, что строка со значениями None отфильтровывается. Чтобы сохранить поведение Pandas, используйте:

>>> df.filter(
...     pl.col("foo").ne_missing(pl.col("bar")),
... )
shape: (5, 3)
┌──────┬──────┬─────┐
│ foo  ┆ bar  ┆ ham │
│ ---  ┆ ---  ┆ --- │
│ i64  ┆ i64  ┆ str │
╞══════╪══════╪═════╡
│ 1    ┆ 6    ┆ a   │
│ 2    ┆ 7    ┆ b   │
│ 3    ┆ 8    ┆ c   │
│ 4    ┆ null ┆ d   │
│ null ┆ 9    ┆ e   │
└──────┴──────┴─────┘

property flags: dict[str, dict[str, bool]]

Получить флаги, заданные для столбцов этого DataFrame.

Возвращает:

dict

Сопоставление имён столбцов с флагами столбцов.

fold(
    operation: Callable[[Series,
    Series],
    Series],
) → Series

Выполняет горизонтальную редукцию DataFrame.

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

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

• Int8 + String = String
• Float32 + Int64 = Float32
• Float32 + Float64 = Float64

Параметры:

operation

функция, принимающая два Series и возвращающая Series.

Примеры

Горизонтальное суммирование:

>>> df = pl.DataFrame(
...     {
...         "a": [2, 1, 3],
...         "b": [1, 2, 3],
...         "c": [1.0, 2.0, 3.0],
...     }
... )
>>> df.fold(lambda s1, s2: s1 + s2)
shape: (3,)
Series: 'a' [f64]
[
    4.0
    5.0
    9.0
]

Горизонтальное вычисление минимума:

>>> df = pl.DataFrame({"a": [2, 1, 3], "b": [1, 2, 3], "c": [1.0, 2.0, 3.0]})
>>> df.fold(lambda s1, s2: s1.zip_with(s1 < s2, s2))
shape: (3,)
Series: 'a' [f64]
[
    1.0
    1.0
    3.0
]

Горизонтальная конкатенация строк:

>>> df = pl.DataFrame(
...     {
...         "a": ["foo", "bar", None],
...         "b": [1, 2, 3],
...         "c": [1.0, 2.0, 3.0],
...     }
... )
>>> df.fold(lambda s1, s2: s1 + s2)
shape: (3,)
Series: 'a' [str]
[
    "foo11.0"
    "bar22.0"
    null
]

Горизонтальная логическая операция «ИЛИ», аналогичная .any() для строк:

>>> df = pl.DataFrame(
...     {
...         "a": [False, False, True],
...         "b": [False, True, False],
...     }
... )
>>> df.fold(lambda s1, s2: s1 | s2)
shape: (3,)
Series: 'a' [bool]
[
        false
        true
        true
]

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

Выбирает строки этого DataFrame по заданным индексам.

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

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

Параметры:

indices

Индексы выбираемых строк.

null_on_oob

Если значение равно true, то при выходе индекса за границы вместо ошибки будет создана строка null.

Примеры

>>> df = pl.DataFrame({"x": [2, 1, 0], "s": ["foo", "bar", "baz"]})
>>> df.gather([2, 0, 0])
shape: (3, 2)
┌─────┬─────┐
│ x   ┆ s   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 0   ┆ baz │
│ 2   ┆ foo │
│ 2   ┆ foo │
└─────┴─────┘

>>> df.gather([0, 10, 1], null_on_oob=True)
shape: (3, 2)
┌──────┬──────┐
│ x    ┆ s    │
│ ---  ┆ ---  │
│ i64  ┆ str  │
╞══════╪══════╡
│ 2    ┆ foo  │
│ null ┆ null │
│ 1    ┆ bar  │
└──────┴──────┘

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

Выбирает каждую n-ю строку DataFrame и возвращает их в виде нового DataFrame.

Параметры:

n

Извлекать каждую n-ю строку.

offset

Начальный индекс.

Примеры

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

>>> s.gather_every(2, offset=1)
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 2   ┆ 6   │
│ 4   ┆ 8   │
└─────┴─────┘

get_column(
    name: str,
    *,
    default: Any | NoDefault = <no_default>,
) → Series | Any

Получает столбец по имени.

Параметры:

name

Строковое имя извлекаемого столбца.

default

Значение, возвращаемое, если столбец не существует; если значение явно не задано, а столбец отсутствует, возникает исключение ColumnNotFoundError.

Возвращает:

Series (или произвольное значение по умолчанию, если оно указано).

См. также

to_series

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
>>> df.get_column("foo")
shape: (3,)
Series: 'foo' [i64]
[
    1
    2
    3
]

Обработка отсутствующего столбца: методу можно передать произвольное значение по умолчанию (в противном случае возникает исключение ColumnNotFoundError).

>>> df.get_column("baz", default=pl.Series("baz", ["?", "?", "?"]))
shape: (3,)
Series: 'baz' [str]
[
    "?"
    "?"
    "?"
]
>>> res = df.get_column("baz", default=None)
>>> res is None
True

get_column_index(
    name: str,
) → int

Находит индекс столбца по имени.

Параметры:

name

Имя искомого столбца.

Примеры

>>> df = pl.DataFrame(
...     {"foo": [1, 2, 3], "bar": [6, 7, 8], "ham": ["a", "b", "c"]}
... )
>>> df.get_column_index("ham")
2
>>> df.get_column_index("sandwich")  
ColumnNotFoundError: sandwich

get_columns() → list[Series]

Возвращает DataFrame в виде списка Series.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
>>> df.get_columns()
[shape: (3,)
Series: 'foo' [i64]
[
        1
        2
        3
], shape: (3,)
Series: 'bar' [i64]
[
        4
        5
        6
]]

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [0.5, 4, 10, 13],
...         "c": [True, True, False, True],
...     }
... )
>>> df.get_columns()
[shape: (4,)
Series: 'a' [i64]
[
    1
    2
    3
    4
], shape: (4,)
Series: 'b' [f64]
[
    0.5
    4.0
    10.0
    13.0
], shape: (4,)
Series: 'c' [bool]
[
    true
    true
    false
    true
]]

glimpse(
    *,
    max_items_per_column: int = 10,
    max_colname_length: int = 50,
    return_type: Literal['frame',
    'self',
    'string'] | None = None,
) → str | DataFrame | None

Возвращает наглядный предварительный просмотр DataFrame.

Форматирование выводит по одной строке на столбец, чтобы широкие DataFrame отображались аккуратно. В каждой строке указаны имя столбца, тип данных и несколько первых значений.

Изменено в версии 1.35.0: Параметр return_as_string переименован в return_type и теперь принимает строковые значения 'string' и 'frame' вместо логических значений True или False.

Параметры:

max_items_per_column

Максимальное количество элементов, отображаемых для каждого столбца.

max_colname_length

Максимальная длина отображаемых имён столбцов; более длинные значения обрезаются с добавлением многоточия.

return_type

Изменяет формат возвращаемого значения:

• None (по умолчанию): Выводит результат glimpse в stdout и возвращает None.
• "self": Выводит результат glimpse в stdout и возвращает исходный фрейм.
• "frame": Возвращает результат glimpse в виде нового DataFrame.
• "string": Возвращает результат glimpse в виде строки.

См. также

describe, head, tail

Примеры

>>> from datetime import date
>>> df = pl.DataFrame(
...     {
...         "a": [1.0, 2.8, 3.0],
...         "b": [4, 5, None],
...         "c": [True, False, True],
...         "d": [None, "b", "c"],
...         "e": ["usd", "eur", None],
...         "f": [date(2020, 1, 1), date(2021, 1, 2), date(2022, 1, 1)],
...     }
... )

Вывести результат в формате glimpse в stdout и вернуть None:

>>> res = df.glimpse()
Rows: 3
Columns: 6
$ a  <f64> 1.0, 2.8, 3.0
$ b  <i64> 4, 5, null
$ c <bool> True, False, True
$ d  <str> null, 'b', 'c'
$ e  <str> 'usd', 'eur', null
$ f <date> 2020-01-01, 2021-01-02, 2022-01-01
>>> res is None
True

Вернуть результат glimpse в виде строки:

>>> res = df.glimpse(return_type="string")
>>> isinstance(res, str)
True

Вернуть результат glimpse в виде DataFrame:

>>> df.glimpse(return_type="frame")
shape: (6, 3)
┌────────┬───────┬─────────────────────────────────┐
│ column ┆ dtype ┆ values                          │
│ ---    ┆ ---   ┆ ---                             │
│ str    ┆ str   ┆ list[str]                       │
╞════════╪═══════╪═════════════════════════════════╡
│ a      ┆ f64   ┆ ["1.0", "2.8", "3.0"]           │
│ b      ┆ i64   ┆ ["4", "5", null]                │
│ c      ┆ bool  ┆ ["True", "False", "True"]       │
│ d      ┆ str   ┆ [null, "'b'", "'c'"]            │
│ e      ┆ str   ┆ ["'usd'", "'eur'", null]        │
│ f      ┆ date  ┆ ["2020-01-01", "2021-01-02", "… │
└────────┴───────┴─────────────────────────────────┘

Вывести результат в формате glimpse в stdout и вернуть исходный фрейм:

>>> res = df.glimpse(return_type="self")
Rows: 3
Columns: 6
$ a  <f64> 1.0, 2.8, 3.0
$ b  <i64> 4, 5, null
$ c <bool> True, False, True
$ d  <str> null, 'b', 'c'
$ e  <str> 'usd', 'eur', null
$ f <date> 2020-01-01, 2021-01-02, 2022-01-01
>>> res
shape: (3, 6)
┌─────┬──────┬───────┬──────┬──────┬────────────┐
│ a   ┆ b    ┆ c     ┆ d    ┆ e    ┆ f          │
│ --- ┆ ---  ┆ ---   ┆ ---  ┆ ---  ┆ ---        │
│ f64 ┆ i64  ┆ bool  ┆ str  ┆ str  ┆ date       │
╞═════╪══════╪═══════╪══════╪══════╪════════════╡
│ 1.0 ┆ 4    ┆ true  ┆ null ┆ usd  ┆ 2020-01-01 │
│ 2.8 ┆ 5    ┆ false ┆ b    ┆ eur  ┆ 2021-01-02 │
│ 3.0 ┆ null ┆ true  ┆ c    ┆ null ┆ 2022-01-01 │
└─────┴──────┴───────┴──────┴──────┴────────────┘

group_by(
    *by: IntoExpr | Iterable[IntoExpr],
    maintain_order: bool = False,
    **named_by: IntoExpr,
) → GroupBy

Начинает группировку.

Параметры:

*by

Столбец или столбцы для группировки. Принимаются выражения. Строки интерпретируются как имена столбцов.

maintain_order

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

Примечание

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

**named_by

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

Возвращает:

GroupBy

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

Примеры

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

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

Задать maintain_order=True, чтобы порядок групп соответствовал порядку входных данных.

>>> df.group_by("a", maintain_order=True).agg(pl.col("c"))
shape: (3, 2)
┌─────┬───────────┐
│ a   ┆ c         │
│ --- ┆ ---       │
│ str ┆ list[i64] │
╞═════╪═══════════╡
│ a   ┆ [5, 3]    │
│ b   ┆ [4, 2]    │
│ c   ┆ [1]       │
└─────┴───────────┘

Сгруппировать по нескольким столбцам, передав список их имён.

>>> df.group_by(["a", "b"]).agg(pl.max("c"))  
shape: (4, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 1   ┆ 5   │
│ b   ┆ 2   ┆ 4   │
│ b   ┆ 3   ┆ 2   │
│ c   ┆ 3   ┆ 1   │
└─────┴─────┴─────┘

Для группировки по нескольким столбцам можно также использовать позиционные аргументы. Допускаются и выражения.

>>> df.group_by("a", pl.col("b") // 2).agg(pl.col("c").mean())  
shape: (3, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ f64 │
╞═════╪═════╪═════╡
│ a   ┆ 0   ┆ 4.0 │
│ b   ┆ 1   ┆ 3.0 │
│ c   ┆ 1   ┆ 1.0 │
└─────┴─────┴─────┘

Объект GroupBy, возвращаемый этим методом, является итерируемым: он возвращает имя и данные каждой группы.

>>> for name, data in df.group_by("a"):  
...     print(name)
...     print(data)
('a',)
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 1   ┆ 5   │
│ a   ┆ 1   ┆ 3   │
└─────┴─────┴─────┘
('b',)
shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ b   ┆ 2   ┆ 4   │
│ b   ┆ 3   ┆ 2   │
└─────┴─────┴─────┘
('c',)
shape: (1, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ c   ┆ 3   ┆ 1   │
└─────┴─────┴─────┘

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

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

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

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

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

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

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

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

Параметры:

index_column

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

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

every

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

period

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

offset

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

include_boundaries

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

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

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

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

Определяет метку окна:

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

group_by

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

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

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

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

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

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

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

Возвращает:

DynamicGroupBy

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

См. также

rolling

Примечания

1. Если вы переходите с pandas, то

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

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

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

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

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

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

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

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

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

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

Примеры

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

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

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

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

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

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

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

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

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

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

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

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

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

hash_rows(
    seed: int = 0,
    seed_1: int | None = None,
    seed_2: int | None = None,
    seed_3: int | None = None,
) → Series

Хеширует и объединяет строки этого DataFrame.

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

Параметры:

seed

Начальное значение генератора случайных чисел. По умолчанию равно 0.

seed_1

Начальное значение генератора случайных чисел. Если не задано, по умолчанию равно seed.

seed_2

Начальное значение генератора случайных чисел. Если не задано, по умолчанию равно seed.

seed_3

Начальное значение генератора случайных чисел. Если не задано, по умолчанию равно seed.

Примечания

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, None, 3, 4],
...         "ham": ["a", "b", None, "d"],
...     }
... )
>>> df.hash_rows(seed=42)  
shape: (4,)
Series: '' [u64]
[
    10783150408545073287
    1438741209321515184
    10047419486152048166
    2047317070637311557
]

head(
    n: int = 5,
) → DataFrame

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

Параметры:

n

Количество возвращаемых строк. Если передано отрицательное значение, возвращаются все строки, кроме последних abs(n).

См. также

tail, glimpse, slice

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> df.head(3)
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

Передайте отрицательное значение, чтобы получить все строки, except последние abs(n).

>>> df.head(-3)
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
└─────┴─────┴─────┘

property height: int

Получает количество строк.

Возвращает:

int

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5]})
>>> df.height
5

hstack(
    columns: list[Series] | DataFrame,
    *,
    in_place: bool = False,
) → DataFrame

Возвращает новый DataFrame, расширенный по горизонтали за счёт добавления нескольких Series.

Параметры:

columns

Series для добавления.

in_place

Изменить объект на месте.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> x = pl.Series("apple", [10, 20, 30])
>>> df.hstack([x])
shape: (3, 4)
┌─────┬─────┬─────┬───────┐
│ foo ┆ bar ┆ ham ┆ apple │
│ --- ┆ --- ┆ --- ┆ ---   │
│ i64 ┆ i64 ┆ str ┆ i64   │
╞═════╪═════╪═════╪═══════╡
│ 1   ┆ 6   ┆ a   ┆ 10    │
│ 2   ┆ 7   ┆ b   ┆ 20    │
│ 3   ┆ 8   ┆ c   ┆ 30    │
└─────┴─────┴─────┴───────┘

insert_column(
    index: int,
    column: IntoExprColumn,
) → DataFrame

Вставляет Series (или выражение) по заданному индексу столбца.

Операция выполняется на месте.

Параметры:

index

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

column

Series или выражение для вставки.

Примеры

Вставить столбец Series по заданному индексу:

>>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
>>> s = pl.Series("baz", [97, 98, 99])
>>> df.insert_column(1, s)
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ baz ┆ bar │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 97  ┆ 4   │
│ 2   ┆ 98  ┆ 5   │
│ 3   ┆ 99  ┆ 6   │
└─────┴─────┴─────┘

Вставить столбец-выражение по заданному индексу:

>>> df = pl.DataFrame(
...     {"a": [2, 4, 2], "b": [0.5, 4, 10], "c": ["xx", "yy", "zz"]}
... )
>>> expr = (pl.col("b") / pl.col("a")).alias("b_div_a")
>>> df.insert_column(2, expr)
shape: (3, 4)
┌─────┬──────┬─────────┬─────┐
│ a   ┆ b    ┆ b_div_a ┆ c   │
│ --- ┆ ---  ┆ ---     ┆ --- │
│ i64 ┆ f64  ┆ f64     ┆ str │
╞═════╪══════╪═════════╪═════╡
│ 2   ┆ 0.5  ┆ 0.25    ┆ xx  │
│ 4   ┆ 4.0  ┆ 1.0     ┆ yy  │
│ 2   ┆ 10.0 ┆ 5.0     ┆ zz  │
└─────┴──────┴─────────┴─────┘

interpolate() → DataFrame

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

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, None, 9, 10],
...         "bar": [6, 7, 9, None],
...         "baz": [1, None, None, 9],
...     }
... )
>>> df.interpolate()
shape: (4, 3)
┌──────┬──────┬──────────┐
│ foo  ┆ bar  ┆ baz      │
│ ---  ┆ ---  ┆ ---      │
│ f64  ┆ f64  ┆ f64      │
╞══════╪══════╪══════════╡
│ 1.0  ┆ 6.0  ┆ 1.0      │
│ 5.0  ┆ 7.0  ┆ 3.666667 │
│ 9.0  ┆ 9.0  ┆ 6.333333 │
│ 10.0 ┆ null ┆ 9.0      │
└──────┴──────┴──────────┘

is_duplicated() → Series

Получает маску всех дублирующихся строк в этом DataFrame.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 1],
...         "b": ["x", "y", "z", "x"],
...     }
... )
>>> df.is_duplicated()
shape: (4,)
Series: '' [bool]
[
        true
        false
        false
        true
]

Эту маску можно использовать для визуализации дублирующихся строк следующим образом:

>>> df.filter(df.is_duplicated())
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 1   ┆ x   │
│ 1   ┆ x   │
└─────┴─────┘

is_empty() → bool

Возвращает True, если DataFrame не содержит строк.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
>>> df.is_empty()
False
>>> df.filter(pl.col("foo") > 99).is_empty()
True

is_sorted(
    by: str | Iterable[str],
    *more_by: str,
    descending: bool | Sequence[bool] = False,
    nulls_last: bool | Sequence[bool] = False,
) → bool

Проверяет, отсортирован ли DataFrame по заданным столбцам.

Параметры:

by

Имя столбца или имена столбцов для проверки.

*more_by

Дополнительные имена столбцов.

descending

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

nulls_last

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

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3], "b": [5, 4, 3]})
>>> df.is_sorted("a")
True
>>> df.is_sorted("b", descending=True)
True
>>> df.is_sorted("a", "b")
True

is_unique() → Series

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 1],
...         "b": ["x", "y", "z", "x"],
...     }
... )
>>> df.is_unique()
shape: (4,)
Series: '' [bool]
[
        false
        true
        true
        false
]

Эту маску можно использовать для визуализации уникальных строк следующим образом:

>>> df.filter(df.is_unique())
shape: (2, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 2   ┆ y   │
│ 3   ┆ z   │
└─────┴─────┘

item(
    row: int | None = None,
    column: int | str | None = None,
) → Any

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

Параметры:

row

Необязательный индекс строки.

column

Необязательный индекс или имя столбца.

См. также

row

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

Примечания

Если row/col не указаны, метод эквивалентен df[0,0] с проверкой, что форма равна (1,1). Если row/col указаны, метод эквивалентен df[row,col].

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
>>> df.select((pl.col("a") * pl.col("b")).sum()).item()
32
>>> df.item(1, 1)
5
>>> df.item(2, "b")
6

iter_columns() → Iterator[Series]

Возвращает итератор по столбцам этого DataFrame.

Генерирует:

Series

Примечания

Подумайте, можно ли вместо этого использовать all(). Если это возможно, такой вариант будет эффективнее.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 3, 5],
...         "b": [2, 4, 6],
...     }
... )
>>> [s.name for s in df.iter_columns()]
['a', 'b']

Если вы используете этот метод для изменения столбцов DataFrame, например:

>>> # Do NOT do this
>>> pl.DataFrame(column * 2 for column in df.iter_columns())
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 2   ┆ 4   │
│ 6   ┆ 8   │
│ 10  ┆ 12  │
└─────┴─────┘

подумайте, можно ли вместо этого использовать all():

>>> df.select(pl.all() * 2)
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 2   ┆ 4   │
│ 6   ┆ 8   │
│ 10  ┆ 12  │
└─────┴─────┘

iter_rows(
    *,
    named: bool = False,
    buffer_size: int = 512,
) → Iterator[tuple[Any, ...]] | Iterator[dict[str, Any]]

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

Параметры:

named

Возвращать словари вместо кортежей. Словари сопоставляют имена столбцов со значениями строк. Это затратнее, чем возврат обычного кортежа, но позволяет обращаться к значениям по имени столбца.

buffer_size

Определяет количество строк, буферизуемых внутри при переборе данных. Изменяйте это значение только в особых случаях, когда значение по умолчанию не подходит для вашего способа доступа к данным: буферизация значительно повышает скорость (примерно в 2–4 раза). Если задать ноль, буферизация строк отключится (не рекомендуется).

Генерирует:

итератор кортежей (по умолчанию) или словарей (если задано named) со значениями строк в типах Python

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

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

См. также

rows

Материализует все данные фрейма в виде списка строк (может быть затратным).

rows_by_key

Материализует данные фрейма в виде словаря с индексом по ключам.

Примечания

Если вы работаете с временными значениями точности ns, учитывайте, что Python изначально поддерживает точность только до μs; при преобразовании в Python значения точности ns будут усечены до микросекунд. Если это важно для вашего случая использования, экспортируйте данные в другой формат (например, Arrow или NumPy).

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 3, 5],
...         "b": [2, 4, 6],
...     }
... )
>>> [row[0] for row in df.iter_rows()]
[1, 3, 5]
>>> [row["b"] for row in df.iter_rows(named=True)]
[2, 4, 6]

iter_slices(
    n_rows: int = 10000,
) → Iterator[DataFrame]

Возвращает итератор неперекрывающихся срезов исходного DataFrame без копирования данных.

Параметры:

n_rows

Определяет количество строк в каждом срезе DataFrame.

См. также

iter_rows

Итератор по строкам данных фрейма (не материализует все строки).

partition_by

Разбивает DataFrame на несколько частей, сгруппированных по группам.

Примеры

>>> from datetime import date
>>> df = pl.DataFrame(
...     data={
...         "a": range(17_500),
...         "b": date(2023, 1, 1),
...         "c": "klmnoopqrstuvwxyz",
...     },
...     schema_overrides={"a": pl.Int32},
... )
>>> for idx, frame in enumerate(df.iter_slices()):
...     print(f"{type(frame).__name__}:[{idx}]:{len(frame)}")
DataFrame:[0]:10000
DataFrame:[1]:7500

Использование iter_slices — эффективный способ перебирать DataFrame частями и экспортировать или преобразовывать фрейм в любой поддерживаемый формат; например, в RecordBatches:

>>> for frame in df.iter_slices(n_rows=15_000):
...     record_batch = frame.to_arrow().to_batches()[0]
...     print(f"{record_batch.schema}\n<< {len(record_batch)}")
a: int32
b: date32[day]
c: large_string
<< 15000
a: int32
b: date32[day]
c: large_string
<< 2500

join(
    other: DataFrame,
    on: str | Expr | Sequence[str | Expr] | None = None,
    how: JoinStrategy = 'inner',
    *,
    left_on: str | Expr | Sequence[str | Expr] | None = None,
    right_on: str | Expr | Sequence[str | Expr] | None = None,
    suffix: str = '_right',
    validate: JoinValidation = 'm:m',
    nulls_equal: bool = False,
    coalesce: bool | None = None,
    maintain_order: MaintainOrderJoin | None = None,
    build_side: JoinBuildSide = 'auto',
) → DataFrame

Объединяет таблицы в стиле SQL.

Изменено в версии 1.24: Параметр join_nulls переименован в nulls_equal.

Параметры:

other

DataFrame для объединения.

on

Имя или имена столбцов для объединения в обоих DataFrame. Если задано, left_on и right_on должны иметь значение None. Не следует указывать, если задан параметр how='cross'.

how{‘inner’, ‘left’, ‘right’, ‘full’, ‘semi’, ‘anti’, ‘cross’}

Стратегия объединения.

inner	(По умолчанию) Возвращает строки, содержащие совпадающие значения в обеих таблицах.
left	Возвращает все строки из левой таблицы и соответствующие им строки из правой таблицы.
right	Возвращает все строки из правой таблицы и соответствующие им строки из левой таблицы.
full	Возвращает все строки из обеих таблиц, объединяя совпадающие строки и заполняя несовпадающие значения значениями null.
cross	Возвращает декартово произведение строк обеих таблиц.
semi	Возвращает строки из левой таблицы, для которых есть совпадения в правой таблице. Столбцы из правой таблицы не возвращаются.
anti	Возвращает строки из левой таблицы, для которых нет совпадений в правой таблице. Столбцы из правой таблицы не возвращаются.

left_on

Имя или имена столбцов для объединения в левой таблице.

right_on

Имя или имена столбцов для объединения в правой таблице.

suffix

Суффикс, добавляемый к столбцам с повторяющимися именами.

validate: {‘m:m’, ‘m:1’, ‘1:m’, ‘1:1’}

Проверяет, соответствует ли объединение указанному типу.

m:m	(По умолчанию) «Многие ко многим» (по умолчанию). Проверки не выполняются.
1:1	«Один к одному». Проверяет уникальность ключей объединения в обоих наборах данных.
1:m	«Один ко многим». Проверяет уникальность ключей объединения в левом наборе данных.
m:1	«Многие к одному». Проверяет уникальность ключей объединения в правом наборе данных.

Примечание

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

nulls_equal

Объединять по значениям null. По умолчанию значения null никогда не считаются совпадающими.

coalesce

Поведение коалесценции (объединения столбцов для объединения).

None	(По умолчанию) Выполнять коалесценцию, если не указан how='full'.
True	Всегда объединять столбцы для объединения.
False	Никогда не объединять столбцы для объединения.

Примечание

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

maintain_order{‘none’, ‘left’, ‘right’, ‘left_right’, ‘right_left’}

Порядок строк какого DataFrame следует сохранить, если это необходимо. Не полагайтесь на наблюдаемый порядок без явной установки этого параметра: ваш код может перестать работать в будущем выпуске. Отказ от указания порядка может повысить производительность.

none	(По умолчанию) Определённый порядок не требуется. Порядок может различаться в разных версиях Polars или даже при разных запусках.
left	Сохраняет порядок строк левого DataFrame.
right	Сохраняет порядок строк правого DataFrame.
left_right	Сначала сохраняет порядок левого DataFrame, затем правого.
right_left	Сначала сохраняет порядок правого DataFrame, затем левого.

build_side: {‘auto’, ‘prefer_left’, ‘prefer_right’, ‘force_left’, ‘force_right’}

Сторона объединения, используемая в качестве строящей стороны. Вероятно, эта сторона будет храниться в памяти в виде хеш-таблицы. Если не выбран вариант force_, выбранная сторона может различаться в разных версиях Polars или даже при разных запусках.

auto	(По умолчанию) Предоставить Polars выбор строящей стороны.
prefer_left	Использовать левую сторону, если нет веских причин считать, что правая сторона меньше.
prefer_right	Использовать правую сторону, если нет веских причин считать, что левая сторона меньше.
force_left	Всегда использовать левую сторону.
force_right	Всегда использовать правую сторону.

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

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

См. также

join_asof

join_where

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> other_df = pl.DataFrame(
...     {
...         "apple": ["x", "y", "z"],
...         "ham": ["a", "b", "d"],
...     }
... )
>>> df.join(other_df, on="ham")
shape: (2, 4)
┌─────┬─────┬─────┬───────┐
│ foo ┆ bar ┆ ham ┆ apple │
│ --- ┆ --- ┆ --- ┆ ---   │
│ i64 ┆ f64 ┆ str ┆ str   │
╞═════╪═════╪═════╪═══════╡
│ 1   ┆ 6.0 ┆ a   ┆ x     │
│ 2   ┆ 7.0 ┆ b   ┆ y     │
└─────┴─────┴─────┴───────┘

>>> df.join(other_df, on="ham", how="full")
shape: (4, 5)
┌──────┬──────┬──────┬───────┬───────────┐
│ foo  ┆ bar  ┆ ham  ┆ apple ┆ ham_right │
│ ---  ┆ ---  ┆ ---  ┆ ---   ┆ ---       │
│ i64  ┆ f64  ┆ str  ┆ str   ┆ str       │
╞══════╪══════╪══════╪═══════╪═══════════╡
│ 1    ┆ 6.0  ┆ a    ┆ x     ┆ a         │
│ 2    ┆ 7.0  ┆ b    ┆ y     ┆ b         │
│ null ┆ null ┆ null ┆ z     ┆ d         │
│ 3    ┆ 8.0  ┆ c    ┆ null  ┆ null      │
└──────┴──────┴──────┴───────┴───────────┘

>>> df.join(other_df, on="ham", how="full", coalesce=True)
shape: (4, 4)
┌──────┬──────┬─────┬───────┐
│ foo  ┆ bar  ┆ ham ┆ apple │
│ ---  ┆ ---  ┆ --- ┆ ---   │
│ i64  ┆ f64  ┆ str ┆ str   │
╞══════╪══════╪═════╪═══════╡
│ 1    ┆ 6.0  ┆ a   ┆ x     │
│ 2    ┆ 7.0  ┆ b   ┆ y     │
│ null ┆ null ┆ d   ┆ z     │
│ 3    ┆ 8.0  ┆ c   ┆ null  │
└──────┴──────┴─────┴───────┘

>>> df.join(other_df, on="ham", how="left")
shape: (3, 4)
┌─────┬─────┬─────┬───────┐
│ foo ┆ bar ┆ ham ┆ apple │
│ --- ┆ --- ┆ --- ┆ ---   │
│ i64 ┆ f64 ┆ str ┆ str   │
╞═════╪═════╪═════╪═══════╡
│ 1   ┆ 6.0 ┆ a   ┆ x     │
│ 2   ┆ 7.0 ┆ b   ┆ y     │
│ 3   ┆ 8.0 ┆ c   ┆ null  │
└─────┴─────┴─────┴───────┘

>>> df.join(other_df, on="ham", how="semi")
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6.0 ┆ a   │
│ 2   ┆ 7.0 ┆ b   │
└─────┴─────┴─────┘

>>> df.join(other_df, on="ham", how="anti")
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 3   ┆ 8.0 ┆ c   │
└─────┴─────┴─────┘

>>> df.join(other_df, how="cross")
shape: (9, 5)
┌─────┬─────┬─────┬───────┬───────────┐
│ foo ┆ bar ┆ ham ┆ apple ┆ ham_right │
│ --- ┆ --- ┆ --- ┆ ---   ┆ ---       │
│ i64 ┆ f64 ┆ str ┆ str   ┆ str       │
╞═════╪═════╪═════╪═══════╪═══════════╡
│ 1   ┆ 6.0 ┆ a   ┆ x     ┆ a         │
│ 1   ┆ 6.0 ┆ a   ┆ y     ┆ b         │
│ 1   ┆ 6.0 ┆ a   ┆ z     ┆ d         │
│ 2   ┆ 7.0 ┆ b   ┆ x     ┆ a         │
│ 2   ┆ 7.0 ┆ b   ┆ y     ┆ b         │
│ 2   ┆ 7.0 ┆ b   ┆ z     ┆ d         │
│ 3   ┆ 8.0 ┆ c   ┆ x     ┆ a         │
│ 3   ┆ 8.0 ┆ c   ┆ y     ┆ b         │
│ 3   ┆ 8.0 ┆ c   ┆ z     ┆ d         │
└─────┴─────┴─────┴───────┴───────────┘

join_asof(
    other: DataFrame,
    *,
    left_on: str | None | Expr = None,
    right_on: str | None | Expr = None,
    on: str | None | Expr = None,
    by_left: str | Sequence[str] | None = None,
    by_right: str | Sequence[str] | None = None,
    by: str | Sequence[str] | None = None,
    strategy: AsofJoinStrategy = 'backward',
    suffix: str = '_right',
    tolerance: str | int | float | timedelta | None = None,
    allow_parallel: bool = True,
    force_parallel: bool = False,
    coalesce: bool = True,
    allow_exact_matches: bool = True,
    check_sortedness: bool = True,
) → DataFrame

Выполняет объединение по принципу asof.

Оно похоже на левое объединение, за исключением того, что совпадение ищется по ближайшему ключу, а не по равным ключам.

Оба DataFrame должны быть отсортированы по ключу on (в каждой группе by, если она указана).

Для каждой строки левого DataFrame:

• При поиске «назад» выбирается последняя строка правого DataFrame, ключ ‘on’ которой меньше или равен ключу левой строки.
• При поиске «вперёд» выбирается первая строка правого DataFrame, ключ ‘on’ которой больше или равен ключу левой строки.
• При поиске «ближайшего» выбирается последняя строка правого DataFrame, значение которой ближе всего к ключу левой строки. Поиск ближайшего значения по строковым ключам в настоящее время не поддерживается.

По умолчанию используется поиск «назад».

Параметры:

other

Ленивый DataFrame для объединения.

left_on

Столбец объединения левого DataFrame.

right_on

Столбец объединения правого DataFrame.

on

Столбец объединения обоих DataFrame. Если задано, left_on и right_on должны иметь значение None.

by_left

Сначала выполнить объединение по этим столбцам, а затем объединение asof.

by_right

Сначала выполнить объединение по этим столбцам, а затем объединение asof.

by

Сначала выполнить объединение по этим столбцам, а затем объединение asof.

strategy{‘backward’, ‘forward’, ‘nearest’}

Стратегия объединения.

suffix

Суффикс, добавляемый к столбцам с повторяющимися именами.

tolerance

Числовой допуск. Если задан этот параметр, объединение будет выполнено, только если близкие ключи находятся в пределах указанного расстояния. При выполнении объединения asof по столбцам типа “Date”, “Datetime”, “Duration” или “Time” используйте объект datetime.timedelta либо следующую строковую запись:

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

Или объедините их: “3d12h4m25s” # 3 дня, 12 часов, 4 минуты и 25 секунд

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

allow_parallel

Разрешить физическому плану при необходимости вычислять данные обоих DataFrame до этапа объединения параллельно.

force_parallel

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

coalesce

Поведение коалесценции (объединения столбцов on / left_on / right_on):

• True: Всегда объединять столбцы для объединения.
• False: Никогда не объединять столбцы для объединения.

Обратите внимание: объединение по любым выражениям, кроме col, отключает коалесценцию.

allow_exact_matches

Допустимы ли точные совпадения в качестве предикатов объединения.

• If True, allow matching with the same on value

  (то есть меньше или равно / больше или равно)

• If False, don’t match the same on value

  (то есть строго меньше / строго больше).

check_sortedness

Проверяет сортировку ключей asof. Если ключи не отсортированы, Polars выдаст ошибку. В настоящее время движок in-memory не может проверить сортировку, если указаны группы ‘by’. Движок streaming проверяет сортировку только обрабатываемых им строк.

См. также

join

join_where

Примеры

>>> from datetime import date
>>> gdp = pl.DataFrame(
...     {
...         "date": pl.date_range(
...             date(2016, 1, 1),
...             date(2020, 1, 1),
...             "1y",
...             eager=True,
...         ),
...         "gdp": [4164, 4411, 4566, 4696, 4827],
...     }
... )
>>> gdp
shape: (5, 2)
┌────────────┬──────┐
│ date       ┆ gdp  │
│ ---        ┆ ---  │
│ date       ┆ i64  │
╞════════════╪══════╡
│ 2016-01-01 ┆ 4164 │
│ 2017-01-01 ┆ 4411 │
│ 2018-01-01 ┆ 4566 │
│ 2019-01-01 ┆ 4696 │
│ 2020-01-01 ┆ 4827 │
└────────────┴──────┘

>>> population = pl.DataFrame(
...     {
...         "date": [date(2016, 3, 1), date(2018, 8, 1), date(2019, 1, 1)],
...         "population": [82.19, 82.66, 83.12],
...     }
... ).sort("date")
>>> population
shape: (3, 2)
┌────────────┬────────────┐
│ date       ┆ population │
│ ---        ┆ ---        │
│ date       ┆ f64        │
╞════════════╪════════════╡
│ 2016-03-01 ┆ 82.19      │
│ 2018-08-01 ┆ 82.66      │
│ 2019-01-01 ┆ 83.12      │
└────────────┴────────────┘

Обратите внимание, что даты не совсем совпадают. Если объединить их с помощью join_asof и strategy='backward', каждая дата из population, для которой нет точного совпадения, будет сопоставлена с ближайшей более ранней датой из gdp:

>>> population.join_asof(gdp, on="date", strategy="backward")
shape: (3, 3)
┌────────────┬────────────┬──────┐
│ date       ┆ population ┆ gdp  │
│ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ i64  │
╞════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 4164 │
│ 2018-08-01 ┆ 82.66      ┆ 4566 │
│ 2019-01-01 ┆ 83.12      ┆ 4696 │
└────────────┴────────────┴──────┘

Обратите внимание:

• дата 2016-03-01 из population сопоставляется с 2016-01-01 из gdp;
• дата 2018-08-01 из population сопоставляется с 2018-01-01 из gdp.

Это можно проверить, передав coalesce=False:

>>> population.join_asof(gdp, on="date", strategy="backward", coalesce=False)
shape: (3, 4)
┌────────────┬────────────┬────────────┬──────┐
│ date       ┆ population ┆ date_right ┆ gdp  │
│ ---        ┆ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ date       ┆ i64  │
╞════════════╪════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 2016-01-01 ┆ 4164 │
│ 2018-08-01 ┆ 82.66      ┆ 2018-01-01 ┆ 4566 │
│ 2019-01-01 ┆ 83.12      ┆ 2019-01-01 ┆ 4696 │
└────────────┴────────────┴────────────┴──────┘

Если вместо этого использовать strategy='forward', каждая дата из population, для которой нет точного совпадения, будет сопоставлена с ближайшей более поздней датой из gdp:

>>> population.join_asof(gdp, on="date", strategy="forward")
shape: (3, 3)
┌────────────┬────────────┬──────┐
│ date       ┆ population ┆ gdp  │
│ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ i64  │
╞════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 4411 │
│ 2018-08-01 ┆ 82.66      ┆ 4696 │
│ 2019-01-01 ┆ 83.12      ┆ 4696 │
└────────────┴────────────┴──────┘

Обратите внимание:

• дата 2016-03-01 из population сопоставляется с 2017-01-01 из gdp;
• дата 2018-08-01 из population сопоставляется с 2019-01-01 из gdp.

Наконец, strategy='nearest' даёт сочетание двух приведённых выше результатов: каждая дата из population, для которой нет точного совпадения, сопоставляется с ближайшей датой из gdp, независимо от того, раньше она или позже:

>>> population.join_asof(gdp, on="date", strategy="nearest")
shape: (3, 3)
┌────────────┬────────────┬──────┐
│ date       ┆ population ┆ gdp  │
│ ---        ┆ ---        ┆ ---  │
│ date       ┆ f64        ┆ i64  │
╞════════════╪════════════╪══════╡
│ 2016-03-01 ┆ 82.19      ┆ 4164 │
│ 2018-08-01 ┆ 82.66      ┆ 4696 │
│ 2019-01-01 ┆ 83.12      ┆ 4696 │
└────────────┴────────────┴──────┘

Обратите внимание:

• дата 2016-03-01 из population сопоставляется с 2016-01-01 из gdp;
• дата 2018-08-01 из population сопоставляется с 2019-01-01 из gdp.

Аргумент by позволяет сначала выполнить объединение по другому столбцу, а затем объединение asof. В этом примере сначала выполняется объединение по country, а затем, как и выше, объединение asof по дате.

>>> gdp_dates = pl.date_range(  # fmt: skip
...     date(2016, 1, 1), date(2020, 1, 1), "1y", eager=True
... )
>>> gdp2 = pl.DataFrame(
...     {
...         "country": ["Germany"] * 5 + ["Netherlands"] * 5,
...         "date": pl.concat([gdp_dates, gdp_dates]),
...         "gdp": [4164, 4411, 4566, 4696, 4827, 784, 833, 914, 910, 909],
...     }
... ).sort("country", "date")
>>>
>>> gdp2
shape: (10, 3)
┌─────────────┬────────────┬──────┐
│ country     ┆ date       ┆ gdp  │
│ ---         ┆ ---        ┆ ---  │
│ str         ┆ date       ┆ i64  │
╞═════════════╪════════════╪══════╡
│ Germany     ┆ 2016-01-01 ┆ 4164 │
│ Germany     ┆ 2017-01-01 ┆ 4411 │
│ Germany     ┆ 2018-01-01 ┆ 4566 │
│ Germany     ┆ 2019-01-01 ┆ 4696 │
│ Germany     ┆ 2020-01-01 ┆ 4827 │
│ Netherlands ┆ 2016-01-01 ┆ 784  │
│ Netherlands ┆ 2017-01-01 ┆ 833  │
│ Netherlands ┆ 2018-01-01 ┆ 914  │
│ Netherlands ┆ 2019-01-01 ┆ 910  │
│ Netherlands ┆ 2020-01-01 ┆ 909  │
└─────────────┴────────────┴──────┘
>>> pop2 = pl.DataFrame(
...     {
...         "country": ["Germany"] * 3 + ["Netherlands"] * 3,
...         "date": [
...             date(2016, 3, 1),
...             date(2018, 8, 1),
...             date(2019, 1, 1),
...             date(2016, 3, 1),
...             date(2018, 8, 1),
...             date(2019, 1, 1),
...         ],
...         "population": [82.19, 82.66, 83.12, 17.11, 17.32, 17.40],
...     }
... ).sort("country", "date")
>>>
>>> pop2
shape: (6, 3)
┌─────────────┬────────────┬────────────┐
│ country     ┆ date       ┆ population │
│ ---         ┆ ---        ┆ ---        │
│ str         ┆ date       ┆ f64        │
╞═════════════╪════════════╪════════════╡
│ Germany     ┆ 2016-03-01 ┆ 82.19      │
│ Germany     ┆ 2018-08-01 ┆ 82.66      │
│ Germany     ┆ 2019-01-01 ┆ 83.12      │
│ Netherlands ┆ 2016-03-01 ┆ 17.11      │
│ Netherlands ┆ 2018-08-01 ┆ 17.32      │
│ Netherlands ┆ 2019-01-01 ┆ 17.4       │
└─────────────┴────────────┴────────────┘
>>> pop2.join_asof(gdp2, by="country", on="date", strategy="nearest")
shape: (6, 4)
┌─────────────┬────────────┬────────────┬──────┐
│ country     ┆ date       ┆ population ┆ gdp  │
│ ---         ┆ ---        ┆ ---        ┆ ---  │
│ str         ┆ date       ┆ f64        ┆ i64  │
╞═════════════╪════════════╪════════════╪══════╡
│ Germany     ┆ 2016-03-01 ┆ 82.19      ┆ 4164 │
│ Germany     ┆ 2018-08-01 ┆ 82.66      ┆ 4696 │
│ Germany     ┆ 2019-01-01 ┆ 83.12      ┆ 4696 │
│ Netherlands ┆ 2016-03-01 ┆ 17.11      ┆ 784  │
│ Netherlands ┆ 2018-08-01 ┆ 17.32      ┆ 910  │
│ Netherlands ┆ 2019-01-01 ┆ 17.4       ┆ 910  │
└─────────────┴────────────┴────────────┴──────┘

join_where(
    other: DataFrame,
    *predicates: Expr | Iterable[Expr],
    how: JoinWhereStrategy = 'inner',
    suffix: str = '_right',
) → DataFrame

Выполняет объединение на основе одного или нескольких предикатов равенства/неравенства.

Примечание

Порядок строк исходных DataFrame не сохраняется.

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

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

Параметры:

other

DataFrame для объединения.

*predicates

Условие равенства/неравенства для объединения двух таблиц. Если имя столбца встречается в обеих таблицах, в предикате необходимо использовать соответствующий суффикс.

how{‘inner’, ‘left’, ‘right’}

Стратегия объединения.

suffix

Суффикс, добавляемый к столбцам с повторяющимися именами.

См. также

join

join_asof

Примеры

Объедините два DataFrame по двум предикатам, связанным оператором AND.

>>> east = pl.DataFrame(
...     {
...         "id": [100, 101, 102],
...         "dur": [120, 140, 160],
...         "rev": [12, 14, 16],
...         "cores": [2, 8, 4],
...     }
... )
>>> west = pl.DataFrame(
...     {
...         "t_id": [404, 498, 676, 742],
...         "time": [90, 130, 150, 170],
...         "cost": [9, 13, 15, 16],
...         "cores": [4, 2, 1, 4],
...     }
... )
>>> east.join_where(
...     west,
...     pl.col("dur") < pl.col("time"),
...     pl.col("rev") < pl.col("cost"),
... )
shape: (5, 8)
┌─────┬─────┬─────┬───────┬──────┬──────┬──────┬─────────────┐
│ id  ┆ dur ┆ rev ┆ cores ┆ t_id ┆ time ┆ cost ┆ cores_right │
│ --- ┆ --- ┆ --- ┆ ---   ┆ ---  ┆ ---  ┆ ---  ┆ ---         │
│ i64 ┆ i64 ┆ i64 ┆ i64   ┆ i64  ┆ i64  ┆ i64  ┆ i64         │
╞═════╪═════╪═════╪═══════╪══════╪══════╪══════╪═════════════╡
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 498  ┆ 130  ┆ 13   ┆ 2           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
└─────┴─────┴─────┴───────┴──────┴──────┴──────┴─────────────┘

Чтобы связать их оператором OR, используйте одно выражение и оператор |.

>>> east.join_where(
...     west,
...     (pl.col("dur") < pl.col("time")) | (pl.col("rev") < pl.col("cost")),
... )
shape: (6, 8)
┌─────┬─────┬─────┬───────┬──────┬──────┬──────┬─────────────┐
│ id  ┆ dur ┆ rev ┆ cores ┆ t_id ┆ time ┆ cost ┆ cores_right │
│ --- ┆ --- ┆ --- ┆ ---   ┆ ---  ┆ ---  ┆ ---  ┆ ---         │
│ i64 ┆ i64 ┆ i64 ┆ i64   ┆ i64  ┆ i64  ┆ i64  ┆ i64         │
╞═════╪═════╪═════╪═══════╪══════╪══════╪══════╪═════════════╡
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 498  ┆ 130  ┆ 13   ┆ 2           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 102 ┆ 160 ┆ 16  ┆ 4     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
└─────┴─────┴─────┴───────┴──────┴──────┴──────┴─────────────┘

Передайте how="left", чтобы дополнительно сохранить строки левой таблицы без совпадений, установив для столбцов правой таблицы значение null.

>>> east.join_where(
...     west,
...     pl.col("dur") < pl.col("time"),
...     pl.col("rev") < pl.col("cost"),
...     how="left",
... )
shape: (6, 8)
┌─────┬─────┬─────┬───────┬──────┬──────┬──────┬─────────────┐
│ id  ┆ dur ┆ rev ┆ cores ┆ t_id ┆ time ┆ cost ┆ cores_right │
│ --- ┆ --- ┆ --- ┆ ---   ┆ ---  ┆ ---  ┆ ---  ┆ ---         │
│ i64 ┆ i64 ┆ i64 ┆ i64   ┆ i64  ┆ i64  ┆ i64  ┆ i64         │
╞═════╪═════╪═════╪═══════╪══════╪══════╪══════╪═════════════╡
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 498  ┆ 130  ┆ 13   ┆ 2           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 100 ┆ 120 ┆ 12  ┆ 2     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 676  ┆ 150  ┆ 15   ┆ 1           │
│ 101 ┆ 140 ┆ 14  ┆ 8     ┆ 742  ┆ 170  ┆ 16   ┆ 4           │
│ 102 ┆ 160 ┆ 16  ┆ 4     ┆ null ┆ null ┆ null ┆ null        │
└─────┴─────┴─────┴───────┴──────┴──────┴──────┴─────────────┘

lazy() → LazyFrame

Начинает ленивый запрос с этой точки. Возвращает объект LazyFrame.

Операции над LazyFrame не выполняются, пока выполнение не будет запущено вызовом одного из методов:

• .collect()

  (выполнить для всех данных)

• .explain()

  (вывести план запроса)

• .show_graph()

  (показать план запроса в виде графа graphviz)

• .collect_schema()

  (вернуть схему результирующего фрейма)

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

Возвращает:

LazyFrame

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [None, 2, 3, 4],
...         "b": [0.5, None, 2.5, 13],
...         "c": [True, True, False, None],
...     }
... )
>>> df.lazy()
<LazyFrame at ...>

limit(
    n: int = 5,
) → DataFrame

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

Псевдоним для DataFrame.head().

Параметры:

n

Количество возвращаемых строк. Если передано отрицательное значение, возвращаются все строки, кроме последних abs(n).

См. также

head

Примеры

Получение первых 3 строк DataFrame.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> df.limit(3)
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

map_columns(
    column_names: str | Sequence[str] | Selector,
    function: Callable[Concatenate[Series,
    P],
    Series],
    *args: P.args,
    **kwargs: P.kwargs,
) → DataFrame

Применяет функции с немедленным выполнением к столбцам DataFrame.

Пользователям всегда следует предпочитать with_columns(), если только они не используют выражения, применимые только к Series, но не к Expr. Такое бывает почти никогда, за исключением нескольких функций, тип выходных данных которых невозможно определить без анализа самих данных.

Параметры:

column_names

Столбцы, к которым нужно применить UDF.

function

Вызываемый объект; первым параметром получает серию столбца, а затем любые переданные args/kwargs.

*args

Аргументы, передаваемые UDF.

**kwargs

Именованные аргументы, передаваемые UDF.

См. также

with_columns

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": ["10", "20", "30", "40"]})
>>> df.map_columns("a", lambda s: s.shrink_dtype())
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i8  ┆ str │
╞═════╪═════╡
│ 1   ┆ 10  │
│ 2   ┆ 20  │
│ 3   ┆ 30  │
│ 4   ┆ 40  │
└─────┴─────┘

>>> df = pl.DataFrame(
...     {
...         "a": ['{"x":"a"}', None, '{"x":"b"}', None],
...         "b": ['{"a":1, "b": true}', None, '{"a":2, "b": false}', None],
...     }
... )
>>> df.map_columns(["a", "b"], lambda s: s.str.json_decode())
shape: (4, 2)
┌───────────┬───────────┐
│ a         ┆ b         │
│ ---       ┆ ---       │
│ struct[1] ┆ struct[2] │
╞═══════════╪═══════════╡
│ {"a"}     ┆ {1,true}  │
│ null      ┆ null      │
│ {"b"}     ┆ {2,false} │
│ null      ┆ null      │
└───────────┴───────────┘
>>> import polars.selectors as cs
>>> df.map_columns(cs.all(), lambda s: s.str.json_decode())
shape: (4, 2)
┌───────────┬───────────┐
│ a         ┆ b         │
│ ---       ┆ ---       │
│ struct[1] ┆ struct[2] │
╞═══════════╪═══════════╡
│ {"a"}     ┆ {1,true}  │
│ null      ┆ null      │
│ {"b"}     ┆ {2,false} │
│ null      ┆ null      │
└───────────┴───────────┘

map_rows(
    function: Callable[[tuple[Any,
    ...]],
    Any],
    return_dtype: PolarsDataType | None = None,
    *,
    inference_size: int = 256,
) → DataFrame

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

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

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

UDF получает каждую строку в виде кортежа значений: udf(row).

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

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

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

Параметры:

function

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

return_dtype

Тип результата операции. Если не задан, Polars попытается определить тип автоматически.

inference_size

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

Примечания

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

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [-1, 5, 8]})

Возвращает DataFrame, преобразуя каждую строку в кортеж:

>>> df.map_rows(lambda t: (t[0] * 2, t[1] * 3))
shape: (3, 2)
┌──────────┬──────────┐
│ column_0 ┆ column_1 │
│ ---      ┆ ---      │
│ i64      ┆ i64      │
╞══════════╪══════════╡
│ 2        ┆ -3       │
│ 4        ┆ 15       │
│ 6        ┆ 24       │
└──────────┴──────────┘

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

>>> df.select(
...     pl.col("foo") * 2,
...     pl.col("bar") * 3,
... )  

Возвращает DataFrame с одним столбцом, преобразуя каждую строку в скалярное значение:

>>> df.map_rows(lambda t: t[0] * 2 + t[1])
shape: (3, 1)
┌─────┐
│ map │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 9   │
│ 14  │
└─────┘

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

>>> df.select(pl.col("foo") * 2 + pl.col("bar"))  

match_to_schema(
    schema: SchemaDict | Schema,
    *,
    missing_columns: Literal['insert',
    'raise'] | Mapping[str,
    Literal['insert',
    'raise'] | Expr] = 'raise',
    missing_struct_fields: Literal['insert',
    'raise'] | Mapping[str,
    Literal['insert',
    'raise']] = 'raise',
    extra_columns: Literal['ignore',
    'raise'] = 'raise',
    extra_struct_fields: Literal['ignore',
    'raise'] | Mapping[str,
    Literal['ignore',
    'raise']] = 'raise',
    integer_cast: Literal['upcast',
    'forbid'] | Mapping[str,
    Literal['upcast',
    'forbid']] = 'forbid',
    float_cast: Literal['upcast',
    'forbid'] | Mapping[str,
    Literal['upcast',
    'forbid']] = 'forbid',
) → DataFrame

Приводит схему LazyFrame к заданной схеме или адаптирует её к ней.

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

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

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

Параметры:

schema

Целевая схема, которой нужно соответствовать или к которой нужно привести данные.

missing_columns

Вызывает ошибку или добавляет отсутствующие во входных данных столбцы в соответствии с schema.

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

missing_struct_fields

Вызывает ошибку или добавляет отсутствующие во входных данных поля структуры в соответствии с schema.

extra_columns

Вызывает ошибку или игнорирует лишние входные столбцы в соответствии с schema.

extra_struct_fields

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

integer_cast

Запрещает повышающее преобразование целочисленных столбцов из входных данных к соответствующим столбцам в schema.

float_cast

Запрещает повышающее преобразование столбцов с плавающей точкой из входных данных к соответствующим столбцам в schema.

Примеры

Проверка соответствия схемы

>>> df = pl.DataFrame({"a": [1, 2, 3], "b": ["A", "B", "C"]})
>>> df.match_to_schema({"a": pl.Int64, "b": pl.String})
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 1   ┆ A   │
│ 2   ┆ B   │
│ 3   ┆ C   │
└─────┴─────┘
>>> df.match_to_schema({"a": pl.Int64})  
polars.exceptions.SchemaError: extra columns in `match_to_schema`: "b"

Добавление отсутствующих столбцов

>>> (
...     pl.DataFrame({"a": [1, 2, 3]}).match_to_schema(
...         {"a": pl.Int64, "b": pl.String},
...         missing_columns="insert",
...     )
... )
shape: (3, 2)
┌─────┬──────┐
│ a   ┆ b    │
│ --- ┆ ---  │
│ i64 ┆ str  │
╞═════╪══════╡
│ 1   ┆ null │
│ 2   ┆ null │
│ 3   ┆ null │
└─────┴──────┘
>>> (
...     pl.DataFrame({"a": [1, 2, 3]}).match_to_schema(
...         {"a": pl.Int64, "b": pl.String},
...         missing_columns={"b": pl.col.a.cast(pl.String)},
...     )
... )
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ str │
╞═════╪═════╡
│ 1   ┆ 1   │
│ 2   ┆ 2   │
│ 3   ┆ 3   │
└─────┴─────┘

Удаление лишних столбцов

>>> (
...     pl.DataFrame({"a": [1, 2, 3], "b": ["A", "B", "C"]}).match_to_schema(
...         {"a": pl.Int64},
...         extra_columns="ignore",
...     )
... )
shape: (3, 1)
┌─────┐
│ a   │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

Повышающее преобразование целых чисел и чисел с плавающей точкой

>>> (
...     pl.DataFrame(
...         {"a": [1, 2, 3], "b": [1.0, 2.0, 3.0]},
...         schema={"a": pl.Int32, "b": pl.Float32},
...     ).match_to_schema(
...         {"a": pl.Int64, "b": pl.Float64},
...         integer_cast="upcast",
...         float_cast="upcast",
...     )
... )
shape: (3, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ f64 │
╞═════╪═════╡
│ 1   ┆ 1.0 │
│ 2   ┆ 2.0 │
│ 3   ┆ 3.0 │
└─────┴─────┘

max() → DataFrame

Агрегирует столбцы этого DataFrame, вычисляя их максимальные значения.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.max()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

max_horizontal() → Series

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

Возвращает:

Series

Series с именем "max".

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [4.0, 5.0, 6.0],
...     }
... )
>>> df.max_horizontal()
shape: (3,)
Series: 'max' [f64]
[
        4.0
        5.0
        6.0
]

mean() → DataFrame

Агрегирует столбцы этого DataFrame, вычисляя их средние значения.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...         "spam": [True, False, None],
...     }
... )
>>> df.mean()
shape: (1, 4)
┌─────┬─────┬──────┬──────┐
│ foo ┆ bar ┆ ham  ┆ spam │
│ --- ┆ --- ┆ ---  ┆ ---  │
│ f64 ┆ f64 ┆ str  ┆ f64  │
╞═════╪═════╪══════╪══════╡
│ 2.0 ┆ 7.0 ┆ null ┆ 0.5  │
└─────┴─────┴──────┴──────┘

mean_horizontal(
    *,
    ignore_nulls: bool = True,
) → Series

Вычисляет среднее значение по горизонтали для всех значений в столбцах.

Параметры:

ignore_nulls

Игнорировать значения null (по умолчанию). Если задано значение False, любое значение null во входных данных приведёт к результату null.

Возвращает:

Series

Series с именем "mean".

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [4.0, 5.0, 6.0],
...     }
... )
>>> df.mean_horizontal()
shape: (3,)
Series: 'mean' [f64]
[
        2.5
        3.5
        4.5
]

median() → DataFrame

Агрегирует столбцы этого DataFrame, вычисляя их медианные значения.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.median()
shape: (1, 3)
┌─────┬─────┬──────┐
│ foo ┆ bar ┆ ham  │
│ --- ┆ --- ┆ ---  │
│ f64 ┆ f64 ┆ str  │
╞═════╪═════╪══════╡
│ 2.0 ┆ 7.0 ┆ null │
└─────┴─────┴──────┘

melt(
    id_vars: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    value_vars: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    variable_name: str | None = None,
    value_name: str | None = None,
) → DataFrame

Преобразует DataFrame из широкого формата в длинный.

При необходимости оставляет идентификаторы неизменными.

Эта функция полезна для преобразования DataFrame в формат, где один или несколько столбцов являются переменными-идентификаторами (id_vars), а все остальные столбцы, рассматриваемые как измеряемые переменные (value_vars), «разворачиваются» в строки, оставляя только два столбца, не являющихся идентификаторами: ‘variable’ и ‘value’.

Устарело начиная с версии 1.0.0: Вместо этого используйте метод unpivot().

Параметры:

id_vars

Столбец или столбцы либо селектор или селекторы, используемые в качестве переменных-идентификаторов.

value_vars

Столбец или столбцы либо селектор или селекторы, используемые в качестве переменных-значений; если value_vars пуст, будут использованы все столбцы, отсутствующие в id_vars.

variable_name

Имя столбца variable. По умолчанию — “variable”.

value_name

Имя столбца value. По умолчанию — “value”.

merge_sorted(
    other: DataFrame,
    key: str | Sequence[str],
    *,
    maintain_order: bool = False,
) → DataFrame

Объединяет два отсортированных DataFrame по отсортированному ключу.

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

Схемы обоих DataFrame должны совпадать.

Параметры:

other

Другой DataFrame, который необходимо объединить.

key

Ключевой столбец или столбцы, по которым отсортированы фреймы. Можно передать одно имя столбца или последовательность имён столбцов. Если передано несколько ключей, фреймы объединяются так, как если бы они были отсортированы по этим ключам в указанном порядке.

maintain_order

Если задано True, для одинаковых ключей гарантируется порядок с приоритетом левого фрейма: строки левого фрейма следуют перед строками правого фрейма.

Примечания

Если не задано maintain_order=True, порядок строк результата при одинаковых ключах не гарантируется.

Ключи должны быть отсортированы по возрастанию.

Примеры

>>> df0 = pl.DataFrame(
...     {"name": ["steve", "elise", "bob"], "age": [42, 44, 18]}
... ).sort("age")
>>> df0
shape: (3, 2)
┌───────┬─────┐
│ name  ┆ age │
│ ---   ┆ --- │
│ str   ┆ i64 │
╞═══════╪═════╡
│ bob   ┆ 18  │
│ steve ┆ 42  │
│ elise ┆ 44  │
└───────┴─────┘
>>> df1 = pl.DataFrame(
...     {"name": ["anna", "megan", "steve", "thomas"], "age": [21, 33, 42, 20]}
... ).sort("age")
>>> df1
shape: (4, 2)
┌────────┬─────┐
│ name   ┆ age │
│ ---    ┆ --- │
│ str    ┆ i64 │
╞════════╪═════╡
│ thomas ┆ 20  │
│ anna   ┆ 21  │
│ megan  ┆ 33  │
│ steve  ┆ 42  │
└────────┴─────┘
>>> df0.merge_sorted(df1, key="age")
shape: (7, 2)
┌────────┬─────┐
│ name   ┆ age │
│ ---    ┆ --- │
│ str    ┆ i64 │
╞════════╪═════╡
│ bob    ┆ 18  │
│ thomas ┆ 20  │
│ anna   ┆ 21  │
│ megan  ┆ 33  │
│ steve  ┆ 42  │
│ steve  ┆ 42  │
│ elise  ┆ 44  │
└────────┴─────┘

Для объединения фреймов, отсортированных по составному ключу, можно передать несколько ключей. Фреймы объединяются так, как если бы они были отсортированы сначала по key_1, а затем по key_2.

>>> df0 = pl.DataFrame({"key_1": [1, 1, 3], "key_2": [1, 4, 2]})
>>> df1 = pl.DataFrame({"key_1": [1, 2, 3], "key_2": [2, 1, 1]})
>>> df0.merge_sorted(df1, key=["key_1", "key_2"])
shape: (6, 2)
┌───────┬───────┐
│ key_1 ┆ key_2 │
│ ---   ┆ ---   │
│ i64   ┆ i64   │
╞═══════╪═══════╡
│ 1     ┆ 1     │
│ 1     ┆ 2     │
│ 1     ┆ 4     │
│ 2     ┆ 1     │
│ 3     ┆ 1     │
│ 3     ┆ 2     │
└───────┴───────┘

min() → DataFrame

Агрегирует столбцы этого DataFrame, вычисляя их минимальные значения.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.min()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
└─────┴─────┴─────┘

min_horizontal() → Series

Вычисляет минимальное значение по горизонтали для всех столбцов.

Возвращает:

Series

Series с именем "min".

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [4.0, 5.0, 6.0],
...     }
... )
>>> df.min_horizontal()
shape: (3,)
Series: 'min' [f64]
[
        1.0
        2.0
        3.0
]

n_chunks(
    strategy: Literal['first',
    'all'] = 'first',
) → int | list[int]

Возвращает количество фрагментов, используемых ChunkedArrays этого DataFrame.

Параметры:

strategy{‘first’, ‘all’}

Возвращает количество фрагментов для «первого» столбца или для «всех» столбцов этого DataFrame.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [0.5, 4, 10, 13],
...         "c": [True, True, False, True],
...     }
... )
>>> df.n_chunks()
1
>>> df.n_chunks(strategy="all")
[1, 1, 1]

n_unique(
    subset: str | Expr | Sequence[str | Expr] | None = None,
) → int

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

Параметры:

subset

Один или несколько столбцов/выражений, определяющих, что подсчитывать; опустите параметр, чтобы вернуть количество уникальных строк.

Примечания

Этот метод работает на уровне DataFrame; чтобы работать с подмножествами на уровне выражений, можно вместо этого использовать упаковку в структуры, например:

>>> expr_unique_subset = pl.struct("a", "b").n_unique()

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

>>> df = pl.DataFrame(
...     [[1, 2, 3], [1, 2, 4]], schema=["a", "b", "c"], orient="row"
... )
>>> df_nunique = df.select(pl.all().n_unique())

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

>>> df_agg_nunique = df.group_by("a").n_unique()

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 1, 2, 3, 4, 5],
...         "b": [0.5, 0.5, 1.0, 2.0, 3.0, 3.0],
...         "c": [True, True, True, False, True, True],
...     }
... )
>>> df.n_unique()
5

Подмножество из обычных столбцов.

>>> df.n_unique(subset=["b", "c"])
4

Подмножество из выражений.

>>> df.n_unique(
...     subset=[
...         (pl.col("a") // 2),
...         (pl.col("c") | (pl.col("b") >= 2)),
...     ],
... )
3

null_count() → DataFrame

Создаёт новый DataFrame, отображающий количество null-значений в каждом столбце.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, None, 3],
...         "bar": [6, 7, None],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.null_count()
shape: (1, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ u32 ┆ u32 ┆ u32 │
╞═════╪═════╪═════╡
│ 1   ┆ 1   ┆ 0   │
└─────┴─────┴─────┘

partition_by(
    by: ColumnNameOrSelector | Sequence[ColumnNameOrSelector],
    *more_by: ColumnNameOrSelector,
    maintain_order: bool = True,
    include_key: bool = True,
    as_dict: bool = False,
) → list[DataFrame] | dict[tuple[Any, ...], DataFrame]

Группирует данные по указанным столбцам и возвращает группы в виде отдельных датафреймов.

Параметры:

by

Имя (имена) столбца или селектор (селекторы) для группировки.

*more_by

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

maintain_order

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

include_key

Включает в результат столбцы, использованные для разбиения DataFrame на разделы.

as_dict

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

Примеры

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

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

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

>>> df.partition_by("a", "b")  
[shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 1   ┆ 5   │
│ a   ┆ 1   ┆ 3   │
└─────┴─────┴─────┘,
shape: (1, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ b   ┆ 2   ┆ 4   │
└─────┴─────┴─────┘,
shape: (1, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ b   ┆ 3   ┆ 2   │
└─────┴─────┴─────┘,
shape: (1, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ c   ┆ 3   ┆ 1   │
└─────┴─────┴─────┘]

Чтобы вернуть разделы в виде словаря, укажите as_dict=True.

>>> import polars.selectors as cs
>>> df.partition_by(cs.string(), as_dict=True)  
{('a',): shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ a   ┆ 1   ┆ 5   │
│ a   ┆ 1   ┆ 3   │
└─────┴─────┴─────┘,
('b',): shape: (2, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ b   ┆ 2   ┆ 4   │
│ b   ┆ 3   ┆ 2   │
└─────┴─────┴─────┘,
('c',): shape: (1, 3)
┌─────┬─────┬─────┐
│ a   ┆ b   ┆ c   │
│ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ c   ┆ 3   ┆ 1   │
└─────┴─────┴─────┘}

pipe(
    function: Callable[Concatenate[DataFrame,
    P],
    T],
    *args: P.args,
    **kwargs: P.kwargs,
) → T

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

Параметры:

function

Вызываемый объект; получит фрейм в качестве первого параметра, за которым следуют переданные аргументы args/kwargs.

*args

Аргументы, передаваемые UDF.

**kwargs

Именованные аргументы, передаваемые UDF.

Примечания

При объединении операций в цепочку рекомендуется использовать LazyFrame, чтобы в полной мере воспользоваться оптимизацией запросов и параллельным выполнением. См. df.lazy().

Примеры

>>> def cast_str_to_int(data, col_name):
...     return data.with_columns(pl.col(col_name).cast(pl.Int64))
>>> df = pl.DataFrame({"a": [1, 2, 3, 4], "b": ["10", "20", "30", "40"]})
>>> df.pipe(cast_str_to_int, col_name="b")
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 10  │
│ 2   ┆ 20  │
│ 3   ┆ 30  │
│ 4   ┆ 40  │
└─────┴─────┘

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

pivot(
    on: ColumnNameOrSelector | Sequence[ColumnNameOrSelector],
    on_columns: Sequence[Any] | Series | DataFrame | None = None,
    *,
    index: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    values: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    aggregate_function: PivotAgg | Expr | None = None,
    maintain_order: bool = True,
    sort_columns: bool = False,
    separator: str = '_',
    column_naming: Literal['auto',
    'combine'] = 'auto',
) → DataFrame

Создаёт сводную таблицу в стиле электронных таблиц в виде DataFrame.

Доступно только в eager-режиме. В разделе «Примеры» ниже описано, как выполнить «ленивое преобразование» (lazy pivot), если заранее известны уникальные значения столбцов.

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

Параметры:

on

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

on_columns

Какие комбинации значений будут учитываться в выходной таблице.

index

Столбец (столбцы), сохраняемый из входных данных в выходных. В выходном DataFrame будет по одной строке для каждой уникальной комбинации значений index. Если задано None, будут использованы все остальные столбцы, не указанные в on и values. Необходимо указать хотя бы один из параметров index и values.

values

Существующий столбец (столбцы) со значениями, которые будут перенесены в новые столбцы из index. Если указана агрегация, она будет вычисляться по этим значениям. Если задано None, будут использованы все остальные столбцы, не указанные в on и index. Необходимо указать хотя бы один из параметров index и values.

aggregate_function

Выберите один из вариантов:

• None: агрегация не выполняется; если в группе несколько значений, будет вызвана ошибка.
• Предопределённая строка с функцией агрегации из набора {‘min’, ‘max’, ‘first’, ‘last’, ‘sum’, ‘mean’, ‘median’, ‘len’}
• Выражение для выполнения агрегации. Выражение может обращаться только к данным соответствующих столбцов ‘values’, созданных в результате сводного преобразования, через pl.element().

maintain_order

Обеспечивает сортировку значений index в порядке их обнаружения.

sort_columns

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

separator

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

column_naming{‘auto’, ‘combine’}

Определяет способ формирования имён результирующих столбцов.

• ‘auto’: значение по умолчанию; если столбцов несколько, объединяет их с помощью разделителя

  столбцы values, в противном случае использует только имена on_columns.

• ‘combine’: Always combine the values columns’ names with

  имена on_columns.

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

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

Возвращает:

DataFrame

См. также

LazyFrame.pivot

Примечания

В некоторых других фреймворках эта операция может называться pivot_wider.

Примеры

С помощью pivot можно преобразовать датафрейм из «длинного» формата в «широкий».

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

>>> df = pl.DataFrame(
...     {
...         "name": ["Cady", "Cady", "Karen", "Karen"],
...         "subject": ["maths", "physics", "maths", "physics"],
...         "test_1": [98, 99, 61, 58],
...         "test_2": [100, 100, 60, 60],
...     }
... )
>>> df
shape: (4, 4)
┌───────┬─────────┬────────┬────────┐
│ name  ┆ subject ┆ test_1 ┆ test_2 │
│ ---   ┆ ---     ┆ ---    ┆ ---    │
│ str   ┆ str     ┆ i64    ┆ i64    │
╞═══════╪═════════╪════════╪════════╡
│ Cady  ┆ maths   ┆ 98     ┆ 100    │
│ Cady  ┆ physics ┆ 99     ┆ 100    │
│ Karen ┆ maths   ┆ 61     ┆ 60     │
│ Karen ┆ physics ┆ 58     ┆ 60     │
└───────┴─────────┴────────┴────────┘

С помощью pivot можно преобразовать данные так, чтобы для каждого студента была одна строка, для разных предметов — отдельные столбцы, а в качестве значений использовались результаты test_1:

>>> df.pivot("subject", index="name", values="test_1")
shape: (2, 3)
┌───────┬───────┬─────────┐
│ name  ┆ maths ┆ physics │
│ ---   ┆ ---   ┆ ---     │
│ str   ┆ i64   ┆ i64     │
╞═══════╪═══════╪═════════╡
│ Cady  ┆ 98    ┆ 99      │
│ Karen ┆ 61    ┆ 58      │
└───────┴───────┴─────────┘

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

>>> df.pivot(
...     "subject",
...     on_columns=["maths", "physics"],
...     index="name",
...     values="test_1",
... )
shape: (2, 3)
┌───────┬───────┬─────────┐
│ name  ┆ maths ┆ physics │
│ ---   ┆ ---   ┆ ---     │
│ str   ┆ i64   ┆ i64     │
╞═══════╪═══════╪═════════╡
│ Cady  ┆ 98    ┆ 99      │
│ Karen ┆ 61    ┆ 58      │
└───────┴───────┴─────────┘

Можно использовать и селекторы — здесь в сводную таблицу включены все результаты тестов:

>>> import polars.selectors as cs
>>> df.pivot("subject", values=cs.starts_with("test"))
shape: (2, 5)
┌───────┬──────────────┬────────────────┬──────────────┬────────────────┐
│ name  ┆ test_1_maths ┆ test_1_physics ┆ test_2_maths ┆ test_2_physics │
│ ---   ┆ ---          ┆ ---            ┆ ---          ┆ ---            │
│ str   ┆ i64          ┆ i64            ┆ i64          ┆ i64            │
╞═══════╪══════════════╪════════════════╪══════════════╪════════════════╡
│ Cady  ┆ 98           ┆ 99             ┆ 100          ┆ 100            │
│ Karen ┆ 61           ┆ 58             ┆ 60           ┆ 60             │
└───────┴──────────────┴────────────────┴──────────────┴────────────────┘

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

>>> df = pl.DataFrame(
...     {
...         "ix": [1, 1, 2, 2, 1, 2],
...         "col": ["a", "a", "a", "a", "b", "b"],
...         "foo": [0, 1, 2, 2, 7, 1],
...         "bar": [0, 2, 0, 0, 9, 4],
...     }
... )
>>> df.pivot("col", index="ix", aggregate_function="sum")
shape: (2, 5)
┌─────┬───────┬───────┬───────┬───────┐
│ ix  ┆ foo_a ┆ foo_b ┆ bar_a ┆ bar_b │
│ --- ┆ ---   ┆ ---   ┆ ---   ┆ ---   │
│ i64 ┆ i64   ┆ i64   ┆ i64   ┆ i64   │
╞═════╪═══════╪═══════╪═══════╪═══════╡
│ 1   ┆ 1     ┆ 7     ┆ 2     ┆ 9     │
│ 2   ┆ 4     ┆ 1     ┆ 0     ┆ 4     │
└─────┴───────┴───────┴───────┴───────┘

Также можно передать пользовательскую функцию агрегации с помощью polars.element():

>>> df = pl.DataFrame(
...     {
...         "col1": ["a", "a", "a", "b", "b", "b"],
...         "col2": ["x", "x", "x", "x", "y", "y"],
...         "col3": [6, 7, 3, 2, 5, 7],
...     }
... )
>>> df.pivot(
...     "col2",
...     index="col1",
...     values="col3",
...     aggregate_function=pl.element().tanh().mean(),
... )
shape: (2, 3)
┌──────┬──────────┬──────────┐
│ col1 ┆ x        ┆ y        │
│ ---  ┆ ---      ┆ ---      │
│ str  ┆ f64      ┆ f64      │
╞══════╪══════════╪══════════╡
│ a    ┆ 0.998347 ┆ null     │
│ b    ┆ 0.964028 ┆ 0.999954 │
└──────┴──────────┴──────────┘

property plot: DataFramePlot

Создаёт пространство имён для построения графиков.

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

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

Изменено в версии 1.6.0: В предыдущих версиях Polars для построения графиков использовался HvPlot. Чтобы восстановить прежнюю функциональность построения графиков, достаточно добавить import hvplot.polars в начало скрипта и заменить df.plot на df.hvplot.

Polars не реализует логику построения графиков самостоятельно, а делегирует её библиотеке Altair:

• df.plot.line(**kwargs) — сокращённая запись для alt.Chart(df).mark_line(tooltip=True).encode(**kwargs).interactive()
• df.plot.point(**kwargs) — сокращённая запись для alt.Chart(df).mark_point(tooltip=True).encode(**kwargs).interactive() (а plot.scatter предоставляется как псевдоним)
• df.plot.bar(**kwargs) — сокращённая запись для alt.Chart(df).mark_bar(tooltip=True).encode(**kwargs).interactive()
• для любого другого атрибута attr, df.plot.attr(**kwargs) — сокращённая запись для alt.Chart(df).mark_attr(tooltip=True).encode(**kwargs).interactive()

Информацию о настройке можно найти в разделе Настройка диаграмм. Например, можно:

• Изменить ширину, высоту и заголовок с помощью .properties(width=500, height=350, title="My amazing plot").
• Изменить угол поворота подписи оси x с помощью .configure_axisX(labelAngle=30).
• Изменить непрозрачность точек на точечной диаграмме с помощью .configure_point(opacity=.5).

Примеры

Точечная диаграмма:

>>> df = pl.DataFrame(
...     {
...         "length": [1, 4, 6],
...         "width": [4, 5, 6],
...         "species": ["setosa", "setosa", "versicolor"],
...     }
... )
>>> df.plot.point(x="length", y="width", color="species")  

Задать заголовок оси x с помощью altair.X:

>>> import altair as alt
>>> df.plot.point(
...     x=alt.X("length", title="Length"), y="width", color="species"
... )  

Линейный график:

>>> from datetime import date
>>> df = pl.DataFrame(
...     {
...         "date": [date(2020, 1, 2), date(2020, 1, 3), date(2020, 1, 4)] * 2,
...         "price": [1, 4, 6, 1, 5, 2],
...         "stock": ["a", "a", "a", "b", "b", "b"],
...     }
... )
>>> df.plot.line(x="date", y="price", color="stock")  

Столбчатая диаграмма:

>>> df = pl.DataFrame(
...     {
...         "day": ["Mon", "Tue", "Wed", "Thu", "Fri", "Sat", "Sun"] * 2,
...         "group": ["a"] * 7 + ["b"] * 7,
...         "value": [1, 3, 2, 4, 5, 6, 1, 1, 3, 2, 4, 5, 1, 2],
...     }
... )
>>> df.plot.bar(
...     x="day", y="value", color="day", column="group"
... )  

Или создать вариант приведённой выше диаграммы с накоплением:

>>> df.plot.bar(x="day", y="value", color="group")  

product() → DataFrame

Агрегирует столбцы этого DataFrame, вычисляя их произведение.

Примеры

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

>>> df.product()
shape: (1, 3)
┌─────┬──────┬─────┐
│ a   ┆ b    ┆ c   │
│ --- ┆ ---  ┆ --- │
│ i64 ┆ f64  ┆ i64 │
╞═════╪══════╪═════╡
│ 6   ┆ 20.0 ┆ 0   │
└─────┴──────┴─────┘

quantile(
    quantile: float,
    interpolation: QuantileMethod = 'nearest',
) → DataFrame

Агрегирует столбцы этого DataFrame, вычисляя их квантиль.

Параметры:

quantile

Квантиль от 0.0 до 1.0.

interpolation{‘nearest’, ‘higher’, ‘lower’, ‘midpoint’, ‘linear’, ‘equiprobable’}

Метод интерполяции.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.quantile(0.5, "nearest")
shape: (1, 3)
┌─────┬─────┬──────┐
│ foo ┆ bar ┆ ham  │
│ --- ┆ --- ┆ ---  │
│ f64 ┆ f64 ┆ str  │
╞═════╪═════╪══════╡
│ 2.0 ┆ 7.0 ┆ null │
└─────┴─────┴──────┘

rechunk() → DataFrame

Перераспределяет данные этого DataFrame в непрерывный блок памяти.

Это обеспечивает оптимальную и предсказуемую производительность всех последующих операций.

remove(
    *predicates: IntoExprColumn | Iterable[IntoExprColumn] | bool | list[bool] | np.ndarray[Any,
    Any],
    **constraints: Any,
) → DataFrame

Удаляет строки, соответствующие заданному выражению (выражениям) предиката.

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

Строки, для которых условие фильтрации не вычисляется как True, сохраняются (в том числе строки, для которых условие вычисляется как null).

Параметры:

predicates

Выражение (выражения), вычисляемое в логический Series. Если передано несколько предикатов, они объединяются с помощью & (логическое И), поэтому строка удаляется, только если каждый предикат для неё вычисляется как True.

constraints

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

См. также

filter

Примечания

Если вы переходите с Pandas и выполняете фильтрацию на основе сравнения двух или более столбцов, обратите внимание: в Polars любое сравнение, в котором участвуют значения null, даст результат null, а не логическое значение True или False. Поэтому такие строки не будут удалены. Обрабатывайте null-значения соответствующим образом, чтобы избежать неожиданного поведения (см. примеры ниже).

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [2, 3, None, 4, 0],
...         "bar": [5, 6, None, None, 0],
...         "ham": ["a", "b", None, "c", "d"],
...     }
... )

Удалить строки, соответствующие условию:

>>> df.remove(pl.col("bar") >= 5)
shape: (3, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ 4    ┆ null ┆ c    │
│ 0    ┆ 0    ┆ d    │
└──────┴──────┴──────┘

Отбросить строки по нескольким условиям, объединённым операторами И/ИЛИ:

>>> df.remove(
...     (pl.col("foo") >= 0) & (pl.col("bar") >= 0),
... )
shape: (2, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ 4    ┆ null ┆ c    │
└──────┴──────┴──────┘

>>> df.remove(
...     (pl.col("foo") >= 0) | (pl.col("bar") >= 0),
... )
shape: (1, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
└──────┴──────┴──────┘

Задать несколько ограничений с помощью синтаксиса *args:

>>> df.remove(
...     pl.col("ham").is_not_null(),
...     pl.col("bar") >= 0,
... )
shape: (2, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ 4    ┆ null ┆ c    │
└──────┴──────┴──────┘

Задать ограничение (ограничения) с помощью синтаксиса **kwargs:

>>> df.remove(foo=0, bar=0)
shape: (4, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ 2    ┆ 5    ┆ a    │
│ 3    ┆ 6    ┆ b    │
│ null ┆ null ┆ null │
│ 4    ┆ null ┆ c    │
└──────┴──────┴──────┘

Удалить строки, сравнив два столбца друг с другом:

>>> df.remove(
...     pl.col("foo").ne_missing(pl.col("bar")),
... )
shape: (2, 3)
┌──────┬──────┬──────┐
│ foo  ┆ bar  ┆ ham  │
│ ---  ┆ ---  ┆ ---  │
│ i64  ┆ i64  ┆ str  │
╞══════╪══════╪══════╡
│ null ┆ null ┆ null │
│ 0    ┆ 0    ┆ d    │
└──────┴──────┴──────┘

rename(
    mapping: Mapping[str,
    str] | Callable[[str],
    str],
    *,
    strict: bool = True,
) → DataFrame

Переименовывает столбцы.

Параметры:

mapping

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

strict

Проверяет наличие всех имён столбцов в текущей схеме и вызывает исключение, если какие-либо из них отсутствуют. (Обратите внимание: этот параметр ничего не делает, если в mapping передана функция.)

См. также

Expr.name.replace

Примеры

>>> df = pl.DataFrame(
...     {"foo": [1, 2, 3], "bar": [6, 7, 8], "ham": ["a", "b", "c"]}
... )
>>> df.rename({"foo": "apple"})
shape: (3, 3)
┌───────┬─────┬─────┐
│ apple ┆ bar ┆ ham │
│ ---   ┆ --- ┆ --- │
│ i64   ┆ i64 ┆ str │
╞═══════╪═════╪═════╡
│ 1     ┆ 6   ┆ a   │
│ 2     ┆ 7   ┆ b   │
│ 3     ┆ 8   ┆ c   │
└───────┴─────┴─────┘
>>> df.rename(lambda column_name: "c" + column_name[1:])
shape: (3, 3)
┌─────┬─────┬─────┐
│ coo ┆ car ┆ cam │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

replace_column(
    index: int,
    column: Series,
) → DataFrame

Заменяет столбец по указанному индексу.

Эта операция выполняется на месте.

Параметры:

index

Индекс столбца.

column

Series, которым будет заменён столбец.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> s = pl.Series("apple", [10, 20, 30])
>>> df.replace_column(0, s)
shape: (3, 3)
┌───────┬─────┬─────┐
│ apple ┆ bar ┆ ham │
│ ---   ┆ --- ┆ --- │
│ i64   ┆ i64 ┆ str │
╞═══════╪═════╪═════╡
│ 10    ┆ 6   ┆ a   │
│ 20    ┆ 7   ┆ b   │
│ 30    ┆ 8   ┆ c   │
└───────┴─────┴─────┘

reverse() → DataFrame

Разворачивает DataFrame в обратном порядке.

Примеры

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметры:

index_column

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

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

period

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

offset

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

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

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

group_by

Также группирует данные по этому столбцу (столбцам).

Возвращает:

RollingGroupBy

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

См. также

group_by_dynamic

Примеры

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

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

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

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

row(
    index: int | None = None,
    *,
    by_predicate: Expr | None = None,
    named: bool = False,
) → tuple[Any, ...] | dict[str, Any]

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

Параметры:

index

Индекс строки.

by_predicate

Выбирает строку в соответствии с заданным выражением/предикатом.

named

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

Возвращает:

кортеж (по умолчанию) или словарь значений строки

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

НИКОГДА не используйте этот метод для перебора DataFrame по строкам; если требуется перебор строк, настоятельно рекомендуется использовать вместо него iter_rows().

См. также

iter_rows

Итератор по строкам данных фрейма (не материализует все строки).

rows

Материализует все данные фрейма в виде списка строк (может потребовать значительных ресурсов).

item

Возвращает элемент датафрейма в виде скалярного значения.

Примечания

Параметры index и by_predicate взаимоисключающие. Кроме того, для ясности параметр by_predicate необходимо передавать по имени.

При использовании by_predicate возвращение чего-либо, кроме одной строки, считается ошибкой: если возвращено больше одной строки, возникает TooManyRowsReturnedError, а если строк нет — NoRowsReturnedError (оба исключения являются подклассами RowsError).

Примеры

Укажите индекс, чтобы вернуть строку с этим индексом в виде кортежа.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.row(2)
(3, 8, 'c')

Укажите named=True, чтобы вместо этого получить словарь, сопоставляющий имена столбцов со значениями строки.

>>> df.row(2, named=True)
{'foo': 3, 'bar': 8, 'ham': 'c'}

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

>>> df.row(by_predicate=(pl.col("ham") == "b"))
(2, 7, 'b')

rows(
    *,
    named: bool = False,
) → list[tuple[Any, ...]] | list[dict[str, Any]]

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

По умолчанию каждая строка возвращается как кортеж значений в том же порядке, что и столбцы фрейма. Если задать named=True, строки будут возвращены в виде словарей.

Параметры:

named

Возвращает словари вместо кортежей. Словари сопоставляют имя столбца со значением в строке. Это требует больше ресурсов, чем возврат обычного кортежа, но позволяет получать значения по имени столбца.

Возвращает:

list of row value tuples (default), or list of dictionaries (if named=True).

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

Перебор строк не оптимален, поскольку данные хранятся в столбцовом формате; по возможности используйте специальные методы экспорта/вывода. Также рассмотрите возможность использования iter_rows, чтобы не материализовать все данные сразу: разница в производительности между этими вариантами невелика, но при обработке строк пакетами можно снизить пиковое потребление памяти.

См. также

iter_rows

Итератор по строкам данных фрейма (не материализует все строки).

rows_by_key

Материализует данные фрейма в виде словаря с индексами-ключами.

Примечания

Если у вас есть временные значения с точностью до ns, учтите, что Python изначально поддерживает точность только до μs; значения с точностью до ns при преобразовании в Python будут усечены до микросекунд. Если это важно для вашего сценария использования, экспортируйте данные в другой формат (например, Arrow или NumPy).

Примеры

>>> df = pl.DataFrame(
...     {
...         "x": ["a", "b", "b", "a"],
...         "y": [1, 2, 3, 4],
...         "z": [0, 3, 6, 9],
...     }
... )
>>> df.rows()
[('a', 1, 0), ('b', 2, 3), ('b', 3, 6), ('a', 4, 9)]
>>> df.rows(named=True)
[{'x': 'a', 'y': 1, 'z': 0},
 {'x': 'b', 'y': 2, 'z': 3},
 {'x': 'b', 'y': 3, 'z': 6},
 {'x': 'a', 'y': 4, 'z': 9}]

rows_by_key(
    key: ColumnNameOrSelector | Sequence[ColumnNameOrSelector],
    *,
    named: bool = False,
    include_key: bool = False,
    unique: bool = False,
) → dict[Any, Any]

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

Этот метод похож на rows, но вместо возврата строк в виде плоского списка группирует их по значениям столбца (столбцов) key и возвращает в виде словаря.

Не используйте этот метод вместо встроенных операций: материализация всех данных фрейма в словарь обходится дорого. Его следует применять только тогда, когда нужно перенести значения в структуру данных Python или другой объект, не умеющий напрямую работать с Polars/Arrow.

Параметры:

key

Столбец (столбцы), используемый в качестве ключа возвращаемого словаря. Если указано несколько столбцов, ключом будет кортеж из соответствующих значений; в противном случае ключом будет строка.

named

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

include_key

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

unique

Указывает, что ключ уникален; в результате каждому ключу будет соответствовать ровно одна строка. Если ключ на самом деле не уникален, будет возвращена последняя строка с этим ключом.

См. также

rows

Материализует все данные фрейма в виде списка строк (может потребовать значительных ресурсов).

iter_rows

Итератор по строкам данных фрейма (не материализует все строки).

to_dict

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

Примечания

Если у вас есть временные значения с точностью до ns, учтите, что Python изначально поддерживает точность только до μs; значения с точностью до ns при преобразовании в Python будут усечены до микросекунд. Если это важно для вашего сценария использования, экспортируйте данные в другой формат (например, Arrow или NumPy).

Примеры

>>> df = pl.DataFrame(
...     {
...         "w": ["a", "b", "b", "a"],
...         "x": ["q", "q", "q", "k"],
...         "y": [1.0, 2.5, 3.0, 4.5],
...         "z": [9, 8, 7, 6],
...     }
... )

Сгруппировать строки по указанному столбцу (столбцам)-ключу:

>>> df.rows_by_key(key=["w"])
defaultdict(<class 'list'>,
    {'a': [('q', 1.0, 9), ('k', 4.5, 6)],
     'b': [('q', 2.5, 8), ('q', 3.0, 7)]})

Вернуть те же группы строк в виде словарей:

>>> df.rows_by_key(key=["w"], named=True)
defaultdict(<class 'list'>,
    {'a': [{'x': 'q', 'y': 1.0, 'z': 9},
           {'x': 'k', 'y': 4.5, 'z': 6}],
     'b': [{'x': 'q', 'y': 2.5, 'z': 8},
           {'x': 'q', 'y': 3.0, 'z': 7}]})

Вернуть группы строк, предполагая, что ключи уникальны:

>>> df.rows_by_key(key=["z"], unique=True)
{9: ('a', 'q', 1.0),
 8: ('b', 'q', 2.5),
 7: ('b', 'q', 3.0),
 6: ('a', 'k', 4.5)}

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

>>> df.rows_by_key(key=["z"], named=True, unique=True)
{9: {'w': 'a', 'x': 'q', 'y': 1.0},
 8: {'w': 'b', 'x': 'q', 'y': 2.5},
 7: {'w': 'b', 'x': 'q', 'y': 3.0},
 6: {'w': 'a', 'x': 'k', 'y': 4.5}}

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

>>> df.rows_by_key(key=["w", "x"], named=True, include_key=True)
defaultdict(<class 'list'>,
    {('a', 'q'): [{'w': 'a', 'x': 'q', 'y': 1.0, 'z': 9}],
     ('b', 'q'): [{'w': 'b', 'x': 'q', 'y': 2.5, 'z': 8},
                  {'w': 'b', 'x': 'q', 'y': 3.0, 'z': 7}],
     ('a', 'k'): [{'w': 'a', 'x': 'k', 'y': 4.5, 'z': 6}]})

sample(
    n: int | Series | None = None,
    *,
    fraction: float | Series | None = None,
    with_replacement: bool = False,
    shuffle: bool | None = None,
    seed: int | None = None,
) → DataFrame

Извлекает случайную выборку из этого DataFrame.

Параметры:

n

Количество возвращаемых элементов. Нельзя использовать вместе с fraction. Если fraction равно None, по умолчанию используется значение 1.

fraction

Доля возвращаемых элементов. Нельзя использовать вместе с n.

with_replacement

Разрешает выбирать одно и то же значение несколько раз.

shuffle

Определяет порядок строк в выборке. Если значение True, выбранные строки явно перемешиваются. Если False, относительный порядок выбранных строк сохраняется (то есть они идут в том же порядке, что и в исходном DataFrame). Если значение None (по умолчанию), порядок не гарантируется и используется наиболее производительный алгоритм.

seed

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.sample(n=2, shuffle=False, seed=0)  
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 3   ┆ 8   ┆ c   │
│ 2   ┆ 7   ┆ b   │
└─────┴─────┴─────┘

property schema: Schema

Возвращает упорядоченное соответствие имён столбцов их типам данных.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.schema
Schema({'foo': Int64, 'bar': Float64, 'ham': String})

select(
    *exprs: IntoExpr | Iterable[IntoExpr],
    **named_exprs: IntoExpr,
) → DataFrame

Выбирает столбцы из этого DataFrame.

Параметры:

*exprs

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

**named_exprs

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

Примеры

Передайте имя столбца, чтобы выбрать его.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.select("foo")
shape: (3, 1)
┌─────┐
│ foo │
│ --- │
│ i64 │
╞═════╡
│ 1   │
│ 2   │
│ 3   │
└─────┘

Чтобы выбрать несколько столбцов, передайте список их имён.

>>> df.select(["foo", "bar"])
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 6   │
│ 2   ┆ 7   │
│ 3   ┆ 8   │
└─────┴─────┘

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

>>> df.select(pl.col("foo"), pl.col("bar") + 1)
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 7   │
│ 2   ┆ 8   │
│ 3   ┆ 9   │
└─────┴─────┘

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

>>> df.select(threshold=pl.when(pl.col("foo") > 2).then(10).otherwise(0))
shape: (3, 1)
┌───────────┐
│ threshold │
│ ---       │
│ i32       │
╞═══════════╡
│ 0         │
│ 0         │
│ 10        │
└───────────┘

select_seq(
    *exprs: IntoExpr | Iterable[IntoExpr],
    **named_exprs: IntoExpr,
) → DataFrame

Выбрать столбцы из этого DataFrame.

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

Параметры:

*exprs

Столбец или столбцы для выбора, указанные в виде позиционных аргументов. Принимает выражения. Строки интерпретируются как имена столбцов, другие аргументы, не являющиеся выражениями, — как литералы.

**named_exprs

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

См. также

select

serialize(
    file: IOBase | str | Path | None = None,
    *,
    format: SerializationFormat = 'binary',
) → bytes | str | None

Сериализовать этот DataFrame в файл или строку в формате JSON.

Параметры:

file

Путь к файлу или файловый объект с возможностью записи, в который будет записан результат. Если задано None (значение по умолчанию), результат возвращается в виде строки.

format

Формат сериализации. Варианты:

• "binary": сериализация в двоичный формат (bytes). Это значение используется по умолчанию.
• "json": сериализация в формат JSON (string).

Примечания

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

Примеры

Сериализуем DataFrame в двоичное представление.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...     }
... )
>>> bytes = df.serialize()
>>> type(bytes)
<class 'bytes'>

Позднее байты можно десериализовать обратно в DataFrame.

>>> import io
>>> pl.DataFrame.deserialize(io.BytesIO(bytes))
shape: (3, 2)
┌─────┬─────┐
│ foo ┆ bar │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 6   │
│ 2   ┆ 7   │
│ 3   ┆ 8   │
└─────┴─────┘

set_sorted(
    column: str,
    *,
    descending: bool = False,
    nulls_last: bool = False,
) → DataFrame

Пометить столбец как отсортированный.

Это может ускорить последующие операции.

Параметры:

column

Отсортированный столбец

descending

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

nulls_last

Указывает, находятся ли значения null в конце.

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

Если данные НЕ отсортированы, это может привести к некорректным результатам! Используйте с осторожностью!

property shape: tuple[int, int]

Получить форму DataFrame.

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3, 4, 5]})
>>> df.shape
(5, 1)

shift(
    n: int = 1,
    *,
    fill_value: IntoExpr | None = None,
) → DataFrame

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

Параметры:

n

Число индексов для сдвига вперёд. Если передано отрицательное значение, значения сдвигаются в противоположном направлении.

fill_value

Заполнить получившиеся значения null этим значением. Принимает скалярное выражение. Аргументы, не являющиеся выражениями, интерпретируются как литералы.

Примечания

Этот метод аналогичен операции LAG в SQL, если значение n положительно. При отрицательном значении n он аналогичен LEAD.

Примеры

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

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

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

>>> df.shift(-2)
shape: (4, 2)
┌──────┬──────┐
│ a    ┆ b    │
│ ---  ┆ ---  │
│ i64  ┆ i64  │
╞══════╪══════╡
│ 3    ┆ 7    │
│ 4    ┆ 8    │
│ null ┆ null │
│ null ┆ null │
└──────┴──────┘

Укажите fill_value, чтобы заполнить получившиеся значения null.

>>> df.shift(-2, fill_value=100)
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 3   ┆ 7   │
│ 4   ┆ 8   │
│ 100 ┆ 100 │
│ 100 ┆ 100 │
└─────┴─────┘

show(
    limit: int | None = 5,
    *,
    ascii_tables: bool | None = None,
    decimal_separator: str | None = None,
    thousands_separator: str | bool | None = None,
    float_precision: int | None = None,
    fmt_float: FloatFmt | None = None,
    fmt_str_lengths: int | None = None,
    fmt_table_cell_list_len: int | None = None,
    tbl_cell_alignment: Alignment | None = None,
    tbl_cell_numeric_alignment: Alignment | None = None,
    tbl_cols: int | None = None,
    tbl_column_data_type_inline: bool | None = None,
    tbl_dataframe_shape_below: bool | None = None,
    tbl_formatting: TableFormatNames | None = None,
    tbl_hide_column_data_types: bool | None = None,
    tbl_hide_column_names: bool | None = None,
    tbl_hide_dtype_separator: bool | None = None,
    tbl_hide_dataframe_shape: bool | None = None,
    tbl_width_chars: int | None = None,
    trim_decimal_zeros: bool | None = True,
) → None

Показать первые n строк.

Параметры:

limitint

Количество отображаемых строк. Если передано отрицательное значение, возвращаются все строки, кроме последних abs(n). Если передано None, возвращаются все строки.

ascii_tablesbool

Использовать символы ASCII для отображения границ таблицы. Установите False, чтобы вернуться к стилю форматирования UTF8_FULL_CONDENSED по умолчанию. Подробнее см. в разделе Config.set_ascii_tables().

decimal_separatorstr

Задать символ-разделитель десятичной части. Подробнее см. в разделе Config.set_decimal_separator().

thousands_separatorstr, bool

Задать символ-разделитель групп разрядов. Подробнее см. в разделе Config.set_thousands_separator().

float_precisionint

Количество отображаемых знаков после запятой для значений с плавающей точкой. Подробнее см. в разделе Config.set_float_precision().

fmt_float{“mixed”, “full”}

Управляет отображением значений с плавающей точкой. Подробнее см. в разделе Config.set_fmt_float(). Поддерживаются следующие варианты:

• “mixed”: ограничить количество знаков после запятой и использовать экспоненциальную запись для больших и малых значений.
• “full”: выводить значение с плавающей точкой с полной точностью.

fmt_str_lengthsint

Количество отображаемых символов для строковых значений. Подробнее см. в разделе Config.set_fmt_str_lengths().

fmt_table_cell_list_lenint

Количество отображаемых элементов для значений типа List. Подробнее см. в разделе Config.set_fmt_table_cell_list_len().

tbl_cell_alignmentstr

Задать выравнивание ячеек таблицы. Подробнее см. в разделе Config.set_tbl_cell_alignment(). Поддерживаются следующие варианты:

• “LEFT”: по левому краю
• “CENTER”: по центру
• “RIGHT”: по правому краю

tbl_cell_numeric_alignmentstr

Задать выравнивание ячеек таблицы для числовых столбцов. Подробнее см. в разделе Config.set_tbl_cell_numeric_alignment(). Поддерживаются следующие варианты:

• “LEFT”: по левому краю
• “CENTER”: по центру
• “RIGHT”: по правому краю

tbl_colsint

Количество отображаемых столбцов. Подробнее см. в разделе Config.set_tbl_cols().

tbl_column_data_type_inlinebool

Размещать тип данных рядом с именем столбца (справа, в скобках). Подробнее см. в разделе Config.set_tbl_column_data_type_inline().

tbl_dataframe_shape_belowbool

Выводить сведения о форме DataFrame под данными при отображении таблиц. Подробнее см. в разделе Config.set_tbl_dataframe_shape_below().

tbl_formattingstr

Задать стиль форматирования таблицы. Подробнее см. в разделе Config.set_tbl_formatting(). Поддерживаются следующие варианты:

• “ASCII_FULL”: ASCII, все границы и линии, включая разделители строк.
• “ASCII_FULL_CONDENSED”: то же, что ASCII_FULL, но с уменьшенным интервалом между строками.
• “ASCII_NO_BORDERS”: ASCII, без границ.
• “ASCII_BORDERS_ONLY”: ASCII, только границы.
• “ASCII_BORDERS_ONLY_CONDENSED”: ASCII, только границы, уменьшенный интервал между строками.
• “ASCII_HORIZONTAL_ONLY”: ASCII, только горизонтальные линии.
• “ASCII_MARKDOWN”: формат Markdown (многоточие ASCII для усечённых значений).
• “MARKDOWN”: формат Markdown (многоточие UTF-8 для усечённых значений).
• “UTF8_FULL”: UTF-8, все границы и линии, включая разделители строк.
• “UTF8_FULL_CONDENSED”: то же, что UTF8_FULL, но с уменьшенным интервалом между строками.
• “UTF8_NO_BORDERS”: UTF-8, без границ.
• “UTF8_BORDERS_ONLY”: UTF-8, только границы.
• “UTF8_HORIZONTAL_ONLY”: UTF-8, только горизонтальные линии.
• “NOTHING”: без границ и других линий.

tbl_hide_column_data_typesbool

Скрывать типы данных столбцов таблицы (i64, f64, str и т. д.). Подробнее см. в разделе Config.set_tbl_hide_column_data_types().

tbl_hide_column_namesbool

Скрывать имена столбцов таблицы. Подробнее см. в разделе Config.set_tbl_hide_column_names().

tbl_hide_dtype_separatorbool

Скрывать разделитель ‘—’ между именами и типами столбцов. Подробнее см. в разделе Config.set_tbl_hide_dtype_separator().

tbl_hide_dataframe_shapebool

Скрывать сведения о форме DataFrame при отображении таблиц. Подробнее см. в разделе Config.set_tbl_hide_dataframe_shape().

tbl_width_charsint

Задать максимальную ширину таблицы в символах. Подробнее см. в разделе Config.set_tbl_width_chars().

trim_decimal_zerosbool

Удалять завершающие нули из значений типа Decimal. Подробнее см. в разделе Config.set_trim_decimal_zeros().

См. также

head

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> df.show(3)
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
└─────┴─────┴─────┘

Передайте отрицательное значение, чтобы получить все строки, except последние abs(n).

>>> df.show(-3)
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
└─────┴─────┴─────┘

shrink_to_fit(
    *,
    in_place: bool = False,
) → DataFrame

Уменьшить объём памяти, используемый DataFrame.

Размер памяти будет сокращён до точной ёмкости, необходимой для хранения данных.

slice(
    offset: int,
    length: int | None = None,
) → DataFrame

Получить срез этого DataFrame.

Параметры:

offset

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

length

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.slice(1, 2)
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ f64 ┆ str │
╞═════╪═════╪═════╡
│ 2   ┆ 7.0 ┆ b   │
│ 3   ┆ 8.0 ┆ c   │
└─────┴─────┴─────┘

sort(
    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,
) → DataFrame

Отсортировать DataFrame по указанным столбцам.

Параметры:

by

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

*more_by

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

descending

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

nulls_last

Размещать значения null в конце; можно указать одно логическое значение для всех столбцов или последовательность логических значений для настройки каждого столбца.

multithreaded

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

maintain_order

Сохранять ли порядок элементов с одинаковыми значениями.

Примеры

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

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

Также поддерживается сортировка по выражениям.

>>> df.sort(pl.col("a") + pl.col("b") * 2, nulls_last=True)
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ 2    ┆ 5.0 ┆ c   │
│ 1    ┆ 6.0 ┆ a   │
│ null ┆ 4.0 ┆ b   │
└──────┴─────┴─────┘

Чтобы отсортировать по нескольким столбцам, передайте список столбцов.

>>> df.sort(["c", "a"], descending=True)
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ 2    ┆ 5.0 ┆ c   │
│ null ┆ 4.0 ┆ b   │
│ 1    ┆ 6.0 ┆ a   │
└──────┴─────┴─────┘

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

>>> df.sort("c", "a", descending=[False, True])
shape: (3, 3)
┌──────┬─────┬─────┐
│ a    ┆ b   ┆ c   │
│ ---  ┆ --- ┆ --- │
│ i64  ┆ f64 ┆ str │
╞══════╪═════╪═════╡
│ 1    ┆ 6.0 ┆ a   │
│ null ┆ 4.0 ┆ b   │
│ 2    ┆ 5.0 ┆ c   │
└──────┴─────┴─────┘

sql(
    query: str,
    *,
    table_name: str = 'self',
) → DataFrame

Выполнить SQL-запрос к DataFrame.

Добавлено в версии 0.20.24.

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

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

Параметры:

query

SQL-запрос для выполнения.

table_name

Необязательно: явно задать имя таблицы, представляющей текущий фрейм (по умолчанию — “self”).

См. также

SQLContext

Примечания

• Вызывающий DataFrame автоматически регистрируется как таблица в SQLContext под именем “self”. Чтобы получить доступ к DataFrame и LazyFrame из текущего пространства имён globals, используйте функцию верхнего уровня pl.sql.
• Для более гибкого управления регистрацией и выполнением используйте объект SQLContext.
• SQL-запрос выполняется в ленивом режиме, а затем собирается и возвращается в виде DataFrame.

Примеры

>>> from datetime import date
>>> df1 = pl.DataFrame(
...     {
...         "a": [1, 2, 3],
...         "b": ["zz", "yy", "xx"],
...         "c": [date(1999, 12, 31), date(2010, 10, 10), date(2077, 8, 8)],
...     }
... )

Запрос к DataFrame с использованием SQL:

>>> df1.sql("SELECT c, b FROM self WHERE a > 1")
shape: (2, 2)
┌────────────┬─────┐
│ c          ┆ b   │
│ ---        ┆ --- │
│ date       ┆ str │
╞════════════╪═════╡
│ 2010-10-10 ┆ yy  │
│ 2077-08-08 ┆ xx  │
└────────────┴─────┘

Применение преобразований к DataFrame с помощью SQL с псевдонимом “frame” для “self”.

>>> df1.sql(
...     query='''
...         SELECT
...             a,
...             (a % 2 == 0) AS a_is_even,
...             CONCAT_WS(':', b, b) AS b_b,
...             EXTRACT(year FROM c) AS year,
...             0::float4 AS "zero",
...         FROM frame
...     ''',
...     table_name="frame",
... )
shape: (3, 5)
┌─────┬───────────┬───────┬──────┬──────┐
│ a   ┆ a_is_even ┆ b_b   ┆ year ┆ zero │
│ --- ┆ ---       ┆ ---   ┆ ---  ┆ ---  │
│ i64 ┆ bool      ┆ str   ┆ i32  ┆ f32  │
╞═════╪═══════════╪═══════╪══════╪══════╡
│ 1   ┆ false     ┆ zz:zz ┆ 1999 ┆ 0.0  │
│ 2   ┆ true      ┆ yy:yy ┆ 2010 ┆ 0.0  │
│ 3   ┆ false     ┆ xx:xx ┆ 2077 ┆ 0.0  │
└─────┴───────────┴───────┴──────┴──────┘

std(
    ddof: int = 1,
) → DataFrame

Вычислить стандартное отклонение значений столбцов этого DataFrame.

Параметры:

ddof

«Число степеней свободы»: делитель, используемый при вычислении, равен N - ddof, где N — количество элементов. По умолчанию ddof равен 1.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.std()
shape: (1, 3)
┌─────┬─────┬──────┐
│ foo ┆ bar ┆ ham  │
│ --- ┆ --- ┆ ---  │
│ f64 ┆ f64 ┆ str  │
╞═════╪═════╪══════╡
│ 1.0 ┆ 1.0 ┆ null │
└─────┴─────┴──────┘
>>> df.std(ddof=0)
shape: (1, 3)
┌──────────┬──────────┬──────┐
│ foo      ┆ bar      ┆ ham  │
│ ---      ┆ ---      ┆ ---  │
│ f64      ┆ f64      ┆ str  │
╞══════════╪══════════╪══════╡
│ 0.816497 ┆ 0.816497 ┆ null │
└──────────┴──────────┴──────┘

property style: GT

Создать таблицу Great Table для стилизации.

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

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

Polars не реализует логику стилизации самостоятельно, а делегирует её пакету Great Tables. Дополнительные сведения и документацию см. в справочнике Great Tables.

Примеры

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

>>> import polars.selectors as cs
>>> from great_tables import loc, style
>>> df = pl.DataFrame(
...     {
...         "site_id": [0, 1, 2],
...         "measure_a": [5, 4, 6],
...         "measure_b": [7, 3, 3],
...     }
... )

Используем site_id в качестве имён строк:

>>> df.style.tab_stub(rowname_col="site_id")  

Зададим цвет фона строки с наибольшим значением measure_a:

>>> df.style.tab_style(
...     style.fill("yellow"),
...     loc.body(rows=pl.col("measure_a") == pl.col("measure_a").max()),
... )  

Добавим объединённый заголовок над столбцами measure:

>>> df.style.tab_spanner(
...     "Measures", cs.starts_with("measure")
... )  

Отформатируем значения measure_b с точностью до двух знаков после запятой:

>>> df.style.fmt_number("measure_b", decimals=2)  

sum() → DataFrame

Вычислить сумму значений столбцов этого DataFrame.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.sum()
shape: (1, 3)
┌─────┬─────┬──────┐
│ foo ┆ bar ┆ ham  │
│ --- ┆ --- ┆ ---  │
│ i64 ┆ i64 ┆ str  │
╞═════╪═════╪══════╡
│ 6   ┆ 21  ┆ null │
└─────┴─────┴──────┘

sum_horizontal(
    *,
    ignore_nulls: bool = True,
) → Series

Сложить все значения по горизонтали, вдоль столбцов.

Параметры:

ignore_nulls

Игнорировать значения null (по умолчанию). Если задано False, любое значение null во входных данных приведёт к результату null.

Возвращает:

Series

Series с именем "sum".

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [4.0, 5.0, 6.0],
...     }
... )
>>> df.sum_horizontal()
shape: (3,)
Series: 'sum' [f64]
[
        5.0
        7.0
        9.0
]

tail(
    n: int = 5,
) → DataFrame

Получить последние n строк.

Параметры:

n

Количество возвращаемых строк. Если передано отрицательное значение, возвращаются все строки, кроме первых abs(n).

См. также

head, slice

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> df.tail(3)
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 3   ┆ 8   ┆ c   │
│ 4   ┆ 9   ┆ d   │
│ 5   ┆ 10  ┆ e   │
└─────┴─────┴─────┘

Передайте отрицательное значение, чтобы получить все строки, except первые abs(n).

>>> df.tail(-3)
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 4   ┆ 9   ┆ d   │
│ 5   ┆ 10  ┆ e   │
└─────┴─────┴─────┘

to_arrow(
    *,
    compat_level: CompatLevel | None = None,
) → Table

Собрать базовые массивы Arrow в таблицу Arrow.

Эта операция в основном выполняется без копирования данных.

Типы данных, для которых создаётся копия:

• CategoricalType

Изменено в версии 1.1: Параметр future переименован в compat_level.

Параметры:

compat_level

Уровень совместимости, используемый при экспорте структур данных Polars. Большинству пользователей рекомендуется уровень совместимости по умолчанию. Используйте pl.CompatLevel.oldest() для максимальной совместимости. pl.CompatLevel.newest() использует наивысший поддерживаемый уровень совместимости, но считается нестабильным и может измениться без того, чтобы это считалось нарушением совместимости.

Примеры

>>> df = pl.DataFrame(
...     {"foo": [1, 2, 3, 4, 5, 6], "bar": ["a", "b", "c", "d", "e", "f"]}
... )
>>> df.to_arrow()
pyarrow.Table
foo: int64
bar: large_string
----
foo: [[1,2,3,4,5,6]]
bar: [["a","b","c","d","e","f"]]

to_dict(
    *,
    as_series: bool = True,
) → dict[str, Series] | dict[str, list[Any]]

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

Параметры:

as_series

True -> значения представлены как Series False -> значения представлены как List[Any]

См. также

rows_by_key

to_dicts

Примеры

>>> 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"],
...         "optional": [28, 300, None, 2, -30],
...     }
... )
>>> df
shape: (5, 5)
┌─────┬────────┬─────┬────────┬──────────┐
│ A   ┆ fruits ┆ B   ┆ cars   ┆ optional │
│ --- ┆ ---    ┆ --- ┆ ---    ┆ ---      │
│ i64 ┆ str    ┆ i64 ┆ str    ┆ i64      │
╞═════╪════════╪═════╪════════╪══════════╡
│ 1   ┆ banana ┆ 5   ┆ beetle ┆ 28       │
│ 2   ┆ banana ┆ 4   ┆ audi   ┆ 300      │
│ 3   ┆ apple  ┆ 3   ┆ beetle ┆ null     │
│ 4   ┆ apple  ┆ 2   ┆ beetle ┆ 2        │
│ 5   ┆ banana ┆ 1   ┆ beetle ┆ -30      │
└─────┴────────┴─────┴────────┴──────────┘
>>> df.to_dict(as_series=False)
{'A': [1, 2, 3, 4, 5],
'fruits': ['banana', 'banana', 'apple', 'apple', 'banana'],
'B': [5, 4, 3, 2, 1],
'cars': ['beetle', 'audi', 'beetle', 'beetle', 'beetle'],
'optional': [28, 300, None, 2, -30]}
>>> df.to_dict(as_series=True)
{'A': shape: (5,)
Series: 'A' [i64]
[
    1
    2
    3
    4
    5
], 'fruits': shape: (5,)
Series: 'fruits' [str]
[
    "banana"
    "banana"
    "apple"
    "apple"
    "banana"
], 'B': shape: (5,)
Series: 'B' [i64]
[
    5
    4
    3
    2
    1
], 'cars': shape: (5,)
Series: 'cars' [str]
[
    "beetle"
    "audi"
    "beetle"
    "beetle"
    "beetle"
], 'optional': shape: (5,)
Series: 'optional' [i64]
[
    28
    300
    null
    2
    -30
]}

to_dicts() → list[dict[str, Any]]

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

Примечания

Если у вас есть временные значения с точностью ns, учтите, что Python изначально поддерживает точность только до μs; значения с точностью ns при преобразовании в Python будут усечены до микросекунд. Если это важно для вашего сценария использования, экспортируйте данные в другой формат (например, Arrow или NumPy).

Примеры

>>> df = pl.DataFrame({"foo": [1, 2, 3], "bar": [4, 5, 6]})
>>> df.to_dicts()
[{'foo': 1, 'bar': 4}, {'foo': 2, 'bar': 5}, {'foo': 3, 'bar': 6}]

to_dummies(
    columns: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    *,
    separator: str = '_',
    drop_first: bool = False,
    drop_nulls: bool = False,
) → DataFrame

Преобразовать категориальные переменные в фиктивные (индикаторные) переменные.

Параметры:

columns

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

separator

Разделитель, используемый при формировании имён столбцов.

drop_first

Удалить первую категорию из кодируемых переменных.

drop_nulls

Если в Series есть значения None, столбец null не создаётся

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2],
...         "bar": [3, 4],
...         "ham": ["a", "b"],
...     }
... )
>>> df.to_dummies()
shape: (2, 6)
┌───────┬───────┬───────┬───────┬───────┬───────┐
│ foo_1 ┆ foo_2 ┆ bar_3 ┆ bar_4 ┆ ham_a ┆ ham_b │
│ ---   ┆ ---   ┆ ---   ┆ ---   ┆ ---   ┆ ---   │
│ u8    ┆ u8    ┆ u8    ┆ u8    ┆ u8    ┆ u8    │
╞═══════╪═══════╪═══════╪═══════╪═══════╪═══════╡
│ 1     ┆ 0     ┆ 1     ┆ 0     ┆ 1     ┆ 0     │
│ 0     ┆ 1     ┆ 0     ┆ 1     ┆ 0     ┆ 1     │
└───────┴───────┴───────┴───────┴───────┴───────┘

>>> df.to_dummies(drop_first=True)
shape: (2, 3)
┌───────┬───────┬───────┐
│ foo_2 ┆ bar_4 ┆ ham_b │
│ ---   ┆ ---   ┆ ---   │
│ u8    ┆ u8    ┆ u8    │
╞═══════╪═══════╪═══════╡
│ 0     ┆ 0     ┆ 0     │
│ 1     ┆ 1     ┆ 1     │
└───────┴───────┴───────┘

>>> import polars.selectors as cs
>>> df.to_dummies(cs.integer(), separator=":")
shape: (2, 5)
┌───────┬───────┬───────┬───────┬─────┐
│ foo:1 ┆ foo:2 ┆ bar:3 ┆ bar:4 ┆ ham │
│ ---   ┆ ---   ┆ ---   ┆ ---   ┆ --- │
│ u8    ┆ u8    ┆ u8    ┆ u8    ┆ str │
╞═══════╪═══════╪═══════╪═══════╪═════╡
│ 1     ┆ 0     ┆ 1     ┆ 0     ┆ a   │
│ 0     ┆ 1     ┆ 0     ┆ 1     ┆ b   │
└───────┴───────┴───────┴───────┴─────┘

>>> df.to_dummies(cs.integer(), drop_first=True, separator=":")
shape: (2, 3)
┌───────┬───────┬─────┐
│ foo:2 ┆ bar:4 ┆ ham │
│ ---   ┆ ---   ┆ --- │
│ u8    ┆ u8    ┆ str │
╞═══════╪═══════╪═════╡
│ 0     ┆ 0     ┆ a   │
│ 1     ┆ 1     ┆ b   │
└───────┴───────┴─────┘

to_init_repr(
    n: int = 1000,
) → str

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

Параметры:

n

Использовать только первые n строк.

См. также

polars.Series.to_init_repr

polars.from_repr

Примеры

>>> df = pl.DataFrame(
...     [
...         pl.Series("foo", [1, 2, 3], dtype=pl.UInt8),
...         pl.Series("bar", [6.0, 7.0, 8.0], dtype=pl.Float32),
...         pl.Series("ham", ["a", "b", "c"], dtype=pl.String),
...     ]
... )
>>> print(df.to_init_repr())
pl.DataFrame(
    [
        pl.Series('foo', [1, 2, 3], dtype=pl.UInt8),
        pl.Series('bar', [6.0, 7.0, 8.0], dtype=pl.Float32),
        pl.Series('ham', ['a', 'b', 'c'], dtype=pl.String),
    ]
)

>>> df_from_str_repr = eval(df.to_init_repr())
>>> df_from_str_repr
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ u8  ┆ f32 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6.0 ┆ a   │
│ 2   ┆ 7.0 ┆ b   │
│ 3   ┆ 8.0 ┆ c   │
└─────┴─────┴─────┘

to_jax(
    return_type: JaxExportType = 'array',
    *,
    device: jax.Device | str | None = None,
    label: str | Expr | Sequence[str | Expr] | None = None,
    features: str | Expr | Sequence[str | Expr] | None = None,
    dtype: PolarsDataType | None = None,
    order: IndexOrder = 'fortran',
) → jax.Array | dict[str, jax.Array]

Преобразовать DataFrame в массив Jax или словарь массивов Jax.

Добавлено в версии 0.20.27.

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

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

Параметры:

return_type{“array”, “dict”}

Задать тип возвращаемого значения: массив Jax или словарь массивов Jax.

device

Задать устройство jax Device, на котором будет создан массив; можно передать строку (например, “cpu”, “gpu” или “tpu”), и в этом случае устройство будет получено как jax.devices(string)[0]. Для более точного управления можно напрямую передать созданный объект Device. Если задано None, массивы создаются на устройстве по умолчанию.

label

Одно или несколько имён столбцов, выражений или селекторов, обозначающих данные меток; если return_type имеет значение “dict”, вместо словаря {"col": array, } возвращается словарь {"label": ..., "features": ...}.

features

Одно или несколько имён столбцов, выражений или селекторов, содержащих данные признаков; если параметр не указан, используются все столбцы, не отнесённые к меткам. Применяется только, когда return_type имеет значение “dict”.

dtype

Унифицировать типы данных всех возвращаемых массивов; перед преобразованием в Array тип данных каждого столбца, который ещё не имеет требуемого типа, будет изменён. Обратите внимание: экспорт выполняется с одинарной точностью (32 бита), если конфигурация или среда Jax не задаёт иное (например, если “jax_enable_x64” установлено в True в объекте конфигурации при запуске или если переменная среды “JAX_ENABLE_X64” установлена в “1”).

order{“c”, “fortran”}

Порядок индексов возвращаемого массива Jax: в стиле C (по строкам) или Fortran (по столбцам).

См. также

to_dummies

to_numpy

to_torch

Примеры

>>> df = pl.DataFrame(
...     {
...         "lbl": [0, 1, 2, 3],
...         "feat1": [1, 0, 0, 1],
...         "feat2": [1.5, -0.5, 0.0, -2.25],
...     }
... )

Стандартный тип возвращаемого значения (2D-массив) на устройстве по умолчанию:

>>> df.to_jax()
Array([[ 0.  ,  1.  ,  1.5 ],
       [ 1.  ,  0.  , -0.5 ],
       [ 2.  ,  0.  ,  0.  ],
       [ 3.  ,  1.  , -2.25]], dtype=float32)

Создать массив на графическом процессоре по умолчанию:

>>> a = df.to_jax(device="gpu")  
>>> a.device()  
GpuDevice(id=0, process_index=0)

Создать массив на определённом графическом процессоре:

>>> gpu_device = jax.devices("gpu")[1]  
>>> a = df.to_jax(device=gpu_device)  
>>> a.device()  
GpuDevice(id=1, process_index=0)

В виде словаря отдельных массивов:

>>> df.to_jax("dict")
{'lbl': Array([0, 1, 2, 3], dtype=int32),
 'feat1': Array([1, 0, 0, 1], dtype=int32),
 'feat2': Array([ 1.5 , -0.5 ,  0.  , -2.25], dtype=float32)}

В виде словаря с “label” и “features”; обратите внимание, что параметр “features” не задан, поэтому по умолчанию в него входят все столбцы, не включённые в “label”:

>>> df.to_jax("dict", label="lbl")
{'label': Array([[0],
        [1],
        [2],
        [3]], dtype=int32),
 'features': Array([[ 1.  ,  1.5 ],
        [ 0.  , -0.5 ],
        [ 0.  ,  0.  ],
        [ 1.  , -2.25]], dtype=float32)}

В виде словаря с “label” и “features”, где каждый из них задан выражением col или селектором (их также можно использовать для приведения данных к типам, если для меток и признаков лучше подходят разные типы данных):

>>> import polars.selectors as cs
>>> df.to_jax(
...     return_type="dict",
...     features=cs.float(),
...     label=pl.col("lbl").cast(pl.UInt8),
... )
{'label': Array([[0],
        [1],
        [2],
        [3]], dtype=uint8),
 'features': Array([[ 1.5 ],
        [-0.5 ],
        [ 0.  ],
        [-2.25]], dtype=float32)}

to_numpy(
    *,
    order: IndexOrder = 'fortran',
    writable: bool = False,
    allow_copy: bool = True,
    structured: bool = False,
    use_pyarrow: bool | None = None,
) → np.ndarray[Any, Any]

Преобразовать этот DataFrame в ndarray NumPy.

Эта операция копирует данные только при необходимости. Преобразование выполняется без копирования, если соблюдаются все следующие условия:

• DataFrame полностью непрерывен в памяти: все Series расположены последовательно, и каждая Series состоит из одного фрагмента.
• Тип данных — целое число или число с плавающей запятой.
• DataFrame не содержит значений null.
• Параметр order установлен в fortran (по умолчанию).
• Параметр writable установлен в False (по умолчанию).

Параметры:

order

Порядок индексов возвращаемого массива NumPy: в стиле C или Fortran. Как правило, использование порядка индексов в стиле Fortran выполняется быстрее. Однако для последующих приложений может быть предпочтительнее порядок в стиле C, чтобы избежать клонирования данных, например при преобразовании массива в одномерный.

writable

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

allow_copy

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

structured

Вернуть структурированный массив с типом данных, соответствующим схеме DataFrame. Если установлено значение False (по умолчанию), вместо него возвращается двумерный ndarray.

use_pyarrow

При необходимости использовать pyarrow.Array.to_numpy

для преобразования в NumPy.

Устарело с версии 0.20.28: Теперь Polars по умолчанию использует для преобразования в NumPy собственный движок.

Примеры

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

>>> df = pl.DataFrame({"a": [1, 2, 3]})
>>> arr = df.to_numpy()
>>> arr
array([[1],
       [2],
       [3]])
>>> arr.flags.writeable
False

Установите writable=True, чтобы принудительно скопировать данные и сделать массив доступным для записи.

>>> df.to_numpy(writable=True).flags.writeable
True

Если DataFrame содержит данные с разными числовыми типами, результирующий тип данных будет общим супертипом. Для этого потребуется копирование данных. Целочисленные типы со значениями null преобразуются в тип с плавающей запятой, где nan обозначает значение null.

>>> df = pl.DataFrame({"a": [1, 2, None], "b": [4.0, 5.0, 6.0]})
>>> df.to_numpy()
array([[ 1.,  4.],
       [ 2.,  5.],
       [nan,  6.]])

Установите allow_copy=False, чтобы вызвать ошибку, если потребуется копирование данных.

>>> s.to_numpy(allow_copy=False)  
Traceback (most recent call last):
...
RuntimeError: copy not allowed: cannot convert to a NumPy array without copying data

По умолчанию Polars использует порядок с непрерывным хранением в стиле F. Используйте order="c", чтобы результирующий массив имел непрерывное хранение в стиле C.

>>> df.to_numpy(order="c").flags.c_contiguous
True

DataFrame со смешанными типами данных будет преобразован в массив с типом object.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.5, 7.0, 8.5],
...         "ham": ["a", "b", "c"],
...     },
...     schema_overrides={"foo": pl.UInt8, "bar": pl.Float32},
... )
>>> df.to_numpy()
array([[1, 6.5, 'a'],
       [2, 7.0, 'b'],
       [3, 8.5, 'c']], dtype=object)

Установите structured=True, чтобы преобразовать данные в структурированный массив, который позволяет лучше сохранять отдельные данные столбцов, например имя и тип данных.

>>> df.to_numpy(structured=True)
array([(1, 6.5, 'a'), (2, 7. , 'b'), (3, 8.5, 'c')],
      dtype=[('foo', 'u1'), ('bar', '<f4'), ('ham', '<U1')])

to_pandas(
    *,
    use_pyarrow_extension_array: bool = False,
    **kwargs: Any,
) → DataFrame

Преобразовать этот DataFrame в DataFrame pandas.

Эта операция копирует данные, если параметр use_pyarrow_extension_array не включён.

Параметры:

use_pyarrow_extension_array

Использовать для столбцов DataFrame pandas массивы расширений на основе PyArrow вместо массивов NumPy. Это позволяет выполнять операции без копирования и сохранять значения null. Последующие операции над результирующим DataFrame pandas могут вызвать преобразование в NumPy, если они не поддерживаются вычислительными функциями PyArrow.

**kwargs

Дополнительные именованные аргументы, передаваемые в pyarrow.Table.to_pandas().

Возвращает:

pandas.DataFrame

Примечания

Для выполнения этой операции необходимо установить pandas и pyarrow.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6.0, 7.0, 8.0],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.to_pandas()
   foo  bar ham
0    1  6.0   a
1    2  7.0   b
2    3  8.0   c

Значения null в числовых столбцах преобразуются в NaN.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, None],
...         "bar": [6.0, None, 8.0],
...         "ham": [None, "b", "c"],
...     }
... )
>>> df.to_pandas()
   foo  bar  ham
0  1.0  6.0  NaN
1  2.0  NaN    b
2  NaN  8.0    c

Передайте use_pyarrow_extension_array=True, чтобы получить DataFrame pandas со столбцами на основе массивов расширений PyArrow. Это позволит сохранить значения null.

>>> df.to_pandas(use_pyarrow_extension_array=True)
    foo   bar   ham
0     1   6.0  <NA>
1     2  <NA>     b
2  <NA>   8.0     c
>>> _.dtypes
foo           int64[pyarrow]
bar          double[pyarrow]
ham    large_string[pyarrow]
dtype: object

to_series(
    index: int = 0,
) → Series

Выбрать столбец как Series по индексу.

Параметры:

index

Индекс выбранного элемента.

См. также

get_column

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.to_series(1)
shape: (3,)
Series: 'bar' [i64]
[
        6
        7
        8
]

to_struct(
    name: str = '',
) → Series

Преобразовать DataFrame в Series типа Struct.

Параметры:

name

Имя структурной Series.

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 4, 5],
...         "b": ["one", "two", "three", "four", "five"],
...     }
... )
>>> df.to_struct("nums")
shape: (5,)
Series: 'nums' [struct[2]]
[
    {1,"one"}
    {2,"two"}
    {3,"three"}
    {4,"four"}
    {5,"five"}
]

to_torch(
    return_type: TorchExportType = 'tensor',
    *,
    label: str | Expr | Sequence[str | Expr] | None = None,
    features: str | Expr | Sequence[str | Expr] | None = None,
    dtype: PolarsDataType | None = None,
) → torch.Tensor | dict[str, torch.Tensor] | PolarsDataset

Преобразовать DataFrame в тензор PyTorch, набор данных или словарь тензоров.

Добавлено в версии 0.20.23.

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

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

Параметры:

return_type{“tensor”, “dataset”, “dict”}

Задать тип возвращаемого значения: тензор PyTorch, PolarsDataset (специализированный для фреймов TensorDataset) или словарь тензоров.

label

Одно или несколько имён столбцов, выражений или селекторов, задающих метки для данных признаков; если return_type равно «dataset», PolarsDataset будет возвращать кортежи тензоров (features, label) для каждой строки. В противном случае он возвращает кортежи тензоров (features,), в которых признак содержит все данные строки.

features

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

dtype

Унифицировать тип данных всех возвращаемых тензоров; перед преобразованием в тензор столбцы, тип которых отличается от требуемого, будут приведены к нему. Это относится и к столбцу меток, если только метка не является выражением (например, pl.col("label_column").cast(pl.Int16)).

См. также

to_dummies

to_jax

to_numpy

Примеры

>>> df = pl.DataFrame(
...     {
...         "lbl": [0, 1, 2, 3],
...         "feat1": [1, 0, 0, 1],
...         "feat2": [1.5, -0.5, 0.0, -2.25],
...     }
... )

Стандартный тип возвращаемого значения (Tensor) с супертипом f32:

>>> df.to_torch(dtype=pl.Float32)
tensor([[ 0.0000,  1.0000,  1.5000],
        [ 1.0000,  0.0000, -0.5000],
        [ 2.0000,  0.0000,  0.0000],
        [ 3.0000,  1.0000, -2.2500]])

В виде словаря отдельных тензоров:

>>> df.to_torch("dict")
{'lbl': tensor([0, 1, 2, 3]),
 'feat1': tensor([1, 0, 0, 1]),
 'feat2': tensor([ 1.5000, -0.5000,  0.0000, -2.2500], dtype=torch.float64)}

В виде словаря «label» и «features». Обратите внимание: поскольку «features» не задан, по умолчанию используются все столбцы, кроме входящих в «label»:

>>> df.to_torch("dict", label="lbl", dtype=pl.Float32)
{'label': tensor([[0.],
         [1.],
         [2.],
         [3.]]),
 'features': tensor([[ 1.0000,  1.5000],
         [ 0.0000, -0.5000],
         [ 0.0000,  0.0000],
         [ 1.0000, -2.2500]])}

В виде PolarsDataset с супертипом f64:

>>> ds = df.to_torch("dataset", dtype=pl.Float64)
>>> ds[3]
(tensor([ 3.0000,  1.0000, -2.2500], dtype=torch.float64),)
>>> ds[:2]
(tensor([[ 0.0000,  1.0000,  1.5000],
         [ 1.0000,  0.0000, -0.5000]], dtype=torch.float64),)
>>> ds[[0, 3]]
(tensor([[ 0.0000,  1.0000,  1.5000],
         [ 3.0000,  1.0000, -2.2500]], dtype=torch.float64),)

Для удобства в PolarsDataset можно включить данные половинной точности для экспериментов (обычно это задаётся для модели или конвейера):

>>> list(ds.half())
[(tensor([0.0000, 1.0000, 1.5000], dtype=torch.float16),),
 (tensor([ 1.0000,  0.0000, -0.5000], dtype=torch.float16),),
 (tensor([2., 0., 0.], dtype=torch.float16),),
 (tensor([ 3.0000,  1.0000, -2.2500], dtype=torch.float16),)]

Передать PolarsDataset в DataLoader, указав метку:

>>> from torch.utils.data import DataLoader
>>> ds = df.to_torch("dataset", label="lbl")
>>> dl = DataLoader(ds, batch_size=2)
>>> batches = list(dl)
>>> batches[0]
[tensor([[ 1.0000,  1.5000],
         [ 0.0000, -0.5000]], dtype=torch.float64), tensor([0, 1])]

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

>>> ds = df.to_torch(
...     return_type="dataset",
...     dtype=pl.Float32,
...     label=pl.col("lbl").cast(pl.Int16),
... )
>>> ds[:2]
(tensor([[ 1.0000,  1.5000],
         [ 0.0000, -0.5000]]), tensor([0, 1], dtype=torch.int16))

Простая интеграция, например, со scikit-learn и другими наборами данных:

>>> from sklearn.datasets import fetch_california_housing  
>>> housing = fetch_california_housing()  
>>> df = pl.DataFrame(
...     data=housing.data,
...     schema=housing.feature_names,
... ).with_columns(
...     Target=housing.target,
... )  
>>> train = df.to_torch("dataset", label="Target")  
>>> loader = DataLoader(
...     train,
...     shuffle=True,
...     batch_size=64,
... )  

top_k(
    k: int,
    *,
    by: IntoExpr | Iterable[IntoExpr],
    reverse: bool | Sequence[bool] = False,
) → DataFrame

Вернуть k строк с наибольшими значениями.

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

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

Параметры:

k

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

by

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

reverse

Рассматривать k наименьших элементов столбца или столбцов by (вместо k наибольших). Для каждого столбца можно задать отдельное значение, передав последовательность логических значений.

См. также

bottom_k

Примеры

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

Получить строки, содержащие 4 наибольших значения в столбце b.

>>> df.top_k(4, by="b")
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 3   │
│ a   ┆ 2   │
│ b   ┆ 2   │
│ b   ┆ 1   │
└─────┴─────┘

Получить строки с 4 наибольшими значениями при сортировке по столбцам b и a.

>>> df.top_k(4, by=["b", "a"])
shape: (4, 2)
┌─────┬─────┐
│ a   ┆ b   │
│ --- ┆ --- │
│ str ┆ i64 │
╞═════╪═════╡
│ b   ┆ 3   │
│ b   ┆ 2   │
│ a   ┆ 2   │
│ c   ┆ 1   │
└─────┴─────┘

transpose(
    *,
    include_header: bool = False,
    header_name: str = 'column',
    column_names: str | Iterable[str] | None = None,
) → DataFrame

Транспонировать DataFrame относительно диагонали.

Параметры:

include_header

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

header_name

Если задан параметр include_header, он определяет имя добавляемого столбца.

column_names

Необязательный итерируемый объект, возвращающий строки, или строка с именем существующего столбца. Эти значения станут именами столбцов со значениями (не заголовков) в транспонированных данных.

Возвращает:

DataFrame

Примечания

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

Примеры

>>> df = pl.DataFrame({"a": [1, 2, 3], "b": [4, 5, 6]})
>>> df.transpose(include_header=True)
shape: (2, 4)
┌────────┬──────────┬──────────┬──────────┐
│ column ┆ column_0 ┆ column_1 ┆ column_2 │
│ ---    ┆ ---      ┆ ---      ┆ ---      │
│ str    ┆ i64      ┆ i64      ┆ i64      │
╞════════╪══════════╪══════════╪══════════╡
│ a      ┆ 1        ┆ 2        ┆ 3        │
│ b      ┆ 4        ┆ 5        ┆ 6        │
└────────┴──────────┴──────────┴──────────┘

Заменить автоматически сгенерированные имена столбцов списком

>>> df.transpose(include_header=False, column_names=["x", "y", "z"])
shape: (2, 3)
┌─────┬─────┬─────┐
│ x   ┆ y   ┆ z   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘

Включить заголовок в качестве отдельного столбца

>>> df.transpose(
...     include_header=True, header_name="foo", column_names=["x", "y", "z"]
... )
shape: (2, 4)
┌─────┬─────┬─────┬─────┐
│ foo ┆ x   ┆ y   ┆ z   │
│ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╪═════╡
│ a   ┆ 1   ┆ 2   ┆ 3   │
│ b   ┆ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┴─────┘

Заменить автоматически сгенерированные имена столбцов именами, полученными из функции-генератора

>>> def name_generator():
...     base_name = "my_column_"
...     count = 0
...     while True:
...         yield f"{base_name}{count}"
...         count += 1
>>> df.transpose(include_header=False, column_names=name_generator())
shape: (2, 3)
┌─────────────┬─────────────┬─────────────┐
│ my_column_0 ┆ my_column_1 ┆ my_column_2 │
│ ---         ┆ ---         ┆ ---         │
│ i64         ┆ i64         ┆ i64         │
╞═════════════╪═════════════╪═════════════╡
│ 1           ┆ 2           ┆ 3           │
│ 4           ┆ 5           ┆ 6           │
└─────────────┴─────────────┴─────────────┘

Использовать существующий столбец в качестве новых имён столбцов

>>> df = pl.DataFrame(dict(id=["i", "j", "k"], a=[1, 2, 3], b=[4, 5, 6]))
>>> df.transpose(column_names="id")
shape: (2, 3)
┌─────┬─────┬─────┐
│ i   ┆ j   ┆ k   │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ i64 │
╞═════╪═════╪═════╡
│ 1   ┆ 2   ┆ 3   │
│ 4   ┆ 5   ┆ 6   │
└─────┴─────┴─────┘
>>> df.transpose(include_header=True, header_name="new_id", column_names="id")
shape: (2, 4)
┌────────┬─────┬─────┬─────┐
│ new_id ┆ i   ┆ j   ┆ k   │
│ ---    ┆ --- ┆ --- ┆ --- │
│ str    ┆ i64 ┆ i64 ┆ i64 │
╞════════╪═════╪═════╪═════╡
│ a      ┆ 1   ┆ 2   ┆ 3   │
│ b      ┆ 4   ┆ 5   ┆ 6   │
└────────┴─────┴─────┴─────┘

unique(
    subset: IntoExpr | Collection[IntoExpr] | None = None,
    *,
    keep: UniqueKeepStrategy = 'any',
    maintain_order: bool = False,
) → DataFrame

Удалить из этого DataFrame повторяющиеся строки.

Параметры:

subset

Имена столбцов, селекторы или выражения, используемые для поиска повторяющихся строк. Если установлено значение None (по умолчанию), учитываются все столбцы.

keep{‘first’, ‘last’, ‘any’, ‘none’}

Указывает, какую из повторяющихся строк следует сохранить.

• «any»: не гарантирует, какая именно строка будет сохранена.

  Это позволяет выполнять дополнительные оптимизации.

• «none»: не сохранять повторяющиеся строки.
• «first»: сохранить первую уникальную строку.
• «last»: сохранить последнюю уникальную строку.

maintain_order

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

Возвращает:

DataFrame

DataFrame с уникальными строками.

Примечания

Для тех, кто знаком с Pandas: эта функция похожа на pandas.DataFrame.drop_duplicates.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 1, 1],
...         "bar": ["a", "a", "a", "x", "x"],
...         "ham": ["b", "b", "b", "y", "y"],
...     }
... )

По умолчанию при определении уникальности строк учитываются все столбцы:

>>> df.unique(maintain_order=True)
shape: (4, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ a   ┆ b   │
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
│ 1   ┆ x   ┆ y   │
└─────┴─────┴─────┘

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

>>> df.unique(subset="foo", keep="first", maintain_order=True)
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ a   ┆ b   │
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
└─────┴─────┴─────┘
>>> df.unique(subset="foo", keep="last", maintain_order=True)
shape: (3, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
│ 1   ┆ x   ┆ y   │
└─────┴─────┴─────┘
>>> df.unique(subset="foo", keep="none", maintain_order=True)
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 2   ┆ a   ┆ b   │
│ 3   ┆ a   ┆ b   │
└─────┴─────┴─────┘

Для задания параметра «subset» можно использовать селекторы:

>>> import polars.selectors as cs
>>> df.unique(subset=cs.string(), maintain_order=True)
shape: (2, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ a   ┆ b   │
│ 1   ┆ x   ┆ y   │
└─────┴─────┴─────┘

Для параметра «subset» можно также использовать произвольное выражение. В этом примере для определения уникальности используется часть метки перед «:»:

>>> df = pl.DataFrame(
...     {
...         "label": ["xx:1", "xx:2", "yy:3", "yy:4"],
...         "value": [100, 200, 300, 400],
...     }
... )
>>> df.unique(
...     subset=pl.col("label").str.extract(r"^(\w+):"),
...     maintain_order=True,
...     keep="first",
... )
shape: (2, 2)
┌───────┬───────┐
│ label ┆ value │
│ ---   ┆ ---   │
│ str   ┆ i64   │
╞═══════╪═══════╡
│ xx:1  ┆ 100   │
│ yy:3  ┆ 300   │
└───────┴───────┘

unnest(
    columns: ColumnNameOrSelector | Collection[ColumnNameOrSelector] | None = None,
    *more_columns: ColumnNameOrSelector,
    separator: str | None = None,
) → DataFrame

Разложить структурные столбцы на отдельные столбцы для каждого поля.

Новые столбцы будут вставлены во фрейм на место структурного столбца.

Если столбцы не указаны, будут разложены все структурные столбцы.

Параметры:

columns

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

*more_columns

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

separator

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "before": ["foo", "bar"],
...         "t_a": [1, 2],
...         "t_b": ["a", "b"],
...         "t_c": [True, None],
...         "t_d": [[1, 2], [3]],
...         "after": ["baz", "womp"],
...     }
... ).select("before", pl.struct(pl.col("^t_.$")).alias("t_struct"), "after")
>>> df
shape: (2, 3)
┌────────┬─────────────────────┬───────┐
│ before ┆ t_struct            ┆ after │
│ ---    ┆ ---                 ┆ ---   │
│ str    ┆ struct[4]           ┆ str   │
╞════════╪═════════════════════╪═══════╡
│ foo    ┆ {1,"a",true,[1, 2]} ┆ baz   │
│ bar    ┆ {2,"b",null,[3]}    ┆ womp  │
└────────┴─────────────────────┴───────┘
>>> df.unnest("t_struct")
shape: (2, 6)
┌────────┬─────┬─────┬──────┬───────────┬───────┐
│ before ┆ t_a ┆ t_b ┆ t_c  ┆ t_d       ┆ after │
│ ---    ┆ --- ┆ --- ┆ ---  ┆ ---       ┆ ---   │
│ str    ┆ i64 ┆ str ┆ bool ┆ list[i64] ┆ str   │
╞════════╪═════╪═════╪══════╪═══════════╪═══════╡
│ foo    ┆ 1   ┆ a   ┆ true ┆ [1, 2]    ┆ baz   │
│ bar    ┆ 2   ┆ b   ┆ null ┆ [3]       ┆ womp  │
└────────┴─────┴─────┴──────┴───────────┴───────┘

Разложить все структурные столбцы, вызвав функцию без аргументов:

>>> df.unnest()
shape: (2, 6)
┌────────┬─────┬─────┬──────┬───────────┬───────┐
│ before ┆ t_a ┆ t_b ┆ t_c  ┆ t_d       ┆ after │
│ ---    ┆ --- ┆ --- ┆ ---  ┆ ---       ┆ ---   │
│ str    ┆ i64 ┆ str ┆ bool ┆ list[i64] ┆ str   │
╞════════╪═════╪═════╪══════╪═══════════╪═══════╡
│ foo    ┆ 1   ┆ a   ┆ true ┆ [1, 2]    ┆ baz   │
│ bar    ┆ 2   ┆ b   ┆ null ┆ [3]       ┆ womp  │
└────────┴─────┴─────┴──────┴───────────┴───────┘

>>> df = pl.DataFrame(
...     {
...         "before": ["foo", "bar"],
...         "t_a": [1, 2],
...         "t_b": ["a", "b"],
...         "t_c": [True, None],
...         "t_d": [[1, 2], [3]],
...         "after": ["baz", "womp"],
...     }
... ).select(
...     "before",
...     pl.struct(pl.col("^t_.$").name.map(lambda t: t[2:])).alias("t"),
...     "after",
... )
>>> df.unnest("t", separator="::")
shape: (2, 6)
┌────────┬──────┬──────┬──────┬───────────┬───────┐
│ before ┆ t::a ┆ t::b ┆ t::c ┆ t::d      ┆ after │
│ ---    ┆ ---  ┆ ---  ┆ ---  ┆ ---       ┆ ---   │
│ str    ┆ i64  ┆ str  ┆ bool ┆ list[i64] ┆ str   │
╞════════╪══════╪══════╪══════╪═══════════╪═══════╡
│ foo    ┆ 1    ┆ a    ┆ true ┆ [1, 2]    ┆ baz   │
│ bar    ┆ 2    ┆ b    ┆ null ┆ [3]       ┆ womp  │
└────────┴──────┴──────┴──────┴───────────┴───────┘

unpivot(
    on: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    *,
    index: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    variable_name: str | None = None,
    value_name: str | None = None,
) → DataFrame

Преобразовать DataFrame из широкого формата в длинный.

Идентификаторы при этом можно оставить.

Эта функция помогает преобразовать DataFrame в формат, где один или несколько столбцов являются переменными-идентификаторами (индексом), а все остальные столбцы, рассматриваемые как измеряемые переменные (on), «переворачиваются» в ось строк. В результате остаются только два столбца, не являющихся идентификаторами: «variable» и «value».

Параметры:

on

Столбец или столбцы, селекторы для использования в качестве переменных-значений; если on пуст, столбцы использоваться не будут. Если установлено значение None (по умолчанию), будут использоваться все столбцы, отсутствующие в index.

index

Столбец или столбцы, селекторы для использования в качестве переменных-идентификаторов.

variable_name

Имя столбца variable. По умолчанию — «variable».

value_name

Имя столбца value. По умолчанию — «value».

Примечания

Для тех, кто знаком с pandas: эта функция похожа на pandas.DataFrame.melt, но вместо id_vars используется index, а вместо value_vars — on. В других фреймворках эта операция может называться pivot_longer.

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": ["x", "y", "z"],
...         "b": [1, 3, 5],
...         "c": [2, 4, 6],
...     }
... )
>>> import polars.selectors as cs
>>> df.unpivot(cs.numeric(), index="a")
shape: (6, 3)
┌─────┬──────────┬───────┐
│ a   ┆ variable ┆ value │
│ --- ┆ ---      ┆ ---   │
│ str ┆ str      ┆ i64   │
╞═════╪══════════╪═══════╡
│ x   ┆ b        ┆ 1     │
│ y   ┆ b        ┆ 3     │
│ z   ┆ b        ┆ 5     │
│ x   ┆ c        ┆ 2     │
│ y   ┆ c        ┆ 4     │
│ z   ┆ c        ┆ 6     │
└─────┴──────────┴───────┘

unstack(
    *,
    step: int,
    how: UnstackDirection = 'vertical',
    columns: ColumnNameOrSelector | Sequence[ColumnNameOrSelector] | None = None,
    fill_values: list[Any] | None = None,
) → DataFrame

Преобразовать длинную таблицу в широкую без выполнения агрегации.

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

Параметры:

step

Количество строк в преобразованном фрейме.

how{ ‘vertical’, ‘horizontal’ }

Направление преобразования.

columns

Имя или имена столбцов либо селекторы для включения в операцию. Если установлено значение None (по умолчанию), используются все столбцы.

fill_values

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

Примеры

>>> from string import ascii_uppercase
>>> df = pl.DataFrame(
...     {
...         "x": list(ascii_uppercase[0:8]),
...         "y": pl.int_range(1, 9, eager=True),
...     }
... ).with_columns(
...     z=pl.int_ranges(pl.col("y"), pl.col("y") + 2, dtype=pl.UInt8),
... )
>>> df
shape: (8, 3)
┌─────┬─────┬──────────┐
│ x   ┆ y   ┆ z        │
│ --- ┆ --- ┆ ---      │
│ str ┆ i64 ┆ list[u8] │
╞═════╪═════╪══════════╡
│ A   ┆ 1   ┆ [1, 2]   │
│ B   ┆ 2   ┆ [2, 3]   │
│ C   ┆ 3   ┆ [3, 4]   │
│ D   ┆ 4   ┆ [4, 5]   │
│ E   ┆ 5   ┆ [5, 6]   │
│ F   ┆ 6   ┆ [6, 7]   │
│ G   ┆ 7   ┆ [7, 8]   │
│ H   ┆ 8   ┆ [8, 9]   │
└─────┴─────┴──────────┘
>>> df.unstack(step=4, how="vertical")
shape: (4, 6)
┌─────┬─────┬─────┬─────┬──────────┬──────────┐
│ x_0 ┆ x_1 ┆ y_0 ┆ y_1 ┆ z_0      ┆ z_1      │
│ --- ┆ --- ┆ --- ┆ --- ┆ ---      ┆ ---      │
│ str ┆ str ┆ i64 ┆ i64 ┆ list[u8] ┆ list[u8] │
╞═════╪═════╪═════╪═════╪══════════╪══════════╡
│ A   ┆ E   ┆ 1   ┆ 5   ┆ [1, 2]   ┆ [5, 6]   │
│ B   ┆ F   ┆ 2   ┆ 6   ┆ [2, 3]   ┆ [6, 7]   │
│ C   ┆ G   ┆ 3   ┆ 7   ┆ [3, 4]   ┆ [7, 8]   │
│ D   ┆ H   ┆ 4   ┆ 8   ┆ [4, 5]   ┆ [8, 9]   │
└─────┴─────┴─────┴─────┴──────────┴──────────┘
>>> df.unstack(step=2, how="horizontal")
shape: (4, 6)
┌─────┬─────┬─────┬─────┬──────────┬──────────┐
│ x_0 ┆ x_1 ┆ y_0 ┆ y_1 ┆ z_0      ┆ z_1      │
│ --- ┆ --- ┆ --- ┆ --- ┆ ---      ┆ ---      │
│ str ┆ str ┆ i64 ┆ i64 ┆ list[u8] ┆ list[u8] │
╞═════╪═════╪═════╪═════╪══════════╪══════════╡
│ A   ┆ B   ┆ 1   ┆ 2   ┆ [1, 2]   ┆ [2, 3]   │
│ C   ┆ D   ┆ 3   ┆ 4   ┆ [3, 4]   ┆ [4, 5]   │
│ E   ┆ F   ┆ 5   ┆ 6   ┆ [5, 6]   ┆ [6, 7]   │
│ G   ┆ H   ┆ 7   ┆ 8   ┆ [7, 8]   ┆ [8, 9]   │
└─────┴─────┴─────┴─────┴──────────┴──────────┘
>>> import polars.selectors as cs
>>> df.unstack(step=5, columns=cs.numeric(), fill_values=0)
shape: (5, 2)
┌─────┬─────┐
│ y_0 ┆ y_1 │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 6   │
│ 2   ┆ 7   │
│ 3   ┆ 8   │
│ 4   ┆ 0   │
│ 5   ┆ 0   │
└─────┴─────┘

update(
    other: DataFrame,
    on: str | Sequence[str] | None = None,
    how: Literal['left',
    'inner',
    'full'] = 'left',
    *,
    left_on: str | Sequence[str] | None = None,
    right_on: str | Sequence[str] | None = None,
    include_nulls: bool = False,
    maintain_order: MaintainOrderJoin | None = 'left',
) → DataFrame

Обновить значения в этом DataFrame значениями из other.

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

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

Параметры:

other

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

on

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

how{‘left’, ‘inner’, ‘full’}

• «left» сохранит все строки из левой таблицы; строки могут дублироваться, если ключу строки в левой таблице соответствуют несколько строк в правом фрейме.
• «inner» сохранит только строки, ключ которых присутствует в обоих фреймах.
• «full» обновит существующие строки с совпадающими ключами и добавит все новые строки из переданного фрейма.

left_on

Столбец или столбцы для соединения в левом DataFrame.

right_on

Столбец или столбцы для соединения в правом DataFrame.

include_nulls

Перезаписать значения в левом фрейме значениями null из правого фрейма. Если установлено значение False (по умолчанию), значения null в правом фрейме игнорируются.

maintain_order{‘none’, ‘left’, ‘right’, ‘left_right’, ‘right_left’}

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

Примечания

Это синтаксический сахар для левого или внутреннего соединения, которое по умолчанию сохраняет порядок левого DataFrame, с необязательным объединением столбцов при include_nulls = False.

Примеры

>>> df = pl.DataFrame(
...     {
...         "A": [1, 2, 3, 4],
...         "B": [400, 500, 600, 700],
...     }
... )
>>> df
shape: (4, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ 400 │
│ 2   ┆ 500 │
│ 3   ┆ 600 │
│ 4   ┆ 700 │
└─────┴─────┘
>>> new_df = pl.DataFrame(
...     {
...         "B": [-66, None, -99],
...         "C": [5, 3, 1],
...     }
... )

Обновить значения df ненулевыми значениями из new_df, используя индекс строк:

>>> df.update(new_df)
shape: (4, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ -66 │
│ 2   ┆ 500 │
│ 3   ┆ -99 │
│ 4   ┆ 700 │
└─────┴─────┘

Обновить значения df ненулевыми значениями из new_df, используя индекс строк, и оставить только строки, присутствующие в обоих фреймах:

>>> df.update(new_df, how="inner")
shape: (3, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ -66 │
│ 2   ┆ 500 │
│ 3   ┆ -99 │
└─────┴─────┘

Обновить значения df ненулевыми значениями из new_df, используя стратегию полного внешнего соединения с явным заданием столбцов для соединения в каждом фрейме:

>>> df.update(new_df, left_on=["A"], right_on=["C"], how="full")
shape: (5, 2)
┌─────┬─────┐
│ A   ┆ B   │
│ --- ┆ --- │
│ i64 ┆ i64 │
╞═════╪═════╡
│ 1   ┆ -99 │
│ 2   ┆ 500 │
│ 3   ┆ 600 │
│ 4   ┆ 700 │
│ 5   ┆ -66 │
└─────┴─────┘

Обновить значения df, включая значения null из new_df, используя стратегию полного внешнего соединения с явным заданием столбцов для соединения в каждом фрейме:

>>> df.update(new_df, left_on="A", right_on="C", how="full", include_nulls=True)
shape: (5, 2)
┌─────┬──────┐
│ A   ┆ B    │
│ --- ┆ ---  │
│ i64 ┆ i64  │
╞═════╪══════╡
│ 1   ┆ -99  │
│ 2   ┆ 500  │
│ 3   ┆ null │
│ 4   ┆ 700  │
│ 5   ┆ -66  │
└─────┴──────┘

upsample(
    time_column: str,
    *,
    every: str | timedelta,
    group_by: str | Sequence[str] | None = None,
    maintain_order: bool = False,
) → DataFrame

Выполнить передискретизацию DataFrame с регулярной частотой.

Аргумент every задаётся строкой следующего формата:

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

Или их комбинацией:

• «3d12h4m25s» # 3 дня, 12 часов, 4 минуты и 25 секунд

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

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

Параметры:

time_column

Столбец времени, используемый для определения date_range. Обратите внимание: для корректного результата этот столбец должен быть отсортирован.

every

Интервал будет начинаться через каждые заданные «every» промежутки времени.

group_by

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

maintain_order

Обеспечить предсказуемый порядок. Это замедляет выполнение.

Возвращает:

DataFrame

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

Примеры

Выполнить передискретизацию DataFrame с заданным интервалом.

>>> from datetime import datetime
>>> df = pl.DataFrame(
...     {
...         "time": [
...             datetime(2021, 2, 1),
...             datetime(2021, 4, 1),
...             datetime(2021, 5, 1),
...             datetime(2021, 6, 1),
...         ],
...         "groups": ["A", "B", "A", "B"],
...         "values": [0, 1, 2, 3],
...     }
... ).set_sorted("time")
>>> df.upsample(
...     time_column="time", every="1mo", group_by="groups", maintain_order=True
... ).select(pl.all().fill_null(strategy="forward"))
shape: (7, 3)
┌─────────────────────┬────────┬────────┐
│ time                ┆ groups ┆ values │
│ ---                 ┆ ---    ┆ ---    │
│ datetime[μs]        ┆ str    ┆ i64    │
╞═════════════════════╪════════╪════════╡
│ 2021-02-01 00:00:00 ┆ A      ┆ 0      │
│ 2021-03-01 00:00:00 ┆ A      ┆ 0      │
│ 2021-04-01 00:00:00 ┆ A      ┆ 0      │
│ 2021-05-01 00:00:00 ┆ A      ┆ 2      │
│ 2021-04-01 00:00:00 ┆ B      ┆ 1      │
│ 2021-05-01 00:00:00 ┆ B      ┆ 1      │
│ 2021-06-01 00:00:00 ┆ B      ┆ 3      │
└─────────────────────┴────────┴────────┘

var(
    ddof: int = 1,
) → DataFrame

Вычислить дисперсию столбцов этого DataFrame.

Параметры:

ddof

«Число степеней свободы»: делитель при вычислении равен N - ddof, где N — количество элементов. По умолчанию ddof равен 1.

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...         "ham": ["a", "b", "c"],
...     }
... )
>>> df.var()
shape: (1, 3)
┌─────┬─────┬──────┐
│ foo ┆ bar ┆ ham  │
│ --- ┆ --- ┆ ---  │
│ f64 ┆ f64 ┆ str  │
╞═════╪═════╪══════╡
│ 1.0 ┆ 1.0 ┆ null │
└─────┴─────┴──────┘
>>> df.var(ddof=0)
shape: (1, 3)
┌──────────┬──────────┬──────┐
│ foo      ┆ bar      ┆ ham  │
│ ---      ┆ ---      ┆ ---  │
│ f64      ┆ f64      ┆ str  │
╞══════════╪══════════╪══════╡
│ 0.666667 ┆ 0.666667 ┆ null │
└──────────┴──────────┴──────┘

vstack(
    other: DataFrame,
    *,
    in_place: bool = False,
) → DataFrame

Увеличить этот DataFrame по вертикали, добавив к нему другой DataFrame.

Параметры:

other

DataFrame для добавления.

in_place

Изменить на месте.

См. также

extend

Примеры

>>> df1 = pl.DataFrame(
...     {
...         "foo": [1, 2],
...         "bar": [6, 7],
...         "ham": ["a", "b"],
...     }
... )
>>> df2 = pl.DataFrame(
...     {
...         "foo": [3, 4],
...         "bar": [8, 9],
...         "ham": ["c", "d"],
...     }
... )
>>> df1.vstack(df2)
shape: (4, 3)
┌─────┬─────┬─────┐
│ foo ┆ bar ┆ ham │
│ --- ┆ --- ┆ --- │
│ i64 ┆ i64 ┆ str │
╞═════╪═════╪═════╡
│ 1   ┆ 6   ┆ a   │
│ 2   ┆ 7   ┆ b   │
│ 3   ┆ 8   ┆ c   │
│ 4   ┆ 9   ┆ d   │
└─────┴─────┴─────┘

property width: int

Получить количество столбцов.

Возвращает:

int

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [4, 5, 6],
...     }
... )
>>> df.width
2

with_columns(
    *exprs: IntoExpr | Iterable[IntoExpr],
    **named_exprs: IntoExpr,
) → DataFrame

Добавить столбцы в этот DataFrame.

Добавленные столбцы заменят существующие столбцы с такими же именами.

Параметры:

*exprs

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

**named_exprs

Дополнительные столбцы для добавления, заданные именованными аргументами. Столбцам будут присвоены имена соответствующих аргументов.

Возвращает:

DataFrame

Новый DataFrame с добавленными столбцами.

Примечания

Создание нового DataFrame с помощью этого метода не копирует существующие данные.

Примеры

Передайте выражение, чтобы добавить его в качестве нового столбца.

>>> df = pl.DataFrame(
...     {
...         "a": [1, 2, 3, 4],
...         "b": [0.5, 4, 10, 13],
...         "c": [True, True, False, True],
...     }
... )
>>> df.with_columns((pl.col("a") ** 2).alias("a^2"))
shape: (4, 4)
┌─────┬──────┬───────┬─────┐
│ a   ┆ b    ┆ c     ┆ a^2 │
│ --- ┆ ---  ┆ ---   ┆ --- │
│ i64 ┆ f64  ┆ bool  ┆ i64 │
╞═════╪══════╪═══════╪═════╡
│ 1   ┆ 0.5  ┆ true  ┆ 1   │
│ 2   ┆ 4.0  ┆ true  ┆ 4   │
│ 3   ┆ 10.0 ┆ false ┆ 9   │
│ 4   ┆ 13.0 ┆ true  ┆ 16  │
└─────┴──────┴───────┴─────┘

Добавленные столбцы заменят существующие столбцы с такими же именами.

>>> df.with_columns(pl.col("a").cast(pl.Float64))
shape: (4, 3)
┌─────┬──────┬───────┐
│ a   ┆ b    ┆ c     │
│ --- ┆ ---  ┆ ---   │
│ f64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╡
│ 1.0 ┆ 0.5  ┆ true  │
│ 2.0 ┆ 4.0  ┆ true  │
│ 3.0 ┆ 10.0 ┆ false │
│ 4.0 ┆ 13.0 ┆ true  │
└─────┴──────┴───────┘

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

>>> df.with_columns(
...     (pl.col("a") ** 2).alias("a^2"),
...     (pl.col("b") / 2).alias("b/2"),
...     (pl.col("c").not_()).alias("not c"),
... )
shape: (4, 6)
┌─────┬──────┬───────┬─────┬──────┬───────┐
│ a   ┆ b    ┆ c     ┆ a^2 ┆ b/2  ┆ not c │
│ --- ┆ ---  ┆ ---   ┆ --- ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  ┆ i64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╪═════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  ┆ 1   ┆ 0.25 ┆ false │
│ 2   ┆ 4.0  ┆ true  ┆ 4   ┆ 2.0  ┆ false │
│ 3   ┆ 10.0 ┆ false ┆ 9   ┆ 5.0  ┆ true  │
│ 4   ┆ 13.0 ┆ true  ┆ 16  ┆ 6.5  ┆ false │
└─────┴──────┴───────┴─────┴──────┴───────┘

Несколько столбцов также можно добавить, передав список выражений.

>>> df.with_columns(
...     [
...         (pl.col("a") ** 2).alias("a^2"),
...         (pl.col("b") / 2).alias("b/2"),
...         (pl.col("c").not_()).alias("not c"),
...     ]
... )
shape: (4, 6)
┌─────┬──────┬───────┬─────┬──────┬───────┐
│ a   ┆ b    ┆ c     ┆ a^2 ┆ b/2  ┆ not c │
│ --- ┆ ---  ┆ ---   ┆ --- ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  ┆ i64 ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╪═════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  ┆ 1   ┆ 0.25 ┆ false │
│ 2   ┆ 4.0  ┆ true  ┆ 4   ┆ 2.0  ┆ false │
│ 3   ┆ 10.0 ┆ false ┆ 9   ┆ 5.0  ┆ true  │
│ 4   ┆ 13.0 ┆ true  ┆ 16  ┆ 6.5  ┆ false │
└─────┴──────┴───────┴─────┴──────┴───────┘

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

>>> df.with_columns(
...     ab=pl.col("a") * pl.col("b"),
...     not_c=pl.col("c").not_(),
... )
shape: (4, 5)
┌─────┬──────┬───────┬──────┬───────┐
│ a   ┆ b    ┆ c     ┆ ab   ┆ not_c │
│ --- ┆ ---  ┆ ---   ┆ ---  ┆ ---   │
│ i64 ┆ f64  ┆ bool  ┆ f64  ┆ bool  │
╞═════╪══════╪═══════╪══════╪═══════╡
│ 1   ┆ 0.5  ┆ true  ┆ 0.5  ┆ false │
│ 2   ┆ 4.0  ┆ true  ┆ 8.0  ┆ false │
│ 3   ┆ 10.0 ┆ false ┆ 30.0 ┆ true  │
│ 4   ┆ 13.0 ┆ true  ┆ 52.0 ┆ false │
└─────┴──────┴───────┴──────┴───────┘

with_columns_seq(
    *exprs: IntoExpr | Iterable[IntoExpr],
    **named_exprs: IntoExpr,
) → DataFrame

Добавить столбцы в этот DataFrame.

Добавленные столбцы заменят существующие столбцы с такими же именами.

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

Параметры:

*exprs

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

**named_exprs

Дополнительные столбцы для добавления, заданные именованными аргументами. Столбцам будут присвоены имена соответствующих аргументов.

Возвращает:

DataFrame

Новый DataFrame с добавленными столбцами.

См. также

with_columns

with_row_count(
    name: str = 'row_nr',
    offset: int = 0,
) → DataFrame

Добавить в индекс 0 столбец со счётчиком строк.

Устарело с версии 0.20.4: Вместо этого используйте метод with_row_index(). Обратите внимание: имя столбца по умолчанию изменилось с «row_nr» на «index».

Параметры:

name

Имя добавляемого столбца.

offset

Смещение, с которого начинается подсчёт строк. По умолчанию — 0.

Примеры

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

with_row_index(
    name: str = 'index',
    offset: int = 0,
) → DataFrame

Добавить индекс строк в качестве первого столбца DataFrame.

Параметры:

name

Имя столбца индекса.

offset

Смещение, с которого начинается индекс. Не может быть отрицательным.

Примечания

У результирующего столбца нет особых свойств. Это обычный столбец типа UInt32 (или UInt64 в polars[rt64]).

Примеры

>>> df = pl.DataFrame(
...     {
...         "a": [1, 3, 5],
...         "b": [2, 4, 6],
...     }
... )
>>> df.with_row_index()
shape: (3, 3)
┌───────┬─────┬─────┐
│ index ┆ a   ┆ b   │
│ ---   ┆ --- ┆ --- │
│ u32   ┆ i64 ┆ i64 │
╞═══════╪═════╪═════╡
│ 0     ┆ 1   ┆ 2   │
│ 1     ┆ 3   ┆ 4   │
│ 2     ┆ 5   ┆ 6   │
└───────┴─────┴─────┘
>>> df.with_row_index("id", offset=1000)
shape: (3, 3)
┌──────┬─────┬─────┐
│ id   ┆ a   ┆ b   │
│ ---  ┆ --- ┆ --- │
│ u32  ┆ i64 ┆ i64 │
╞══════╪═════╪═════╡
│ 1000 ┆ 1   ┆ 2   │
│ 1001 ┆ 3   ┆ 4   │
│ 1002 ┆ 5   ┆ 6   │
└──────┴─────┴─────┘

Столбец индекса также можно создать с помощью выражений int_range() и len().

>>> df.select(
...     pl.int_range(pl.len(), dtype=pl.UInt32).alias("index"),
...     pl.all(),
... )
shape: (3, 3)
┌───────┬─────┬─────┐
│ index ┆ a   ┆ b   │
│ ---   ┆ --- ┆ --- │
│ u32   ┆ i64 ┆ i64 │
╞═══════╪═════╪═════╡
│ 0     ┆ 1   ┆ 2   │
│ 1     ┆ 3   ┆ 4   │
│ 2     ┆ 5   ┆ 6   │
└───────┴─────┴─────┘

write_avro(
    file: str | Path | IO[bytes],
    compression: AvroCompression = 'uncompressed',
    name: str = '',
) → None

Записать в файл Apache Avro.

Параметры:

file

Путь к файлу или файловый объект с возможностью записи, в который будут записаны данные.

compression{‘uncompressed’, ‘snappy’, ‘deflate’}

Метод сжатия. По умолчанию — «uncompressed».

name

Имя схемы. По умолчанию — пустая строка.

Примеры

>>> import pathlib
>>>
>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> path: pathlib.Path = dirpath / "new_file.avro"
>>> df.write_avro(path)

write_clipboard(
    *,
    separator: str = '\t',
    **kwargs: Any,
) → None

Скопировать DataFrame в формате CSV в системный буфер обмена с помощью write_csv.

Удобно для вставки в Excel или другие аналогичные программы для работы с электронными таблицами.

Параметры:

separator

Разделять поля CSV этим символом.

kwargs

Дополнительные аргументы для передачи в write_csv.

См. также

polars.read_clipboard

Прочитать DataFrame из буфера обмена.

write_csv

Записать файл в формате CSV (значения, разделённые запятыми).

write_csv(
    file: str | Path | IO[str] | IO[bytes] | None = None,
    *,
    include_bom: bool = False,
    compression: Literal['uncompressed',
    'gzip',
    'zstd'] = 'uncompressed',
    compression_level: int | None = None,
    check_extension: bool = True,
    include_header: bool = True,
    separator: str = ',',
    line_terminator: str = '\n',
    quote_char: str = '"',
    batch_size: int = 1024,
    datetime_format: str | None = None,
    date_format: str | None = None,
    time_format: str | None = None,
    float_scientific: bool | None = None,
    float_precision: int | None = None,
    decimal_comma: bool = False,
    null_value: str | None = None,
    quote_style: CsvQuoteStyle | None = None,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
) → str | None

Записать файл в формате CSV (значения, разделённые запятыми).

Параметры:

file

Путь к файлу или объект файлового типа с поддержкой записи, в который будет записан результат. Если задано None (значение по умолчанию), вместо этого результат возвращается в виде строки.

include_bom

Следует ли включать BOM UTF-8 в вывод CSV.

compression

Формат сжатия.

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

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

compression_level

Уровень сжатия: обычно от 0 до 9 или None, чтобы позволить движку выбрать значение.

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

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

check_extension

Проверять ли соответствие имени файла настройкам сжатия. Будет вызвана ошибка, если для сжатия задано значение ‘uncompressed’, а имя файла заканчивается на одно из значений (“.gz”, “.zst”, “.zstd”), либо если compression != ‘uncompressed’, а имя файла не заканчивается соответствующим расширением. Применяется только в том случае, если file — это путь.

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

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

include_header

Следует ли включать заголовок в вывод CSV.

separator

Разделять поля CSV этим символом.

line_terminator

Строка, используемая для завершения каждой строки.

quote_char

Байт, используемый в качестве символа кавычек.

batch_size

Количество строк, обрабатываемых одним потоком.

datetime_format

Строка формата со спецификаторами, определёнными в библиотеке Rust chrono. Если формат не задан, точность дробной части по умолчанию определяется по максимальной единице времени, найденной в столбцах Datetime кадра (если таковые имеются).

date_format

Строка формата со спецификаторами, определёнными в библиотеке Rust chrono.

time_format

Строка формата со спецификаторами, определёнными в библиотеке Rust chrono.

float_scientific

Следует ли всегда (true), никогда (false) или автоматически (None) использовать научную запись для типов данных с плавающей точкой.

float_precision

Количество десятичных знаков для записи; применяется к обоим типам данных с плавающей точкой.

decimal_comma

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

null_value

Строка, представляющая нулевые значения (по умолчанию — пустая строка).

quote_style{‘necessary’, ‘always’, ‘non_numeric’, ‘never’}

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

• necessary (по умолчанию): заключает поля в кавычки только при необходимости. Это необходимо, если поля содержат кавычку, разделитель или символ окончания записи. Кавычки также необходимы при записи пустой записи (которую невозможно отличить от записи с одним пустым полем). Это значение используется по умолчанию.
• always: заключает в кавычки каждое поле. Всегда.
• never: никогда не заключает поля в кавычки, даже если это приводит к некорректным данным CSV (например, если не заключать в кавычки строки, содержащие разделитель).
• non_numeric: заключает в кавычки все поля, не являющиеся числовыми. То есть при записи поля, которое не разбирается как допустимое число с плавающей точкой или целое число, кавычки используются, даже если они не являются строго необходимыми.

storage_options

Параметры, определяющие способ подключения к облачному провайдеру.

В настоящее время поддерживаются облачные провайдеры AWS, GCP и Azure. Список поддерживаемых ключей приведён здесь:

• aws
• gcp
• azure
• Hugging Face (hf://): принимает ключ API в параметре token: {'token': '...'} или через переменную окружения HF_TOKEN.

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

credential_provider

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

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

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

retries

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

Устарело с версии 1.37.1: Вместо этого передайте {“max_retries”: n} через storage_options.

Примеры

>>> import pathlib
>>>
>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> path: pathlib.Path = dirpath / "new_file.csv"
>>> df.write_csv(path, separator=",")

write_database(
    table_name: str,
    connection: ConnectionOrCursor | str,
    *,
    if_table_exists: DbWriteMode = 'fail',
    engine: DbWriteEngine | None = None,
    engine_options: dict[str,
    Any] | None = None,
) → int

Записать данные Polars DataFrame в базу данных.

Добавлено в версии 0.20.26: Поддержка готовых объектов соединения в дополнение к строкам URI, а также новый параметр engine_options.

Параметры:

table_name

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

connection

Существующее соединение SQLAlchemy или ADBC с целевой базой данных либо строка URI, используемая для создания такого соединения, например:

• “postgresql://user:pass@server:port/database”
• “sqlite:////path/to/database.db”

if_table_exists{‘append’, ‘replace’, ‘fail’}

Режим вставки:

• ‘replace’ создаст новую таблицу базы данных, перезаписав существующую.
• ‘append’ добавит данные в существующую таблицу.
• ‘fail’ вызовет ошибку, если таблица уже существует.

engine{‘sqlalchemy’, ‘adbc’}

Выбрать движок для записи данных кадра; требуется только при передаче строки URI (по умолчанию используется ‘sqlalchemy’, если значение не задано).

engine_options

Дополнительные параметры, передаваемые методу вставки, связанному с движком, указанным параметром engine.

• Если для engine задано значение “sqlalchemy”, вставка в настоящее время выполняется методом to_sql из Pandas (в дальнейшем от него планируется отказаться в пользу нативного решения).
• Если для engine задано значение “adbc”, вставка выполняется методом adbc_ingest курсора ADBC. Обратите внимание: при передаче готового объекта соединения для драйверов SQLite и Snowflake требуется PyArrow.

Возвращает:

int

Количество затронутых строк, если драйвер предоставляет эту информацию. В противном случае возвращается -1.

Примеры

Вставка данных во временную таблицу с использованием URI PostgreSQL и движка ADBC:

>>> df.write_database(
...     table_name="target_table",
...     connection="postgresql://user:pass@server:port/database",
...     engine="adbc",
...     engine_options={"temporary": True},
... )  

Вставка данных в таблицу с использованием соединения pyodbc SQLAlchemy с SQL Server, созданного с параметром “fast_executemany=True” для повышения производительности:

>>> pyodbc_uri = (
...     "mssql+pyodbc://user:pass@server:1433/test?"
...     "driver=ODBC+Driver+18+for+SQL+Server"
... )
>>> engine = create_engine(pyodbc_uri, fast_executemany=True)  
>>> df.write_database(
...     table_name="target_table",
...     connection=engine,
... )  

write_delta(
    target: str | Path | deltalake.DeltaTable,
    *,
    mode: Literal['error',
    'append',
    'overwrite',
    'ignore',
    'merge'] = 'error',
    overwrite_schema: bool | None = None,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    delta_write_options: dict[str,
    Any] | None = None,
    delta_merge_options: dict[str,
    Any] | None = None,
) → deltalake.table.TableMerger | None

Записать DataFrame в виде таблицы Delta.

Параметры:

target

URI таблицы или объект DeltaTable.

mode{‘error’, ‘append’, ‘overwrite’, ‘ignore’, ‘merge’}

Способ обработки существующих данных.

• Если задано ‘error’, при существовании таблицы будет вызвана ошибка (значение по умолчанию).
• Если задано ‘append’, будут добавлены новые данные.
• Если задано ‘overwrite’, таблица будет заменена новыми данными.
• Если задано ‘ignore’, при существовании таблицы запись не будет выполняться.
• Если задано ‘merge’, возвращается объект TableMerger для объединения данных DataFrame с существующими данными.

overwrite_schema

Если True, разрешает обновление схемы таблицы.

Устарело с версии 0.20.14: Вместо этого используйте параметр delta_write_options и передайте {"schema_mode": "overwrite"}.

storage_options

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

• Список поддерживаемых параметров хранилища для S3 см. здесь.
• Список поддерживаемых параметров хранилища для GCS см. здесь.
• Список поддерживаемых параметров хранилища для Azure см. здесь.

credential_provider

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

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

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

delta_write_options

Дополнительные именованные аргументы при записи таблицы Delta Lake. Список поддерживаемых параметров записи см. здесь.

delta_merge_options

Именованные аргументы, необходимые для MERGE таблицы Delta Lake. Список поддерживаемых параметров объединения см. здесь.

Вызывает исключения:

TypeError

Если DataFrame содержит неподдерживаемые типы данных.

ArrowInvalidError

Если DataFrame содержит типы данных, которые не удалось привести к примитивному типу.

TableNotFoundError

Если таблица Delta не существует и запускается действие MERGE.

Примечания

Типы данных Polars Null и Time не поддерживаются спецификацией протокола Delta и приведут к TypeError. Столбцы с типом данных Categorical при записи будут преобразованы в обычные строки (не категориальные).

Столбцы Polars всегда допускают нулевые значения. Чтобы записать данные в таблицу Delta со столбцами, не допускающими нулевые значения, необходимо передать пользовательскую схему pyarrow в delta_write_options. См. последний пример ниже.

Примеры

Запись DataFrame в файловую систему локального компьютера в виде таблицы Delta Lake.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> table_path = "/path/to/delta-table/"
>>> df.write_delta(table_path)  

Добавление данных в существующую таблицу Delta Lake в локальной файловой системе. Обратите внимание: операция завершится ошибкой, если схема новых данных не совпадает со схемой существующей таблицы.

>>> df.write_delta(table_path, mode="append")  

Перезапись таблицы Delta Lake с созданием новой версии. Если схемы новых и старых данных совпадают, указывать schema_mode не требуется.

>>> existing_table_path = "/path/to/delta-table/"
>>> df.write_delta(
...     existing_table_path,
...     mode="overwrite",
...     delta_write_options={"schema_mode": "overwrite"},
... )  

Запись DataFrame в виде таблицы Delta Lake в облачное объектное хранилище, например S3.

>>> table_path = "s3://bucket/prefix/to/delta-table/"
>>> df.write_delta(
...     table_path,
...     storage_options={
...         "AWS_REGION": "THE_AWS_REGION",
...         "AWS_ACCESS_KEY_ID": "THE_AWS_ACCESS_KEY_ID",
...         "AWS_SECRET_ACCESS_KEY": "THE_AWS_SECRET_ACCESS_KEY",
...     },
... )  

Запись DataFrame в виде таблицы Delta Lake со столбцами, не допускающими нулевые значения.

>>> import pyarrow as pa
>>> existing_table_path = "/path/to/delta-table/"
>>> df.write_delta(
...     existing_table_path,
...     delta_write_options={
...         "schema": pa.schema([pa.field("foo", pa.int64(), nullable=False)])
...     },
... )  

Запись DataFrame в виде таблицы Delta Lake со сжатием zstd. Список всех именованных аргументов delta_write_options см. в документации deltalake здесь, а параметры Writer Properties — в частности здесь.

>>> import deltalake
>>> df.write_delta(
...     table_path,
...     delta_write_options={
...         "writer_properties": deltalake.WriterProperties(compression="zstd"),
...     },
... )  

Объединение DataFrame с существующей таблицей Delta Lake. Список всех методов TableMerger см. в документации deltalake здесь.

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> table_path = "/path/to/delta-table/"
>>> (
...     df.write_delta(
...         "table_path",
...         mode="merge",
...         delta_merge_options={
...             "predicate": "s.foo = t.foo",
...             "source_alias": "s",
...             "target_alias": "t",
...         },
...     )
...     .when_matched_update_all()
...     .when_not_matched_insert_all()
...     .execute()
... )  

write_excel(
    workbook: str | Workbook | IO[bytes] | Path | None = None,
    worksheet: str | Worksheet | None = None,
    *,
    position: tuple[int,
    int] | str = 'A1',
    table_style: str | dict[str,
    Any] | None = None,
    table_name: str | None = None,
    column_formats: ColumnFormatDict | None = None,
    dtype_formats: dict[OneOrMoreDataTypes,
    str] | None = None,
    conditional_formats: ConditionalFormatDict | None = None,
    header_format: dict[str,
    Any] | None = None,
    column_totals: ColumnTotalsDefinition | None = None,
    column_widths: ColumnWidthsDefinition | None = None,
    row_totals: RowTotalsDefinition | None = None,
    row_heights: dict[int | tuple[int,
    ...],
    int] | int | None = None,
    sparklines: dict[str,
    Sequence[str] | dict[str,
    Any]] | None = None,
    formulas: dict[str,
    str | dict[str,
    str]] | None = None,
    float_precision: int = 3,
    include_header: bool = True,
    autofilter: bool = True,
    autofit: bool = False,
    hidden_columns: Sequence[str] | SelectorType | None = None,
    hide_gridlines: bool = False,
    sheet_zoom: int | None = None,
    freeze_panes: str | tuple[int,
    int] | tuple[str,
    int,
    int] | tuple[int,
    int,
    int,
    int] | None = None,
    use_zip64: bool = False,
) → Workbook

Записать данные кадра в таблицу листа книги Excel.

Параметры:

workbook{str, Workbook}

Имя или путь к создаваемой книге в виде строки, объект BytesIO, файл, открытый в двоичном режиме, или незакрытый объект xlsxwriter.Workbook. Если задано None, данные записываются в dataframe.xlsx в рабочем каталоге.

worksheet{str, Worksheet}

Имя целевого листа или объект xlsxwriter.Worksheet (в этом случае workbook должен быть родительским объектом xlsxwriter.Workbook); если задано None, при создании новой книги данные записываются на “Sheet1” (обратите внимание: для записи в существующую книгу необходимо указать допустимое имя существующего или нового листа).

position{str, tuple}

Позиция таблицы в нотации Excel (например, “A1”) или кортеж целых чисел (строка, столбец).

table_style{str, dict}

Именованный стиль таблицы Excel, например “Table Style Medium 4”, или словарь параметров {"key":value,}, содержащий один или несколько следующих ключей: “style”, “first_column”, “last_column”, “banded_columns, “banded_rows”.

table_namestr

Имя выходного объекта таблицы на листе; на него можно ссылаться в формулах и диаграммах листа, а также в последующих операциях xlsxwriter.

column_formatsdict

Словарь {colname(s):str,} или {selector:str,} для применения строки формата Excel к указанным столбцам. Заданные здесь форматы (например, “dd/mm/yyyy”, “0.00%” и т. д.) переопределяют форматы, указанные в dtype_formats.

dtype_formatsdict

Словарь {dtype:str,}, задающий формат Excel по умолчанию для указанного dtype. (Его можно переопределить отдельно для каждого столбца с помощью параметра column_formats.)

conditional_formatsdict

Словарь, сопоставляющий имена столбцов (или селекторы) со строкой формата, словарём или списком, задающим параметры условного форматирования для указанных столбцов.

• Если в качестве строки указано имя типа, оно должно быть одним из допустимых типов xlsxwriter, например “3_color_scale”, “data_bar” и т. д.
• Если передан словарь, можно использовать любые поддерживаемые параметры xlsxwriter, включая наборы значков, формулы и т. д.
• Если передать несколько столбцов в виде кортежа или ключа, единый формат будет применён ко всем столбцам. Это удобно для создания тепловой карты, поскольку минимальные и максимальные значения будут определяться для всего диапазона, а не отдельно для каждого столбца.
• Наконец, можно передать список из указанных выше параметров, чтобы применить к одному диапазону несколько правил условного форматирования.

header_formatdict

Словарь {key:value,} с параметрами форматирования xlsxwriter для строки заголовка таблицы, например {"bold":True, "font_color":"#702963"}.

column_totals{bool, list, dict}

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

• Если задано True, для всех числовых столбцов будут вычислены итоги с помощью функции “sum”.
• Если передана строка, она должна быть именем допустимой функции вычисления итогов; эта функция будет применена ко всем числовым столбцам.
• Если передан список имён столбцов, итоги будут вычислены только для указанных столбцов.
• Для большего контроля передайте словарь {colname:funcname,}.

Допустимые имена функций вычисления итогов по столбцам: “average”, “count_nums”, “count”, “max”, “min”, “std_dev”, “sum” и “var”.

column_widths{dict, int}

Словарь {colname:int,} или {selector:int,} либо целое число, задающее (или переопределяющее при автоматическом подборе) ширину столбцов таблицы в целых пикселях. Если задано целое число, это значение используется для всех столбцов таблицы.

row_totals{dict, list, bool}

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

• Если задано True, в конце таблицы будет добавлен столбец с именем “total”, в котором для каждой строки будет вычислена сумма по всем числовым столбцам.
• Если передан список или последовательность имён столбцов, в суммировании будут участвовать только соответствующие столбцы.
• Также можно передать словарь {colname:columns,}, чтобы создать один или несколько столбцов итогов с разными именами, ссылающихся на разные столбцы.

row_heights{dict, int}

Целое число или словарь {row_index:int,}, задающий высоту указанных строк (если передан словарь) или всех строк (если передано целое число), пересекающихся с телом таблицы (включая строку заголовка и строку итогов), в целых пикселях. Обратите внимание: отсчёт row_index начинается с нуля, и это будет строка заголовка (если только include_header не равно False).

sparklinesdict

Словарь {colname:list,} или {colname:dict,}, задающий одну или несколько спарклайн-диаграмм для записи в новый столбец таблицы.

• Если передан список имён столбцов (используемых в качестве источника данных спарклайна), применяются настройки спарклайна по умолчанию (например, линейная диаграмма без маркеров).
• Для большего контроля можно передать словарь параметров, совместимый с xlsxwriter; в этом случае доступны три дополнительных ключа, специфичных для polars: “columns”, “insert_before” и “insert_after”. Они позволяют задать исходные столбцы и положение спарклайна относительно других столбцов таблицы. Если позиция не указана, спарклайны добавляются в конец таблицы (например, в крайний правый столбец) в заданном порядке.

formulasdict

Словарь {colname:formula,} или {colname:dict,}, задающий одну или несколько формул для записи в новый столбец таблицы. Настоятельно рекомендуется по возможности использовать в формулах структурированные ссылки — так проще ссылаться на столбцы по имени.

• Если передана формула в виде строки (например, “=[@colx]*[@coly]”), столбец будет добавлен в конец таблицы (например, в крайний правый столбец), после всех спарклайнов по умолчанию и перед столбцами итогов по строкам.
• Для максимального контроля передайте словарь параметров со следующими ключами: “formula” (обязательный), один из “insert_before” или “insert_after” и необязательный “return_dtype”. Последний используется для надлежащего форматирования результата формулы и позволяет включать его в итоги по строкам и столбцам.

float_precisionint

Количество знаков после запятой по умолчанию для столбцов с числами с плавающей точкой (это только указание для форматирования; фактические значения не округляются).

include_headerbool

Указывает, следует ли создавать таблицу со строкой заголовка.

autofilterbool

Если у таблицы есть заголовки, включить возможность автофильтрации.

autofitbool

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

hidden_columnsstr | list

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

hide_gridlinesbool

Не отображать линии сетки на выходном листе.

sheet_zoomint

Задать масштаб по умолчанию для выходного листа.

freeze_panesstr | (str, int, int) | (int, int) | (int, int, int, int)

Закрепить области книги.

• Если передано значение (row, col), разделение областей выполняется в левом верхнем углу указанной ячейки; индексация начинается с нуля. Таким образом, чтобы закрепить только верхнюю строку, передайте (1, 0).
• Также для указания ячейки можно использовать её обозначение. Например, “A2” означает, что разделение выполняется в левом верхнем углу ячейки A2, что эквивалентно (1, 0).
• Если передано значение (row, col, top_row, top_col), области разделяются на основе row и col, а прокручиваемая область начинается с top_row и top_col. Таким образом, чтобы закрепить только верхнюю строку и начать прокручиваемую область со строки 10, столбца D (5-го столбца), передайте (1, 0, 9, 4). Использование обозначения ячейки для (row, col), например (“A2”, 9, 4), эквивалентно.

use_zip64bool

Использовать ли расширения ZIP64 при записи книги. Это позволяет записывать очень большие файлы книг (не сжатые, размером не менее 4 ГБ), но снижает совместимость.

Примечания

• Список совместимых имён свойств формата xlsxwriter приведён здесь.
• Словари условного форматирования должны содержать определения, совместимые с xlsxwriter; polars самостоятельно применит их на листе с учётом положения листа и столбца. Список поддерживаемых параметров см. здесь: https://xlsxwriter.readthedocs.io/working_with_conditional_formats.html
• Аналогично, словари параметров спарклайнов должны содержать ключи и значения, совместимые с xlsxwriter, а также обязательный ключ polars “columns”, задающий источник данных спарклайна; исходные столбцы должны располагаться рядом. Для указания положения спарклайна в таблице доступны ещё два ключа, специфичных для polars: “insert_after” и “insert_before”. Значением этих ключей должно быть имя столбца экспортируемой таблицы. https://xlsxwriter.readthedocs.io/working_with_sparklines.html
• Словари формул должны содержать ключ “formula” и могут дополнительно содержать ключи “insert_after”, “insert_before” и/или “return_dtype”. Эти дополнительные ключи позволяют вставить столбец в определённое место таблицы и/или задать тип возвращаемого значения формулы (например, “Int64”, “Float64” и т. д.). В формулах, ссылающихся на столбцы таблицы, следует использовать синтаксис структурированных ссылок Excel, чтобы формула применялась корректно и относилась к таблице. https://support.microsoft.com/en-us/office/using-structured-references-with-excel-tables-f5ed2452-2337-4f71-bed3-c8ae6d2b276e
• Чтобы получить вывод без форматирования, можно использовать селектор для применения формата “General” ко всем столбцам (или ко всем нетемпоральным столбцам, чтобы сохранить форматирование столбцов с датами и датой-временем), например: column_formats={~cs.temporal(): "General"}.

Примеры

Создание простого DataFrame:

>>> from random import uniform
>>> from datetime import date
>>>
>>> df = pl.DataFrame(
...     {
...         "dtm": [date(2023, 1, 1), date(2023, 1, 2), date(2023, 1, 3)],
...         "num": [uniform(-500, 500), uniform(-500, 500), uniform(-500, 500)],
...         "val": [10_000, 20_000, 30_000],
...     }
... )

Экспорт в “dataframe.xlsx” (имя книги по умолчанию, если не задано другое) в рабочем каталоге, добавление итогов по столбцам для всех числовых столбцов (по умолчанию “sum”), затем автоматический подбор ширины столбцов:

>>> df.write_excel(column_totals=True, autofit=True)  

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

>>> df.write_excel(  
...     position="B4",
...     table_style="Table Style Light 16",
...     dtype_formats={pl.Date: "mm/dd/yyyy"},
...     column_totals={"num": "average"},
...     float_precision=6,
...     autofit=True,
... )

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

>>> from xlsxwriter import Workbook
>>> with Workbook("multi_frame.xlsx") as wb:  
...     # basic/default conditional formatting
...     df.write_excel(
...         workbook=wb,
...         worksheet="data",
...         position=(3, 1),  # specify position as (row,col) coordinates
...         conditional_formats={"num": "3_color_scale", "val": "data_bar"},
...         table_style="Table Style Medium 4",
...     )
...
...     # advanced conditional formatting, custom styles
...     df.write_excel(
...         workbook=wb,
...         worksheet="data",
...         position=(df.height + 7, 1),
...         table_style={
...             "style": "Table Style Light 4",
...             "first_column": True,
...         },
...         conditional_formats={
...             "num": {
...                 "type": "3_color_scale",
...                 "min_color": "#76933c",
...                 "mid_color": "#c4d79b",
...                 "max_color": "#ebf1de",
...             },
...             "val": {
...                 "type": "data_bar",
...                 "data_bar_2010": True,
...                 "bar_color": "#9bbb59",
...                 "bar_negative_color_same": True,
...                 "bar_negative_border_color_same": True,
...             },
...         },
...         column_formats={"num": "#,##0.000;[White]-#,##0.000"},
...         column_widths={"val": 125},
...         autofit=True,
...     )
...
...     # add some table titles (with a custom format)
...     ws = wb.get_worksheet_by_name("data")
...     fmt_title = wb.add_format(
...         {
...             "font_color": "#4f6228",
...             "font_size": 12,
...             "italic": True,
...             "bold": True,
...         }
...     )
...     ws.write(2, 1, "Basic/default conditional formatting", fmt_title)
...     ws.write(df.height + 6, 1, "Custom conditional formatting", fmt_title)

Экспорт таблицы с двумя разными типами спарклайнов. Для спарклайна “trend” используются параметры по умолчанию, а для спарклайна “+/-” win_loss — настроенные параметры и положение; также применяются нестандартный целочисленный формат, итоги по столбцам и ненавязчивая двухцветная тепловая карта, а линии сетки листа скрываются:

>>> df = pl.DataFrame(
...     {
...         "id": ["aaa", "bbb", "ccc", "ddd", "eee"],
...         "q1": [100, 55, -20, 0, 35],
...         "q2": [30, -10, 15, 60, 20],
...         "q3": [-50, 0, 40, 80, 80],
...         "q4": [75, 55, 25, -10, -55],
...     }
... )
>>> df.write_excel(  
...     table_style="Table Style Light 2",
...     # apply accounting format to all flavours of integer
...     dtype_formats={dt: "#,##0_);(#,##0)" for dt in [pl.Int32, pl.Int64]},
...     sparklines={
...         # default options; just provide source cols
...         "trend": ["q1", "q2", "q3", "q4"],
...         # customized sparkline type, with positioning directive
...         "+/-": {
...             "columns": ["q1", "q2", "q3", "q4"],
...             "insert_after": "id",
...             "type": "win_loss",
...         },
...     },
...     conditional_formats={
...         # create a unified multi-column heatmap
...         ("q1", "q2", "q3", "q4"): {
...             "type": "2_color_scale",
...             "min_color": "#95b3d7",
...             "max_color": "#ffffff",
...         },
...     },
...     column_totals=["q1", "q2", "q3", "q4"],
...     row_totals=True,
...     hide_gridlines=True,
... )

Экспорт таблицы со столбцом на основе формулы Excel для вычисления стандартизованной Z-оценки; демонстрируется использование структурированных ссылок вместе с указанием положения, итогами по столбцам и пользовательским форматированием.

>>> df = pl.DataFrame(
...     {
...         "id": ["a123", "b345", "c567", "d789", "e101"],
...         "points": [99, 45, 50, 85, 35],
...     }
... )
>>> df.write_excel(  
...     table_style={
...         "style": "Table Style Medium 15",
...         "first_column": True,
...     },
...     column_formats={
...         "id": {"font": "Consolas"},
...         "points": {"align": "center"},
...         "z-score": {"align": "center"},
...     },
...     column_totals="average",
...     formulas={
...         "z-score": {
...             # use structured references to refer to the table columns and 'totals' row
...             "formula": "=STANDARDIZE([@points], [[#Totals],[points]], STDEV([points]))",
...             "insert_after": "points",
...             "return_dtype": pl.Float64,
...         }
...     },
...     hide_gridlines=True,
...     sheet_zoom=125,
... )

Создание объекта Worksheet и прямое обращение к нему, добавление простой диаграммы. Настоятельно рекомендуется использовать структурированные ссылки для задания значений и категорий рядов диаграммы, чтобы не вычислять позиции ячеек относительно данных кадра и листа:

>>> with Workbook("basic_chart.xlsx") as wb:  
...     # create worksheet object and write frame data to it
...     ws = wb.add_worksheet("demo")
...     df.write_excel(
...         workbook=wb,
...         worksheet=ws,
...         table_name="DataTable",
...         table_style="Table Style Medium 26",
...         hide_gridlines=True,
...     )
...     # create chart object, point to the written table
...     # data using structured references, and style it
...     chart = wb.add_chart({"type": "column"})
...     chart.set_title({"name": "Example Chart"})
...     chart.set_legend({"none": True})
...     chart.set_style(38)
...     chart.add_series(
...         {  # note the use of structured references
...             "values": "=DataTable[points]",
...             "categories": "=DataTable[id]",
...             "data_labels": {"value": True},
...         }
...     )
...     # add chart to the worksheet
...     ws.insert_chart("D1", chart)

Экспорт почти полностью неформатированных данных (без числового форматирования и стандартной точности для чисел с плавающей точкой), отключение автофильтра при сохранении форматирования дат и значений дата-время:

>>> import polars.selectors as cs
>>> df = pl.DataFrame(
...     {
...         "n1": [-100, None, 200, 555],
...         "n2": [987.4321, -200, 44.444, 555.5],
...     }
... )
>>> df.write_excel(  
...     column_formats={~cs.temporal(): "General"},
...     autofilter=False,
... )

write_iceberg(
    target: str | pyiceberg.table.Table,
    mode: Literal['append',
    'overwrite'],
) → None

Записать DataFrame в таблицу Iceberg.

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

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

Параметры:

target

Имя таблицы или объект Table, представляющий таблицу Iceberg.

mode{‘append’, ‘overwrite’}

Способ обработки существующих данных.

• Если задано ‘append’, будут добавлены новые данные.
• Если задано ‘overwrite’, таблица будет заменена новыми данными.

write_ipc(
    file: str | Path | IO[bytes] | None,
    *,
    compression: IpcCompression = 'uncompressed',
    compat_level: CompatLevel | None = None,
    record_batch_size: int | None = None,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
) → BytesIO | None

Записать в двоичный поток Arrow IPC или файл Feather.

См. «Формат файла или произвольного доступа» в https://arrow.apache.org/docs/python/ipc.html.

Изменено в версии 1.1: Параметр future был переименован в compat_level.

Параметры:

file

Путь или доступный для записи файловый объект, в который будут записаны данные IPC. Если задано значение None, результат возвращается в виде объекта BytesIO.

compression{‘uncompressed’, ‘lz4’, ‘zstd’}

Метод сжатия. По умолчанию — «uncompressed».

compat_level

Использовать определённый уровень совместимости при экспорте внутренних структур данных Polars.

record_batch_size

Размер пакетов записей в количестве строк.

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

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

storage_options

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

В настоящее время поддерживаются облачные провайдеры AWS, GCP и Azure. Поддерживаемые ключи приведены здесь:

• aws
• gcp
• azure
• Hugging Face (hf://): принимает ключ API в параметре token: {'token': '...'} или через переменную окружения HF_TOKEN.

Если storage_options не указан, Polars попытается получить эту информацию из переменных окружения.

credential_provider

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

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

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

retries

Количество повторных попыток при сбое доступа к облачному экземпляру.

Устарело с версии 1.37.1: Вместо этого передайте {“max_retries”: n} через storage_options.

Примеры

>>> import pathlib
>>>
>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> path: pathlib.Path = dirpath / "new_file.arrow"
>>> df.write_ipc(path)

Запишите данные в объект BytesIO, передав file=None. Позиция возвращённого буфера находится в конце записанных данных, поэтому перед чтением вызовите seek(0).

>>> buf = df.write_ipc(file=None)
>>> buf.seek(0)
0
>>> pl.read_ipc(buf).equals(df)
True

write_ipc_stream(
    file: str | Path | IO[bytes] | None,
    *,
    compression: IpcCompression = 'uncompressed',
    compat_level: CompatLevel | None = None,
) → BytesIO | None

Записать в поток пакетов записей Arrow IPC.

См. «Потоковый формат» в https://arrow.apache.org/docs/python/ipc.html.

Изменено в версии 1.1: Параметр future был переименован в compat_level.

Параметры:

file

Путь или доступный для записи файловый объект, в который будут записаны данные пакетов записей IPC. Если задано значение None, результат возвращается в виде объекта BytesIO.

compression{‘uncompressed’, ‘lz4’, ‘zstd’}

Метод сжатия. По умолчанию — «uncompressed».

compat_level

Использовать определённый уровень совместимости при экспорте внутренних структур данных Polars.

Примеры

>>> import pathlib
>>>
>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> path: pathlib.Path = dirpath / "new_file.arrow"
>>> df.write_ipc_stream(path)

write_json(
    file: IOBase | str | Path | None = None,
) → str | None

Сериализовать в представление JSON.

Параметры:

file

Путь к файлу или доступный для записи файловый объект, в который будет записан результат. Если задано значение None (по умолчанию), результат возвращается в виде строки.

См. также

DataFrame.write_ndjson

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...     }
... )
>>> df.write_json()
'[{"foo":1,"bar":6},{"foo":2,"bar":7},{"foo":3,"bar":8}]'

write_ndjson(
    file: str | Path | IO[bytes] | IO[str] | None = None,
    *,
    compression: Literal['uncompressed',
    'gzip',
    'zstd'] = 'uncompressed',
    compression_level: int | None = None,
    check_extension: bool = True,
) → str | None

Сериализовать в построчное представление JSON.

Параметры:

file

Путь к файлу или доступный для записи файловый объект, в который будет записан результат. Если задано значение None (по умолчанию), результат возвращается в виде строки.

compression

Формат сжатия.

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

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

compression_level

Уровень сжатия: обычно от 0 до 9 или None, чтобы позволить движку выбрать значение.

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

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

check_extension

Проверять, соответствует ли имя файла настройкам сжатия. Будет вызвана ошибка, если сжатие задано как ‘uncompressed’, а имя файла заканчивается одним из суффиксов (“.gz”, “.zst”, “.zstd”), либо если compression != ‘uncompressed’ и расширение файла не соответствует настройкам. Применяется только в том случае, если file — это путь.

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

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

Примеры

>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3],
...         "bar": [6, 7, 8],
...     }
... )
>>> df.write_ndjson()
'{"foo":1,"bar":6}\n{"foo":2,"bar":7}\n{"foo":3,"bar":8}\n'

write_parquet(
    file: str | Path | IO[bytes],
    *,
    compression: ParquetCompression = 'zstd',
    compression_level: int | None = None,
    statistics: bool | str | dict[str,
    bool] = True,
    row_group_size: int | None = None,
    data_page_size: int | None = None,
    use_pyarrow: bool = False,
    pyarrow_options: dict[str,
    Any] | None = None,
    partition_by: str | Sequence[str] | None = None,
    partition_chunk_size_bytes: int = 4294967296,
    storage_options: StorageOptionsDict | None = None,
    credential_provider: CredentialProviderFunction | Literal['auto'] | None = 'auto',
    retries: int | None = None,
    metadata: ParquetMetadata | None = None,
    arrow_schema: ArrowSchemaExportable | None = None,
    mkdir: bool = False,
) → None

Записать в файл Apache Parquet.

Параметры:

file

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

compression{‘lz4’, ‘uncompressed’, ‘snappy’, ‘gzip’, ‘brotli’, ‘zstd’}

Выберите “zstd” для хорошей производительности сжатия. Выберите “lz4” для быстрого сжатия и распаковки. Выберите “snappy” для большей гарантии обратной совместимости при работе со старыми средствами чтения Parquet.

compression_level

Уровень сжатия. Чем выше уровень сжатия, тем меньше размер файлов на диске.

• “gzip” : минимальный уровень: 0, максимальный уровень: 9, по умолчанию: 6.
• “brotli” : минимальный уровень: 0, максимальный уровень: 11, по умолчанию: 1.
• “zstd” : минимальный уровень: 1, максимальный уровень: 22, по умолчанию: 3.

statistics

Записывать статистику в заголовки Parquet. Это поведение используется по умолчанию.

Возможные значения:

• True: включить стандартный набор статистики (по умолчанию). Некоторые статистические данные могут быть отключены.
• False: отключить всю статистику
• “full”: вычислить и записать всю доступную статистику. Нельзя использовать вместе с use_pyarrow.

• { "statistic-key": True / False, ... }. Нельзя использовать вместе с use_pyarrow. Доступные ключи:

  • “min”: минимальное значение столбца (по умолчанию: True)
  • “max”: максимальное значение столбца (по умолчанию: True)
  • “distinct_count”: количество уникальных значений столбца (по умолчанию: False)
  • “null_count”: количество null-значений в столбце (по умолчанию: True)

row_group_size

Размер групп строк в количестве строк. По умолчанию — 512^2 строк.

data_page_size

Размер страницы данных в байтах. По умолчанию — 1024^2 байт.

use_pyarrow

Использовать реализацию Parquet на C++ из PyArrow вместо нативной реализации Polars на Rust. Это может пригодиться, если нужны определённые функции PyArrow через pyarrow_options. При включении этого параметра некоторые возможности не поддерживаются (например, statistics="full", metadata, mkdir).

pyarrow_options

Аргументы, передаваемые в pyarrow.parquet.write_table.

Если передать сюда partition_cols, набор данных будет записан с помощью pyarrow.parquet.write_to_dataset. Параметр partition_cols приводит к записи набора данных в каталог. Аналогично секционированным наборам данных Spark. Для нативной записи с секционированием рассмотрите возможность использования partition_by.

partition_by

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

partition_chunk_size_bytes

Приблизительный размер для разделения DataFrame внутри одного раздела при записи. Обратите внимание: значение рассчитывается по размеру DataFrame в памяти; размер выходного файла может отличаться в зависимости от формата файла и сжатия.

storage_options

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

В настоящее время поддерживаются облачные провайдеры AWS, GCP и Azure. Поддерживаемые ключи приведены здесь:

• aws
• gcp
• azure
• Hugging Face (hf://): принимает ключ API в параметре token: {'token': '...'} или через переменную окружения HF_TOKEN.

Если storage_options не указан, Polars попытается получить эту информацию из переменных окружения.

credential_provider

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

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

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

retries

Количество повторных попыток при сбое доступа к облачному экземпляру.

Устарело с версии 1.37.1: Вместо этого передайте {“max_retries”: n} через storage_options.

metadata

Словарь или функция обратного вызова для добавления пар «ключ — значение» в метаданные Parquet на уровне файла.

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

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

arrow_schema

Пользовательская схема Arrow для записи в файл. Это позволяет задать пользовательскую схему и метаданные на уровне полей. Имена и типы данных должны совпадать.

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

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

mkdir: bool

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

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

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

Примеры

>>> import pathlib
>>>
>>> df = pl.DataFrame(
...     {
...         "foo": [1, 2, 3, 4, 5],
...         "bar": [6, 7, 8, 9, 10],
...         "ham": ["a", "b", "c", "d", "e"],
...     }
... )
>>> path: pathlib.Path = dirpath / "new_file.parquet"
>>> df.write_parquet(path)

Можно записывать секционированные наборы данных. В следующем примере первая строка будет записана в ../watermark=1/.parquet, а остальные строки — в ../watermark=2/.parquet.

>>> df = pl.DataFrame({"a": [1, 2, 3], "watermark": [1, 2, 2]})
>>> path: pathlib.Path = dirpath / "partitioned_object"
>>> df.write_parquet(
...     path,
...     partition_by=["watermark"],
... )