polars.DataFrame.to_numpy

DataFrame.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-contiguous. Используйте order="c", чтобы принудительно получить массив в порядке C-contiguous.

>>> 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')])