Многомерный массив (ndarray)

Массив ndarray представляет собой (обычно с фиксированным размером) многомерный контейнер элементов одного типа и размера. Количество измерений и элементов в массиве определяется его shape, который является tuple из N неотрицательных целых чисел, определяющих размеры каждого измерения. Тип элементов в массиве определяется отдельным объектом типа данных (dtype), каждый из которых связан с каждым ndarray.

Как и другие контейнерные объекты в Python, содержимое массива ndarray может быть обработано и изменено путем индексирования или среза массива (используя, например, N целых чисел), а также через методы и атрибуты массива ndarray.

Разные ndarrays могут совместно использовать одни и те же данные, так что изменения, внесенные в одном ndarray, могут быть видны в другом. То есть, ndarray может быть «просмотром» другого ndarray, а за данными, на которые он ссылается, отвечает «базовый» ndarray. ndarray также могут быть представлениями памяти, принадлежащей Python strings или объектам, реализующим интерфейсы memoryview или массива.

Пример

Двумерный массив размером 2 x 3, состоящий из 4-байтовых целочисленных элементов:

>>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32)
>>> type(x)
<class 'numpy.ndarray'>
>>> x.shape
(2, 3)
>>> x.dtype
dtype('int32')

К массиву можно обратиться с помощью синтаксиса, подобного контейнерам Python:

>>> # The element of x in the *second* row, *third* column, namely, 6.
>>> x[1, 2]
6

Например, срезы могут создавать представления массива:

>>> y = x[:,1]
>>> y
array([2, 5], dtype=int32)
>>> y[0] = 9 # this also changes the corresponding element in x
>>> y
array([9, 5], dtype=int32)
>>> x
array([[1, 9, 3],
       [4, 5, 6]], dtype=int32)

Создание массивов

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

ndarray(shape[, dtype, buffer, offset, ...])

Объект массива представляет собой многомерный однородный массив элементов фиксированного размера.

Индексирование массивов

Массивы можно индексировать с помощью расширенного синтаксиса срезов Python, array[selection]. Аналогичный синтаксис также используется для доступа к полям в структурированном типе данных.

См. также

Индексирование массивов.

Внутреннее расположение памяти ndarray

Экземпляр класса ndarray состоит из непрерывного одномерного сегмента компьютерной памяти (принадлежащей массиву или другому объекту), совместно с схемой индексирования, которая отображает N целых чисел в положение элемента в блоке. Диапазоны, в которых могут изменяться индексы, задаются shape массива. Размер байтов каждого элемента и способ интерпретации байтов определяются связанным с массивом объектом типа данных.

Сегмент памяти изначально одномерный, и существует множество схем для размещения элементов N-мерного массива в одномерном блоке. NumPy гибкий, и объекты ndarray могут адаптироваться к любой схеме индексирования со смещением. В схеме со смещением N-мерный индекс \((n_0, n_1, ..., n_{N-1})\) соответствует смещению (в байтах):

\[n_{\mathrm{offset}} = \sum_{k=0}^{N-1} s_k n_k\]

от начала блока памяти, связанного с массивом. Здесь \(s_k\) — целые числа, которые задают strides массива. Порядок следования столбцов (используемый, например, в языке Fortran и в Matlab) и порядок следования строк (используемый в C) — это просто частные случаи схемы со смещением, и соответствуют памяти, к которой можно обратиться с помощью смещений:

\[s_k^{\mathrm{column}} = \mathrm{itemsize} \prod_{j=0}^{k-1} d_j , \quad s_k^{\mathrm{row}} = \mathrm{itemsize} \prod_{j=k+1}^{N-1} d_j .\]

где \(d_j\) = self.shape[j].

Оба порядка (C и Fortran) являются непрерывными, то есть имеют односегментную структуру памяти, в которой к каждой части блока памяти можно обратиться с помощью некоторой комбинации индексов.

Примечание

Непрерывные массивы и односегментные массивы — синонимы и используются взаимозаменяемо в документации.

Хотя массив, непрерывный в стиле C или Fortran, у которого установлены соответствующие флаги, может быть обработано с указанными выше смещениями, фактические смещения могут быть другими. Это может произойти в двух случаях:

