Стандартные подклассы массивов

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

NumPy предоставляет несколько крючков, которые классы могут настраивать:

class.__array_ufunc__(ufunc, method, *inputs, **kwargs)

Введено в версии 1.13.

Любой класс, подкласс ndarray или нет, может определить этот метод или установить его в None, чтобы переопределить поведение ufunc NumPy. Это работает очень похоже на Python __mul__ и другие двоичные операторные процедуры.

• ufunc — объект ufunc, который был вызван.
• method — строка, указывающая, какой метод Ufunc был вызван (один из "__call__", "reduce", "reduceat", "accumulate", "outer", "inner").
• inputs — кортеж входных аргументов в ufunc.
• kwargs — словарь, содержащий необязательные входные аргументы ufunc. Если заданы, все аргументы out, как позиционные, так и ключевые, передаются в виде tuple в kwargs. Подробности см. в обсуждении в Универсальные функции (ufunc).

Метод должен вернуть либо результат операции, либо NotImplemented, если запрошенная операция не реализована.

Если у одного из входных, выходных или where аргументов есть метод __array_ufunc__, он выполняется вместо ufunc. Если более одного из аргументов реализуют __array_ufunc__, они проверяются в следующем порядке: подклассы перед суперклассами, входные данные перед выходными, выходные перед where, иначе слева направо. Первый метод, возвращающий значение отличное от NotImplemented, определяет результат. Если все операции __array_ufunc__ возвращают NotImplemented, генерируется TypeError.

Примечание

Мы намерены повторно реализовать функции numpy как (обобщенные) Ufunc, в этом случае появится возможность их переопределения методом __array_ufunc__ . Основной кандидат — matmul, который в настоящее время не является Ufunc, но его можно сравнительно легко переписать в виде (набора) обобщенных Ufunc. То же самое может произойти с функциями, такими как median, amin и argsort.

Как и в случае с другими специальными методами в Python, такими как __hash__ и __iter__, можно указать, что ваш класс не поддерживает ufunc, установив __array_ufunc__ = None. Ufunc всегда генерирует TypeError, когда вызывается на объекте, который устанавливает __array_ufunc__ = None.

Наличие __array_ufunc__ также влияет на то, как ndarray обрабатывает двоичные операции, такие как arr + obj и arr < obj, когда arr является ndarray, а obj — экземпляром пользовательского класса. Существуют два варианта. Если obj.__array_ufunc__ присутствует и не равно None, то ndarray.__add__ и друзья делегируют работу механизму ufunc, что означает, что arr + obj становится np.add(arr, obj), а затем add вызывает obj.__array_ufunc__. Это полезно, если вы хотите определить объект, который ведет себя как массив.

В противном случае, если obj.__array_ufunc__ установлено в None, как специальный случай, специальные методы, такие как ndarray.__add__ , заметят это и безусловно сгенерируют TypeError. Это полезно, если вы хотите создавать объекты, которые взаимодействуют с массивами с помощью двоичных операций, но сами не являются массивами. Например, система обработки единиц может иметь объект m, представляющий единицу «метры», и захочет поддержать синтаксис arr * m для указания того, что массив имеет единицы измерения «метры», но не хочет взаимодействовать с массивами через ufuncs или каким-либо другим способом. Это можно сделать, установив __array_ufunc__ = None и определив методы __mul__ и __rmul__. (Обратите внимание, что это означает, что написание __array_ufunc__, который всегда возвращает NotImplemented, не совсем то же самое, что установка __array_ufunc__ = None: в первом случае arr + obj сгенерирует TypeError, а во втором случае можно определить метод __radd__ , чтобы предотвратить это.)

Вышесказанное не относится к операторам на месте, для которых ndarray никогда не возвращает NotImplemented. Следовательно, arr += obj всегда приведет к TypeError. Это связано с тем, что для массивов операции на месте не могут быть обобщенно заменены простой обратной операцией. (Например, по умолчанию arr += obj будет переведено в arr = arr + obj, то есть arr будет заменено, что противоречит ожидаемому для операций на месте с массивами.)

Примечание

Если вы определили __array_ufunc__:

