polars.Series.to_numpy

Series.to_numpy(
    *,
    writable: bool = False,
    allow_copy: bool = True,
    use_pyarrow: bool | None = None,
    zero_copy_only: bool | None = None,
) → ndarray[Any, Any]

Преобразует этот Series в массив NumPy ndarray.

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

• Тип данных — целочисленный, с плавающей точкой, Datetime, Duration или Array.
• Series не содержит значений null.
• Series состоит из одного фрагмента.
• Параметр writable имеет значение False (по умолчанию).

Параметры:

writable

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

allow_copy

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

use_pyarrow

Сначала преобразует данные в PyArrow, а затем вызывает pyarrow.Array.to_numpy для преобразования в NumPy. Если задано значение False, используется собственная логика преобразования Polars.

Устарело с версии 0.20.28: Теперь Polars по умолчанию использует собственный механизм для преобразования в NumPy. Чтобы использовать механизм PyArrow, вместо этого вызовите .to_arrow().to_numpy().

zero_copy_only

Вызывает исключение, если для преобразования в NumPy требуется копирование базовых данных. Например, данные копируются, если Series содержит значения null или нечисловые типы.

Устарело с версии 0.20.10: Вместо этого используйте параметр allow_copy, который является инверсией данного параметра.

Примеры

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

>>> s = pl.Series([1, 2, 3], dtype=pl.Int8)
>>> arr = s.to_numpy()
>>> arr
array([1, 2, 3], dtype=int8)
>>> arr.flags.writeable
False

Задайте writable=True, чтобы принудительно копировать данные и сделать массив доступным для записи.

>>> s.to_numpy(writable=True).flags.writeable
True

Целочисленный Series, содержащий значения null, будет приведён к типу с плавающей точкой, где nan обозначает значение null. Для этого требуется копирование данных.

>>> s = pl.Series([1, 2, None], dtype=pl.UInt16)
>>> s.to_numpy()
array([ 1.,  2., nan], dtype=float32)

Задайте 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

Series типов данных Array и Struct преобразуются в массив с более чем одним измерением.

>>> s = pl.Series([[1, 2, 3], [4, 5, 6]], dtype=pl.Array(pl.Int64, 3))
>>> s.to_numpy()
array([[1, 2, 3],
       [4, 5, 6]])