Если self.shape[k] == 1 то для любого допустимого индекса index[k] == 0. Это означает, что в формуле для смещения \(n_k = 0\) и, следовательно, \(s_k n_k = 0\) и значение \(s_k\) = self.strides[k] произвольное.
Если массив не имеет элементов (self.size == 0) допустимого индекса нет, и смещения никогда не используются. Любой массив без элементов может считаться непрерывным в стиле C и Fortran.

Пункт 1 означает, что self и self.squeeze() всегда имеют одинаковую непрерывность и aligned значения флагов. Это также означает, что даже многомерный массив может быть одновременно непрерывным в стиле C и Fortran.

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

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

В общем случае self.strides[-1] == self.itemsize для непрерывных массивов в стиле C или self.strides[0] == self.itemsize для непрерывных массивов в стиле Fortran неверно.

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

Примечание

Некоторые алгоритмы в NumPy работают с произвольно смещёнными массивами. Однако некоторые алгоритмы требуют односегментных массивов. Когда в такие алгоритмы передается массив с произвольным смещением, автоматически создаётся копия.

Атрибуты массива

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

Макет памяти

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

`ndarray.flags`	Информация о макете памяти массива.
`ndarray.shape`	Кортеж измерений массива.
`ndarray.strides`	Кортеж байтов, которые нужно пропустить в каждом измерении при прохождении по массиву.
`ndarray.ndim`	Количество измерений массива.
`ndarray.data`	Объект буфера Python, указывающий на начало данных массива.
`ndarray.size`	Количество элементов в массиве.
`ndarray.itemsize`	Длина одного элемента массива в байтах.
`ndarray.nbytes`	Общее количество байтов, занимаемых элементами массива.
`ndarray.base`	Базовый объект, если память взята из другого объекта.

Тип данных

См. также

Объекты типов данных

Объект типа данных, связанный с массивом, можно найти в атрибуте dtype:

ndarray.dtype

Тип данных элементов массива.

Другие атрибуты

`ndarray.T`	Представление транспонированного массива.
`ndarray.real`	Вещественная часть массива.
`ndarray.imag`	Мнимая часть массива.
`ndarray.flat`	Итератор по массиву в 1-D формате.

Интерфейс массива

См. также

Протокол интерфейса массива.

`__array_interface__`	Сторона Python интерфейса массива
`__array_struct__`	Сторона C интерфейса массива

`ctypes` интерфейс внешних функций

ndarray.ctypes

Объект для упрощения взаимодействия массива с модулем ctypes.

Методы массивов

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

Для следующих методов также существуют соответствующие функции в numpy: all, any, argmax, argmin, argpartition, argsort, choose, clip, compress, copy, cumprod, cumsum, diagonal, imag, max, mean, min, nonzero, partition, prod, put, ravel, real, repeat, reshape, round, searchsorted, sort, squeeze, std, sum, swapaxes, take, trace, transpose, var.

Преобразование массивов

`ndarray.item`(*args)	Копирует элемент массива в стандартный скаляр Python и возвращает его.
`ndarray.tolist`()	Возвращает массив в виде вложенного списка Pythonских скаляров до глубины `a.ndim`.
`ndarray.tostring`([order])	Синоним для `tobytes`, с абсолютно таким же поведением.
`ndarray.tobytes`([order])	Создаёт строку Python с сырыми байтовыми данными массива.
`ndarray.tofile`(fid[, sep, format])	Записывает массив в файл как текст или двоичные данные (по умолчанию).
`ndarray.dump`(file)	Сохраняет пикл массива в указанный файл.
`ndarray.dumps`()	Возвращает строку пикла массива.
`ndarray.astype`(dtype[, order, casting, ...])	Копия массива, преобразованного к указанному типу.
`ndarray.byteswap`([inplace])	Меняет порядок байтов элементов массива.
`ndarray.copy`([order])	Возвращает копию массива.
`ndarray.view`([dtype][, type])	Новый вид массива с теми же данными.
`ndarray.getfield`(dtype[, offset])	Возвращает поле данного массива как определённого типа.
`ndarray.setflags`([write, align, uic])	Устанавливает флаги массива WRITEABLE, ALIGNED, WRITEBACKIFCOPY соответственно.
`ndarray.fill`(value)	Заполняет массив скалярным значением.

Изменение формы массива

Для reshape, resize и transpose единственный кортеж аргумента может быть заменён на n целых чисел, которые будут интерпретированы как n-кортеж.