• Если вы не являетесь подклассом ndarray, мы рекомендуем вашему классу определять специальные методы, такие как __add__ и __lt__, которые делегируют вычисления ufunc так же, как делает ndarray. Простой способ сделать это — наследование от NDArrayOperatorsMixin.
• Если вы являетесь подклассом ndarray, мы рекомендуем поместить всю логику переопределения в __array_ufunc__ и не переопределять также специальные методы. Это гарантирует, что иерархия классов определяется только в одном месте, а не раздельно механизмом ufunc и правилами двоичных операций (которые отдают предпочтение специальным методам подклассов; альтернативный способ принудительного определения иерархии в одном месте, установив __array_ufunc__ в None, кажется очень неожиданным и, следовательно, непонятным, так как тогда подкласс вообще не будет работать с ufuncs).
• ndarray определяет собственный __array_ufunc__, который оценивает ufunc, если у аргументов нет переопределений, и возвращает NotImplemented в противном случае. Это может быть полезно для подклассов, для которых __array_ufunc__ преобразует все экземпляры своего собственного класса в ndarray: он затем может передать их своему суперклассу, используя super().__array_ufunc__(*inputs, **kwargs), и, наконец, вернуть результаты после возможного обратного преобразования. Преимущество этой практики заключается в том, что она гарантирует возможность существования иерархии подклассов, расширяющих поведение. Подробнее см. Наследование ndarray.

class.__array_function__(func, types, args, kwargs)

New in version 1.16.

• func — произвольное вызываемое значение, экспонируемое общедоступным API NumPy, которое было вызвано в форме func(*args, **kwargs).
• types — коллекция collections.abc.Collection уникальных типов аргументов из исходного вызова функции NumPy, реализующих __array_function__.
• Кортеж args и словарь kwargs передаются непосредственно из исходного вызова.

В качестве удобства для разработчиков __array_function__, types предоставляет все типы аргументов с атрибутом '__array_function__'. Это позволяет разработчикам быстро определять случаи, когда следует перенаправить обработку к реализациям __array_function__ для других аргументов. Реализации не должны полагаться на порядок итерации types.

Большинство реализаций __array_function__ начинаются с двух проверок:

1. Является ли данная функция чем-то, что мы можем перегрузить?
2. Являются ли все аргументы типа, с которым мы можем работать?

Если эти условия выполняются, __array_function__ должно вернуть результат вызова своей реализации для func(*args, **kwargs). В противном случае оно должно вернуть значение sentinela NotImplemented, указывая, что функция не реализована для этих типов.

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

Также удобно определить пользовательские декораторы (implements ниже) для регистрации реализаций __array_function__.

HANDLED_FUNCTIONS = {}

class MyArray:
    def __array_function__(self, func, types, args, kwargs):
        if func not in HANDLED_FUNCTIONS:
            return NotImplemented
        # Note: this allows subclasses that don't override
        # __array_function__ to handle MyArray objects
        if not all(issubclass(t, MyArray) for t in types):
            return NotImplemented
        return HANDLED_FUNCTIONS[func](*args, **kwargs)

def implements(numpy_function):
    """Register an __array_function__ implementation for MyArray objects."""
    def decorator(func):
        HANDLED_FUNCTIONS[numpy_function] = func
        return func
    return decorator

@implements(np.concatenate)
def concatenate(arrays, axis=0, out=None):
    ...  # implementation of concatenate for MyArray objects

@implements(np.broadcast_to)
def broadcast_to(array, shape):
    ...  # implementation of broadcast_to for MyArray objects

Обратите внимание, что от реализаций __array_function__ не требуется включать все соответствующие необязательные аргументы функции NumPy (например, broadcast_to выше пропускает неважный аргумент subok). Необязательные аргументы передаются в __array_function__ только в том случае, если они были явно использованы в вызове функции NumPy.

Так же, как и в случае встроенных специальных методов, таких как __add__, правильно написанные методы __array_function__ всегда должны возвращать NotImplemented при обнаружении неизвестного типа. В противном случае невозможно будет правильно переопределить функции NumPy из другого объекта, если операция также включает один из ваших объектов.

В основном, правила для диспетчеризации с __array_function__ соответствуют правилам для __array_ufunc__. В частности:

• NumPy соберет реализации __array_function__ от всех указанных входных данных и вызовет их в порядке: подклассы перед суперклассами, а в противном случае слева направо. Обратите внимание, что в некоторых крайних случаях, связанных с подклассами, это немного отличается от текущего поведения Python.
• Реализации __array_function__ указывают, что они могут обработать операцию, возвращая любое значение, отличное от NotImplemented.
• Если все методы __array_function__ возвращают NotImplemented, NumPy поднимет TypeError.

Если методы __array_function__ не существуют, NumPy по умолчанию вызовет собственную реализацию, предназначенную для использования с массивами NumPy. Этот случай возникает, например, когда все массивоподобные аргументы — это числа Python или списки. (Массивы NumPy имеют метод __array_function__, указанный ниже, но он всегда возвращает NotImplemented если любой аргумент, кроме подкласса массива NumPy, реализует __array_function__).

Одно отличие от текущего поведения __array_ufunc__ заключается в том, что NumPy вызовет __array_function__ только для первого аргумента каждого уникального типа. Это соответствует правилу Python для вызова отраженных методов, и это гарантирует, что проверка перегрузок имеет приемлемую производительность даже при большом количестве перегруженных аргументов.

class.__array_finalize__(obj)

Этот метод вызывается всякий раз, когда система внутренне выделяет новый массив из obj, где obj является подклассом (подтипом) ndarray. Его можно использовать для изменения атрибутов self после построения (например, для обеспечения 2-мерной матрицы) или для обновления метаданных из «родителя». Подклассы наследуют реализацию этого метода по умолчанию, которая ничего не делает.

class.__array_wrap__(array, context=None, return_scalar=False)

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

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

Изменено в версии 2.0: return_scalar теперь передаётся либо как False (обычно), либо как True, указывая, что NumPy вернёт скаляр. Подклассы могут игнорировать значение или возвращать array[()], чтобы вести себя более похожим образом на NumPy.

Примечание

Надеемся в конечном итоге устареть этот метод в пользу func:__array_ufunc__ для ufunc (и __array_function__ для некоторых других функций, например, numpy.squeeze).

class.__array_priority__

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

Примечание

Для ufunc, надеемся в конечном итоге устареть этот метод в пользу __array_ufunc__.

class.__array__(dtype=None, copy=None)

Если определён на объекте, должен вернуть ndarray. Этот метод вызывается функциями приведения к массиву, такими как np.array(), если объекту, реализующему этот интерфейс, передаётся в эти функции. Реализации __array__ сторонних разработчиков должны принимать ключевые аргументы dtype и copy, так как игнорирование их может нарушить код сторонних разработчиков или сам NumPy.

• dtype — тип данных возвращаемого массива.
• copy — необязательный булевый, указывающий, следует ли возвращать копию. Для True копия всегда должна быть создана, для None только если это необходимо (например, из-за переданного значения dtype), а для False копия никогда не должна создаваться (если копия всё же требуется, должно быть выброшено соответствующее исключение).

См. Взаимодействие с NumPy для иерархии протоколов, из которых __array__ является самым старым и наименее желательным.

Примечание

Если класс (подкласс ndarray или нет), имеющий метод __array__, используется в качестве объекта вывода ufunc, результаты не записываются в объект, возвращаемый __array__. Эта практика вернёт TypeError.

Матричные объекты

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

1. Матричные объекты могут быть созданы с использованием строкового обозначения, что позволяет использовать синтаксис в стиле Matlab, где пробелы отделяют столбцы, а точки с запятой (';') — строки.
2. Матричные объекты всегда двумерные. Это имеет далеко идущие последствия, поскольку m.ravel() все еще двумерный (с 1 в первом измерении), а выбор элементов возвращает двумерные объекты, так что поведение последовательности принципиально отличается от массивов.
3. Матричные объекты переопределяют умножение для выполнения матричного умножения. Убедитесь, что вы понимаете это для функций, которые могут получать матрицы. Особенно с учетом того, что asanyarray(m) возвращает матрицу, когда m — матрица.
4. Матричные объекты переопределяют возведение в степень для выполнения возведения матрицы в степень. То же предупреждение о использовании возведения в степень внутри функции, использующей asanyarray(...), чтобы получить объект массива, справедливо и в этом случае.
5. Значение по умолчанию __array_priority__ для матричных объектов составляет 10,0, и поэтому смешанные операции с ndarray всегда производят матрицы.

6. Матрицы имеют специальные атрибуты, которые упрощают вычисления. Это

   matrix.T	Возвращает транспонированную матрицу.
   matrix.H	Возвращает (комплексно) сопряженную транспонированную матрицу self.
   matrix.I	Возвращает (мультипликативное) обратное значение обратимой матрицы self.
   matrix.A	Возвращает self как объект ndarray.

Класс матриц — это подкласс Python ndarray, который может использоваться как справочник для создания собственного подкласса ndarray. Матрицы могут быть созданы из других матриц, строк и всего, что может быть преобразовано в ndarray. Имя «mat» — псевдоним для «matrix» в NumPy.

Пример 1: Создание матрицы из строки

>>> a = np.asmatrix('1 2 3; 4 5 3')
>>> print((a*a.T).I)
    [[ 0.29239766 -0.13450292]
     [-0.13450292  0.08187135]]

Пример 2: Создание матрицы из вложенной последовательности