`ndarray.reshape`(shape, /, *[, order])	Возвращает массив, содержащий те же данные с новой формой.
`ndarray.resize`(new_shape[, refcheck])	Изменяет форму и размер массива на месте.
`ndarray.transpose`(*axes)	Возвращает представление массива с транспонированными осями.
`ndarray.swapaxes`(axis1, axis2)	Возвращает представление массива с осями `axis1` и `axis2` поменянными местами.
`ndarray.flatten`([order])	Возвращает копию массива, сжатого в одно измерение.
`ndarray.ravel`([order])	Возвращает уплощённый массив.
`ndarray.squeeze`([axis])	Удаляет оси длины один из `a`.

Выбор и обработка элементов

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

`ndarray.take`(indices[, axis, out, mode])	Возвращает массив, образованный элементами `a` по заданным индексам.
`ndarray.put`(indices, values[, mode])	Устанавливает `a.flat[n] = values[n]` для всех `n` в indices.
`ndarray.repeat`(repeats[, axis])	Повторяет элементы массива.
`ndarray.choose`(choices[, out, mode])	Использует массив индексов для построения нового массива из набора вариантов.
`ndarray.sort`([axis, kind, order])	Сортирует массив на месте.
`ndarray.argsort`([axis, kind, order])	Возвращает индексы, которые отсортировали бы этот массив.
`ndarray.partition`(kth[, axis, kind, order])	Частично сортирует элементы в массиве таким образом, что значение элемента в позиции k находится в позиции, в которой оно находилось бы в отсортированном массиве.
`ndarray.argpartition`(kth[, axis, kind, order])	Возвращает индексы, которые бы разделили этот массив.
`ndarray.searchsorted`(v[, side, sorter])	Находит индексы, куда элементы v следует вставить в массив a, чтобы сохранить порядок.
`ndarray.nonzero`()	Возвращает индексы элементов, отличных от нуля.
`ndarray.compress`(condition[, axis, out])	Возвращает выбранные срезы этого массива вдоль заданной оси.
`ndarray.diagonal`([offset, axis1, axis2])	Возвращает указанные диагонали.

Вычисления

Многие из этих методов принимают аргумент axis. В таких случаях,

Если axis равно None (по умолчанию), массив обрабатывается как одномерный, и операция выполняется над всем массивом. Это поведение также является по умолчанию, если self является массивом нулевой размерности или скаляром массива. (Скаляр массива — это экземпляр типов/классов float32, float64 и т. д., а массив нулевой размерности — это экземпляр ndarray, содержащий ровно один скаляр массива.)
Если axis является целым числом, операция выполняется по данной оси (для каждого одномерного подмассива, который можно создать вдоль заданной оси).

Пример аргумента axis

Трехмерный массив размером 3 x 3 x 3, суммированный по каждой из трёх осей

>>> x = np.arange(27).reshape((3,3,3))
>>> x
array([[[ 0,  1,  2],
        [ 3,  4,  5],
        [ 6,  7,  8]],
       [[ 9, 10, 11],
        [12, 13, 14],
        [15, 16, 17]],
       [[18, 19, 20],
        [21, 22, 23],
        [24, 25, 26]]])
>>> x.sum(axis=0)
array([[27, 30, 33],
       [36, 39, 42],
       [45, 48, 51]])
>>> # for sum, axis is the first keyword, so we may omit it,
>>> # specifying only its value
>>> x.sum(0), x.sum(1), x.sum(2)
(array([[27, 30, 33],
        [36, 39, 42],
        [45, 48, 51]]),
 array([[ 9, 12, 15],
        [36, 39, 42],
        [63, 66, 69]]),
 array([[ 3, 12, 21],
        [30, 39, 48],
        [57, 66, 75]]))

Параметр dtype задаёт тип данных, по которому должна выполняться операция редукции (например, суммирование). Тип данных редукции по умолчанию — такой же, как тип данных self. Для предотвращения переполнения может быть полезно выполнить редукцию с использованием более крупного типа данных.

Для нескольких методов также можно указать необязательный аргумент out, и результат будет помещён в выходной массив. Аргумент out должен быть ndarray и иметь такое же количество элементов. Он может иметь другой тип данных, в этом случае будет выполнено приведение.

`ndarray.max`([axis, out, keepdims, initial, ...])	Возвращает максимальное значение вдоль заданной оси.
`ndarray.argmax`([axis, out, keepdims])	Возвращает индексы максимальных значений вдоль заданной оси.
`ndarray.min`([axis, out, keepdims, initial, ...])	Возвращает минимальное значение вдоль заданной оси.
`ndarray.argmin`([axis, out, keepdims])	Возвращает индексы минимальных значений вдоль заданной оси.
`ndarray.clip`([min, max, out])	Возвращает массив, значения которого ограничены `[min, max]`.
`ndarray.conj`()	Комплексно сопрягает все элементы.
`ndarray.round`([decimals, out])	Возвращает `a` с каждым элементом, округленным до заданного числа десятичных знаков.
`ndarray.trace`([offset, axis1, axis2, dtype, out])	Возвращает сумму по диагоналям массива.
`ndarray.sum`([axis, dtype, out, keepdims, ...])	Возвращает сумму элементов массива по заданной оси.
`ndarray.cumsum`([axis, dtype, out])	Возвращает кумулятивную сумму элементов по заданной оси.
`ndarray.mean`([axis, dtype, out, keepdims, where])	Возвращает среднее значение элементов массива по заданной оси.
`ndarray.var`([axis, dtype, out, ddof, ...])	Возвращает дисперсию элементов массива по заданной оси.
`ndarray.std`([axis, dtype, out, ddof, ...])	Возвращает стандартное отклонение элементов массива по заданной оси.
`ndarray.prod`([axis, dtype, out, keepdims, ...])	Возвращает произведение элементов массива по заданной оси.
`ndarray.cumprod`([axis, dtype, out])	Возвращает кумулятивное произведение элементов по заданной оси.
`ndarray.all`([axis, out, keepdims, where])	Возвращает True, если все элементы имеют значение True.
`ndarray.any`([axis, out, keepdims, where])	Возвращает True, если любой из элементов `a` имеет значение True.

Арифметические, операции умножения матриц и сравнения

Арифметические и операции сравнения на ndarrays определены как поэлементные операции и обычно возвращают объекты ndarray в качестве результатов.