>>> np.asmatrix([[1,5,10],[1.0,3,4j]])
matrix([[  1.+0.j,   5.+0.j,  10.+0.j],
        [  1.+0.j,   3.+0.j,   0.+4.j]])

Пример 3: Создание матрицы из массива

>>> np.asmatrix(np.random.rand(3,3)).T
matrix([[4.17022005e-01, 3.02332573e-01, 1.86260211e-01],
        [7.20324493e-01, 1.46755891e-01, 3.45560727e-01],
        [1.14374817e-04, 9.23385948e-02, 3.96767474e-01]])

Массивы файлов с отображением в памяти

Файлы с отображением в памяти полезны для чтения и/или изменения небольших фрагментов большого файла с регулярной структурой без чтения всего файла в память. Простой подкласс ndarray использует файл с отображением в памяти для буфера данных массива. Для небольших файлов накладные расходы на чтение всего файла в память, как правило, не значительны, однако для больших файлов использование отображения в памяти может существенно сэкономить ресурсы.

Массивы файлов с отображением в памяти имеют один дополнительный метод (кроме тех, которые они наследуют от ndarray): .flush(), который должен вызываться пользователем вручную, чтобы гарантировать, что любые изменения в массиве действительно записываются на диск.

Пример:

>>> a = np.memmap('newfile.dat', dtype=float, mode='w+', shape=1000)
>>> a[10] = 10.0
>>> a[30] = 30.0
>>> del a
>>> b = np.fromfile('newfile.dat', dtype=float)
>>> print(b[10], b[30])
10.0 30.0
>>> a = np.memmap('newfile.dat', dtype=float)
>>> print(a[10], a[30])
10.0 30.0

Массивы символов (numpy.char)

Это расширенные массивы типа str_ или типа bytes_. Эти массивы наследуют от ndarray, но специально определяют операции +, *, и % на основе (векторных) элемента-за-элементом. Эти операции недоступны для стандартного ndarray символьного типа. Кроме того, chararray обладает всеми стандартными методами str (и bytes), выполняющими их на основе элемента за элементом. Возможно, самым простым способом создания chararray является использование self.view(chararray), где self — ndarray типа str или unicode. Однако chararray также можно создать, используя конструктор chararray или функцию numpy.char.array:

Другое отличие от стандартного ndarray типа str заключается в том, что chararray наследует функцию, введенную Numarray, что пробелы в конце любого элемента массива будут игнорироваться при получении элемента и сравнениях.

Массивы записей

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

Маскированные массивы (numpy.ma)

Стандартный контейнерный класс

Для обеспечения обратной совместимости и в качестве стандартного «контейнерного» класса, класс UserArray из Numeric перенесён в NumPy и переименован в numpy.lib.user_array.container. Контейнерный класс — это класс Python, атрибут self.array которого является ndarray. Наследование с множественным наследованием, вероятно, проще с numpy.lib.user_array.container, чем с самим ndarray, поэтому оно включено по умолчанию. Оно не документируется здесь, кроме упоминания о его существовании, так как рекомендуется использовать класс ndarray напрямую, если это возможно.

Итераторы массивов

Итераторы — мощная концепция для обработки массивов. По сути, итераторы реализуют обобщённый цикл for. Если myiter — объект итератора, то код Python:

for val in myiter:
    ...
    some code involving val
    ...

вызывает val = next(myiter) многократно до тех пор, пока не будет вызвано StopIteration итератором. Существует несколько способов итерирования по массиву, которые могут быть полезны: стандартное итерирование, плоское итерирование и \(N\)-мерное перечисление.

for i in range(arr.shape[0]):
    val = arr[i]

>>> a = np.arange(24).reshape(3,2,4)+10
>>> for val in a:
...     print('item:', val)
item: [[10 11 12 13]
 [14 15 16 17]]
item: [[18 19 20 21]
 [22 23 24 25]]
item: [[26 27 28 29]
 [30 31 32 33]]

>>> for i, val in enumerate(a.flat):
...     if i%5 == 0: print(i, val)
0 10
5 15
10 20
15 25
20 30

>>> for i, val in np.ndenumerate(a):
...     if sum(i)%5 == 0: print(i, val)
(0, 0, 0) 10
(1, 1, 3) 25
(2, 0, 3) 29
(2, 1, 2) 32

>>> for val in np.broadcast([[1, 0], [2, 3]], [0, 1]):
...     print(val)
(np.int64(1), np.int64(0))
(np.int64(0), np.int64(1))
(np.int64(2), np.int64(0))
(np.int64(3), np.int64(1))