Каждая из арифметических операций (+, -, *, /, //, %, divmod(), ** или pow(), <<, >>, &, ^, |, ~ или сравнения (==, <, >, <=, >=, !=) эквивалентна соответствующей универсальной функции (или ufunc для краткости) в NumPy. Для получения дополнительной информации см. раздел Универсальные функции.

Операторы сравнения:

`ndarray.__lt__`(value, /)	Возвращает self<value.
`ndarray.__le__`(value, /)	Возвращает self<=value.
`ndarray.__gt__`(value, /)	Возвращает self>value.
`ndarray.__ge__`(value, /)	Возвращает self>=value.
`ndarray.__eq__`(value, /)	Возвращает self==value.
`ndarray.__ne__`(value, /)	Возвращает self!=value.

Логическое значение массива (bool()):

ndarray.__bool__(/)

True, если self, иначе False

Примечание

Проверка истинности массива вызывает ndarray.__bool__, что вызывает ошибку, если количество элементов в массиве больше 1, потому что истинностное значение таких массивов неоднозначно. Используйте .any() и .all() вместо этого, чтобы однозначно указать, что подразумевается в таких случаях. (Если количество элементов равно 0, массив оценивается как False.)

Унарные операции:

`ndarray.__neg__`(/)	-self
`ndarray.__pos__`(/)	+self
`ndarray.__abs__`(self)
`ndarray.__invert__`(/)	~self

Арифметические операции:

`ndarray.__add__`(value, /)	Возвращает self+value.
`ndarray.__sub__`(value, /)	Возвращает self-value.
`ndarray.__mul__`(value, /)	Возвращает self*value.
`ndarray.__truediv__`(value, /)	Возвращает self/value.
`ndarray.__floordiv__`(value, /)	Возвращает self//value.
`ndarray.__mod__`(value, /)	Возвращает self%value.
`ndarray.__divmod__`(value, /)	Возвращает divmod(self, value).
`ndarray.__pow__`(value[, mod])	Возвращает pow(self, value, mod).
`ndarray.__lshift__`(value, /)	Возвращает self<<value.
`ndarray.__rshift__`(value, /)	Возвращает self>>value.
`ndarray.__and__`(value, /)	Возвращает self&value.
`ndarray.__or__`(value, /)	Возвращает self\|value.
`ndarray.__xor__`(value, /)	Возвращает self^value.

Примечание

Любой третий аргумент для pow игнорируется, так как лежащая в основе ufunc принимает только два аргумента.
Поскольку ndarray является встроенным типом (написанным на C), специальные методы __r{op}__ не определены непосредственно.
Функции, вызываемые для реализации многих арифметических специальных методов для массивов, могут быть изменены с помощью __array_ufunc__.

Арифметические операции, выполняемые на месте:

`ndarray.__iadd__`(value, /)	Возвращает self+=value.
`ndarray.__isub__`(value, /)	Возвращает self-=value.
`ndarray.__imul__`(value, /)	Возвращает self*=value.
`ndarray.__itruediv__`(value, /)	Возвращает self/=value.
`ndarray.__ifloordiv__`(value, /)	Возвращает self//=value.
`ndarray.__imod__`(value, /)	Возвращает self%=value.
`ndarray.__ipow__`(value, /)	Возвращает self**=value.
`ndarray.__ilshift__`(value, /)	Возвращает self<<=value.
`ndarray.__irshift__`(value, /)	Возвращает self>>=value.
`ndarray.__iand__`(value, /)	Возвращает self&=value.
`ndarray.__ior__`(value, /)	Возвращает self\|=value.
`ndarray.__ixor__`(value, /)	Возвращает self^=value.

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

Операции на месте выполняют вычисления с точностью, определяемой типом данных двух операндов, но при этом результат неявно понижается (при необходимости), чтобы он мог поместиться в массив. Поэтому для вычислений с разной точностью A {op}= B может отличаться от A = A {op} B. Например, предположим a = ones((3,3)). Тогда a += 3j отличается от a = a + 3j: хотя оба они выполняют одно и то же вычисление, a += 3 преобразует результат, чтобы он поместился обратно в a, в то время как a = a + 3j привязывает имя a к результату.

Умножение матриц:

ndarray.__matmul__(value, /)

Возвращает self@value.

Примечание

Операторы матриц @ и @= были введены в Python 3.5 вслед за PEP 465, а оператор @ был введен в NumPy 1.10.0. Дополнительную информацию можно найти в документации matmul.

Специальные методы

Для стандартных функций:

`ndarray.__copy__`()	Используется, если к массиву применяется `copy.copy`.
`ndarray.__deepcopy__`(memo, /)	Используется, если к массиву применяется `copy.deepcopy`.
`ndarray.__reduce__`()	Для сериализации.
`ndarray.__setstate__`(state, /)	Для десериализации.

Основные настройки:

`ndarray.__new__`(args, *kwargs)
`ndarray.__array__`([dtype], *[, copy])	Для параметра `dtype` возвращает новую ссылку на self, если `dtype` не указан или совпадает с типом данных массива.
`ndarray.__array_wrap__`(array[, context], /)	Возвращает представление `array` с таким же типом, что и self.

Настройка контейнера: (см. Индексирование)

`ndarray.__len__`(/)	Возвращает len(self).
`ndarray.__getitem__`(key, /)	Возвращает self[key].
`ndarray.__setitem__`(key, value, /)	Устанавливает self[key] в значение value.
`ndarray.__contains__`(key, /)	Возвращает key in self.

Преобразование; операции int(), float() и complex(). Они работают только с массивами, содержащими один элемент, и возвращают соответствующее скалярное значение.

`ndarray.__int__`(self)
`ndarray.__float__`(self)
`ndarray.__complex__`

Представления строк:

`ndarray.__str__`(/)	Возвращает str(self).
`ndarray.__repr__`(/)	Возвращает repr(self).

Утилитарный метод для типизации:

ndarray.__class_getitem__(item, /)

Возвращает параметризованную оболочку вокруг типа ndarray.

© 2005–2024 NumPy Developers
Licensed under the 3-clause BSD License.
https://numpy.org/doc/2.0/reference/arrays.ndarray.html

Многомерный массив (ndarray)

Пример

Создание массивов

Индексирование массивов

Внутреннее расположение памяти ndarray

Атрибуты массива

Макет памяти

Тип данных

Другие атрибуты

Интерфейс массива

ctypes интерфейс внешних функций

Методы массивов

Преобразование массивов

Изменение формы массива

Выбор и обработка элементов

Вычисления

Арифметические, операции умножения матриц и сравнения

Специальные методы

`ctypes` интерфейс внешних функций