NumPy 子类化 ndarray
介绍
对 ndarray 进行子类化相对简单,但与其他 Python 对象相比,它有一些复杂性。在此页面上,我们解释了允许您对 ndarray 进行子类化的机制,以及实现子类的含义。
ndarrays 和对象创建
由于 ndarray 类的新实例可以通过三种不同的方式产生,因此子类化 ndarray 很复杂。这些是:
- 显式构造函数调用 - 如
MySubClass(params)
. 这是创建 Python 实例的常用方法。 - 视图转换 - 将现有的 ndarray 转换为给定的子类
- New from template - 从模板实例创建一个新实例。示例包括从子类数组返回切片、从 ufunc 创建返回类型以及复制数组。有关更多详细信息,请参阅 从模板创建新内容
最后两个是 ndarrays 的特性 - 为了支持数组切片之类的东西。子类化 ndarray 的复杂性是由于 numpy 必须支持后两种实例创建路径的机制。
查看投射
视图转换是标准的 ndarray 机制,您可以通过它获取任何子类的 ndarray,并将数组的视图作为另一个(指定的)子类返回:
>>> import numpy as np
>>> # create a completely useless ndarray subclass
>>> class C(np.ndarray): pass
>>> # create a standard ndarray
>>> arr = np.zeros((3,))
>>> # take a view of it, as our useless subclass
>>> c_arr = arr.view(C)
>>> type(c_arr)
<class 'C'>
从模板创建新
ndarray 子类的新实例也可以通过与View cast非常相似的机制产生,当 numpy 发现它需要从模板实例创建一个新实例时。这必须发生的最明显的地方是当您获取子类数组的切片时。例如:
>>> v = c_arr[1:]
>>> type(v) # the view is of type 'C'
<class 'C'>
>>> v is c_arr # but it's a new instance
False
切片是原始数据的视图c_arr
。因此,当我们从 ndarray 中查看时,我们返回一个新的 ndarray,属于同一类,指向原始数据。
使用 ndarrays 的其他点我们需要这样的视图,例如复制数组 ( c_arr.copy()
)、创建 ufunc 输出数组(另请参阅__array_wrap__ 以了解 ufuncs 和其他函数)和减少方法(如 c_arr.mean()
)。
视图转换和新模板的关系
这些路径都使用相同的机器。我们在这里进行区分,因为它们会导致对您的方法的不同输入。具体来说, 视图转换意味着您已经从 ndarray 的任何潜在子类创建了数组类型的新实例。 从模板 创建新实例意味着您已经从预先存在的实例创建了类的新实例,例如,允许您跨子类特定的属性进行复制。
子类化的含义
如果我们继承 ndarray,我们不仅需要处理数组类型的显式构造,还需要处理视图转换或 从模板创建新的。NumPy 具有执行此操作的机制,正是这种机制使子类化略微非标准。
ndarray 用于支持子类中的视图和新模板的机制有两个方面。
首先是使用该ndarray.__new__
方法进行对象初始化的主要工作,而不是更常用的__init__
方法。第二个是使用该__array_finalize__
方法允许子类在从模板创建视图和新实例后进行清理。
关于__new__
和的简短 Python 入门__init__
__new__
是一个标准的 Python 方法,如果存在,__init__
在我们创建类实例之前调用。有关更多详细信息,请参阅python new 文档。
例如,考虑以下 Python 代码:
class C:
def __new__(cls, *args):
print('Cls in __new__:', cls)
print('Args in __new__:', args)
# The `object` type __new__ method takes a single argument.
return object.__new__(cls)
def __init__(self, *args):
print('type(self) in __init__:', type(self))
print('Args in __init__:', args)
这意味着我们得到:
>>> c = C('hello')
Cls in __new__: <class 'C'>
Args in __new__: ('hello',)
type(self) in __init__: <class 'C'>
Args in __init__: ('hello',)
当我们调用 时C('hello')
,该__new__
方法获取自己的类作为第一个参数,以及传递的参数,即字符串 'hello'
。在 python 调用之后__new__
,它通常(见下文)调用我们的__init__
方法,将 的输出__new__
作为第一个参数(现在是一个类实例),然后是传递的参数。
可以看到,对象可以在__new__
方法中初始化,也可以在方法中初始化__init__
,或者两者都可以,而实际上ndarray是没有__init__
方法的,因为所有的初始化都是在__new__
方法中完成的。
为什么要使用__new__
而不仅仅是通常的__init__
?因为在某些情况下,对于 ndarray,我们希望能够返回某个其他类的对象。考虑以下:
class D(C):
def __new__(cls, *args):
print('D cls is:', cls)
print('D args in __new__:', args)
return C.__new__(C, *args)
def __init__(self, *args):
# we never get here
print('In D __init__')
意思是:
>>> obj = D('hello')
D cls is: <class 'D'>
D args in __new__: ('hello',)
Cls in __new__: <class 'C'>
Args in __new__: ('hello',)
>>> type(obj)
<class 'C'>
的定义C
与之前相同,但对于D
,该 __new__
方法返回类的实例C
而不是 D
。请注意,不会调用的__init__
方法D
。通常,当该__new__
方法返回定义它的类以外的类的对象时,__init__
不会调用该类的方法。
这就是 ndarray 类的子类如何能够返回保留类类型的视图。在查看时,标准的 ndarray 机制会使用以下内容创建新的 ndarray 对象:
obj = ndarray.__new__(subtype, shape, ...
subdtype
子类在哪里。因此,返回的视图与子类属于同一类,而不是属于 class ndarray
。
这解决了返回相同类型视图的问题,但现在我们有一个新问题。ndarray 的机制可以在其用于获取视图的标准方法中以这种方式设置类,但是 ndarray __new__
方法对我们在自己的__new__
方法中为设置属性所做的一切一无所知 ,等等。(另外 - 为什么不调用呢?因为我们可能没有具有相同调用签名的方法)。obj = subdtype.__new__(...``__new__
__array_finalize__
的作用
__array_finalize__
是 numpy 提供的机制,允许子类处理创建新实例的各种方式。
请记住,子类实例可以通过以下三种方式产生:
- 显式构造函数调用 ( )。这将调用then (如果存在) 的通常序列。
obj = MySubClass(params)``MySubClass.__new__``MySubClass.__init__
- 查看演员表
- 从模板创建新
我们的MySubClass.__new__
方法只在显式构造函数调用的情况下被调用,所以我们不能依赖MySubClass.__new__
或 MySubClass.__init__
处理视图转换和新模板。事实证明,MySubClass.__array_finalize__
不被调用对象创建的所有三种方法,所以这是我们的对象创建看家一般无二。
- 对于显式构造函数调用,我们的子类需要创建它自己的类的新 ndarray 实例。在实践中,这意味着我们,代码的作者,需要调用
ndarray.__new__(MySubClass,...)
,类层次结构准备调用 ,或者对现有数组进行视图转换(见下文)super().__new__(cls, ...)
- 对于视图转换和新模板
ndarray.__new__(MySubClass,...
,在 C 级别调用等效项 。
__array_finalize__
上述三种实例创建方法接收的参数不同。
以下代码允许我们查看调用序列和参数:
import numpy as np
class C(np.ndarray):
def __new__(cls, *args, **kwargs):
print('In __new__ with class %s' % cls)
return super().__new__(cls, *args, **kwargs)
def __init__(self, *args, **kwargs):
# in practice you probably will not need or want an __init__
# method for your subclass
print('In __init__ with class %s' % self.__class__)
def __array_finalize__(self, obj):
print('In array_finalize:')
print(' self type is %s' % type(self))
print(' obj type is %s' % type(obj))
现在:
>>> # Explicit constructor
>>> c = C((10,))
In __new__ with class <class 'C'>
In array_finalize:
self type is <class 'C'>
obj type is <type 'NoneType'>
In __init__ with class <class 'C'>
>>> # View casting
>>> a = np.arange(10)
>>> cast_a = a.view(C)
In array_finalize:
self type is <class 'C'>
obj type is <type 'numpy.ndarray'>
>>> # Slicing (example of new-from-template)
>>> cv = c[:1]
In array_finalize:
self type is <class 'C'>
obj type is <class 'C'>
的签名__array_finalize__
是:
def __array_finalize__(self, obj):
可以看到,到 的super
调用 ndarray.__new__
传递__array_finalize__
了我们自己的类 ( self
) 以及从中获取视图的对象( )的新对象obj
。从上面的输出可以看出,self
总是我们子类的一个新创建的实例,obj
三种实例创建方法的类型不同:
- 当从显式构造函数调用时,
obj
是None
- 当从视图转换调用时,
obj
可以是 ndarray 的任何子类的实例,包括我们自己的。 - 当在 new-from-template 中调用时,
obj
是我们自己子类的另一个实例,我们可能会用它来更新新self
实例。
因为__array_finalize__
它是唯一能始终看到新实例被创建的方法,所以它是为新对象属性填充实例默认值以及其他任务的明智之选。
举个例子可能更清楚。
简单示例 - 向 ndarray 添加额外属性
import numpy as np
class InfoArray(np.ndarray):
def __new__(subtype, shape, dtype=float, buffer=None, offset=0,
strides=None, order=None, info=None):
# Create the ndarray instance of our type, given the usual
# ndarray input arguments. This will call the standard
# ndarray constructor, but return an object of our type.
# It also triggers a call to InfoArray.__array_finalize__
obj = super().__new__(subtype, shape, dtype,
buffer, offset, strides, order)
# set the new 'info' attribute to the value passed
obj.info = info
# Finally, we must return the newly created object:
return obj
def __array_finalize__(self, obj):
# ``self`` is a new object resulting from
# ndarray.__new__(InfoArray, ...), therefore it only has
# attributes that the ndarray.__new__ constructor gave it -
# i.e. those of a standard ndarray.
#
# We could have got to the ndarray.__new__ call in 3 ways:
# From an explicit constructor - e.g. InfoArray():
# obj is None
# (we're in the middle of the InfoArray.__new__
# constructor, and self.info will be set when we return to
# InfoArray.__new__)
if obj is None: return
# From view casting - e.g arr.view(InfoArray):
# obj is arr
# (type(obj) can be InfoArray)
# From new-from-template - e.g infoarr[:3]
# type(obj) is InfoArray
#
# Note that it is here, rather than in the __new__ method,
# that we set the default value for 'info', because this
# method sees all creation of default objects - with the
# InfoArray.__new__ constructor, but also with
# arr.view(InfoArray).
self.info = getattr(obj, 'info', None)
# We do not need to return anything
使用对象如下所示:
>>> obj = InfoArray(shape=(3,)) # explicit constructor
>>> type(obj)
<class 'InfoArray'>
>>> obj.info is None
True
>>> obj = InfoArray(shape=(3,), info='information')
>>> obj.info
'information'
>>> v = obj[1:] # new-from-template - here - slicing
>>> type(v)
<class 'InfoArray'>
>>> v.info
'information'
>>> arr = np.arange(10)
>>> cast_arr = arr.view(InfoArray) # view casting
>>> type(cast_arr)
<class 'InfoArray'>
>>> cast_arr.info is None
True
这个类不是很有用,因为它具有与裸 ndarray 对象相同的构造函数,包括传入缓冲区和形状等。我们可能更希望构造函数能够从通常的 numpy 调用中获取一个已经形成的 ndarraynp.array
并返回一个对象。
稍微更现实的例子 - 添加到现有数组的属性
这是一个类,它采用已经存在的标准 ndarray,转换为我们的类型,并添加了一个额外的属性。
import numpy as np
class RealisticInfoArray(np.ndarray):
def __new__(cls, input_array, info=None):
# Input array is an already formed ndarray instance
# We first cast to be our class type
obj = np.asarray(input_array).view(cls)
# add the new attribute to the created instance
obj.info = info
# Finally, we must return the newly created object:
return obj
def __array_finalize__(self, obj):
# see InfoArray.__array_finalize__ for comments
if obj is None: return
self.info = getattr(obj, 'info', None)
所以:
>>> arr = np.arange(5)
>>> obj = RealisticInfoArray(arr, info='information')
>>> type(obj)
<class 'RealisticInfoArray'>
>>> obj.info
'information'
>>> v = obj[1:]
>>> type(v)
<class 'RealisticInfoArray'>
>>> v.info
'information'
3 __array_ufunc__
对于 ufunc
1.13 版中的新功能。
子类可以通过覆盖默认ndarray.__array_ufunc__
方法来覆盖在其上执行 numpy ufuncs 时发生的情况。执行此方法而不是ufunc 并且应该返回操作的结果,或者NotImplemented
如果请求的操作没有实现。
的签名__array_ufunc__
是:
def __array_ufunc__(ufunc, method, *inputs, **kwargs):
- *ufunc* is the ufunc object that was called.
- *method* is a string indicating how the Ufunc was called, either
``"__call__"`` to indicate it was called directly, or one of its
:ref:`methods<ufuncs.methods>`: ``"reduce"``, ``"accumulate"``,
``"reduceat"``, ``"outer"``, or ``"at"``.
- *inputs* is a tuple of the input arguments to the ``ufunc``
- *kwargs* contains any optional or keyword arguments passed to the
function. This includes any ``out`` arguments, which are always
contained in a tuple.
典型的实现将转换作为自己类实例的任何输入或输出,使用 将所有内容传递给超类 super()
,最后在可能的反向转换后返回结果。举例来说,来自测试案例采取 test_ufunc_override_with_super
在core/tests/test_umath.py
,如下。
import numpy as np
class A(np.ndarray):
def __array_ufunc__(self, ufunc, method, *inputs, out=None, **kwargs):
args = []
in_no = []
for i, input_ in enumerate(inputs):
if isinstance(input_, A):
in_no.append(i)
args.append(input_.view(np.ndarray))
else:
args.append(input_)
outputs = out
out_no = []
if outputs:
out_args = []
for j, output in enumerate(outputs):
if isinstance(output, A):
out_no.append(j)
out_args.append(output.view(np.ndarray))
else:
out_args.append(output)
kwargs['out'] = tuple(out_args)
else:
outputs = (None,) * ufunc.nout
info = {}
if in_no:
info['inputs'] = in_no
if out_no:
info['outputs'] = out_no
results = super().__array_ufunc__(ufunc, method, *args, **kwargs)
if results is NotImplemented:
return NotImplemented
if method == 'at':
if isinstance(inputs[0], A):
inputs[0].info = info
return
if ufunc.nout == 1:
results = (results,)
results = tuple((np.asarray(result).view(A)
if output is None else output)
for result, output in zip(results, outputs))
if results and isinstance(results[0], A):
results[0].info = info
return results[0] if len(results) == 1 else results
所以,这个类实际上并没有做任何有趣的事情:它只是将它自己的任何实例转换为常规 ndarray(否则,我们会得到无限递归!),并添加一个info
字典,告诉它转换了哪些输入和输出。因此,例如,
>>> a = np.arange(5.).view(A)
>>> b = np.sin(a)
>>> b.info
{'inputs': [0]}
>>> b = np.sin(np.arange(5.), out=(a,))
>>> b.info
{'outputs': [0]}
>>> a = np.arange(5.).view(A)
>>> b = np.ones(1).view(A)
>>> c = a + b
>>> c.info
{'inputs': [0, 1]}
>>> a += b
>>> a.info
{'inputs': [0, 1], 'outputs': [0]}
请注意,另一种方法是使用而不是调用。对于此示例,结果将是相同的,但如果另一个操作数也定义了 ,则会有所不同。例如,让我们假设我们评估 ,其中是另一个具有覆盖的类的实例。如果您在示例中使用as , 会注意到它具有覆盖,这意味着它无法评估结果本身。因此,它将返回NotImplemented,我们的 class也将返回 。然后,控制将传递给,它要么知道如何处理我们并产生结果,要么不知道并返回NotImplemented,从而引发.getattr(ufunc, methods)(*inputs, **kwargs)``super``__array_ufunc__``np.add(a, b)``b``B``super``ndarray.__array_ufunc__``b``A``b``TypeError
相反,如果我们用 替换我们的super
电话,我们就有效地做到了。同样, 将被调用,但现在它将 an视为另一个参数。很可能,它会知道如何处理这个问题,并将该类的一个新实例返回给我们。我们的示例类没有设置来处理这个问题,但如果,例如,要使用 重新实现,它可能是最好的方法。getattr(ufunc, method)``np.add(a.view(np.ndarray), b)``B.__array_ufunc__``ndarray``B``MaskedArray``__array_ufunc__
最后要注意的是:如果super
路由适合给定的类,使用它的好处是它有助于构建类层次结构。例如,假设我们的另一个类在其 实现中B
也使用了,并且我们创建了一个依赖于两者的类,即(为了简单起见,没有另一个 覆盖)。然后,实例上的任何 ufunc将传递给,调用将转到 ,调用将转到 ,从而允许并进行协作。super``__array_ufunc__``C``class C(A, B)``__array_ufunc__``C``A.__array_ufunc__``super``A``B.__array_ufunc__``super``B``ndarray.__array_ufunc__``A``B
__array_wrap__
对于 ufuncs 和其他函数
在 numpy 1.13 之前,ufunc 的行为只能使用__array_wrap__
和进行调整 __array_prepare__
。这两个允许更改 ufunc 的输出类型,但与 相比 __array_ufunc__
,不允许对输入进行任何更改。希望最终弃用这些,但__array_wrap__
也被其他 numpy 函数和方法使用,例如squeeze
,因此目前仍需要完整功能。
从概念上讲,__array_wrap__
“包装动作”是指允许子类设置返回值的类型并更新属性和元数据。让我们用一个例子来展示它是如何工作的。首先我们回到更简单的示例子类,但使用不同的名称和一些打印语句:
import numpy as np
class MySubClass(np.ndarray):
def __new__(cls, input_array, info=None):
obj = np.asarray(input_array).view(cls)
obj.info = info
return obj
def __array_finalize__(self, obj):
print('In __array_finalize__:')
print(' self is %s' % repr(self))
print(' obj is %s' % repr(obj))
if obj is None: return
self.info = getattr(obj, 'info', None)
def __array_wrap__(self, out_arr, context=None):
print('In __array_wrap__:')
print(' self is %s' % repr(self))
print(' arr is %s' % repr(out_arr))
# then just call the parent
return super().__array_wrap__(self, out_arr, context)
我们在新数组的一个实例上运行一个 ufunc:
>>> obj = MySubClass(np.arange(5), info='spam')
In __array_finalize__:
self is MySubClass([0, 1, 2, 3, 4])
obj is array([0, 1, 2, 3, 4])
>>> arr2 = np.arange(5)+1
>>> ret = np.add(arr2, obj)
In __array_wrap__:
self is MySubClass([0, 1, 2, 3, 4])
arr is array([1, 3, 5, 7, 9])
In __array_finalize__:
self is MySubClass([1, 3, 5, 7, 9])
obj is MySubClass([0, 1, 2, 3, 4])
>>> ret
MySubClass([1, 3, 5, 7, 9])
>>> ret.info
'spam'
请注意, ufunc ( np.add
) 调用了__array_wrap__
带有参数self
as的方法obj
,以及out_arr
作为加法的 (ndarray) 结果。反过来,默认__array_wrap__
( ndarray.__array_wrap__
) 已将结果强制转换为 class MySubClass
,并调用__array_finalize__
- 因此复制info
属性。这一切都发生在 C 级。
但是,我们可以做任何我们想做的事情:
class SillySubClass(np.ndarray):
def __array_wrap__(self, arr, context=None):
return 'I lost your data'
>>> arr1 = np.arange(5)
>>> obj = arr1.view(SillySubClass)
>>> arr2 = np.arange(5)
>>> ret = np.multiply(obj, arr2)
>>> ret
'I lost your data'
因此,通过__array_wrap__
为我们的子类定义一个特定的方法,我们可以调整 ufuncs 的输出。该__array_wrap__
方法需要self
,然后是一个参数——它是 ufunc 的结果——和一个可选的参数上下文。此参数由 ufuncs 作为 3 元素元组返回:(ufunc 的名称,ufunc 的参数,ufunc 的域),但不由其他 numpy 函数设置。虽然,如上所见,有可能以其他方式执行,但__array_wrap__
应返回其包含类的实例。有关实现,请参阅掩码数组子类。
除了__array_wrap__
在退出 ufunc 的途中调用的 之外,还有一个__array_prepare__
方法在进入 ufunc 的途中调用,在创建输出数组之后但在执行任何计算之前。默认实现除了传递数组之外什么都不做。__array_prepare__
不应尝试访问数组数据或调整数组大小,它旨在设置输出数组类型、更新属性和元数据,以及在计算开始之前根据可能需要的输入执行任何检查。像__array_wrap__
,__array_prepare__
必须返回一个 ndarray 或其子类或引发错误。
额外的问题 - 自定义__del__
方法和 ndarray.base
ndarray 解决的问题之一是跟踪 ndarray 及其视图的内存所有权。考虑我们创建了一个 ndarrayarr
并使用. 这两个对象正在查看相同的内存。NumPy 使用以下属性跟踪特定数组或视图的数据来自何处 :v = arr[1:]``base
>>> # A normal ndarray, that owns its own data
>>> arr = np.zeros((4,))
>>> # In this case, base is None
>>> arr.base is None
True
>>> # We take a view
>>> v1 = arr[1:]
>>> # base now points to the array that it derived from
>>> v1.base is arr
True
>>> # Take a view of a view
>>> v2 = v1[1:]
>>> # base points to the original array that it was derived from
>>> v2.base is arr
True
一般来说,如果数组拥有自己的内存,就arr
在这种情况下,那么arr.base
将是 None - 有一些例外 - 有关更多详细信息,请参阅 numpy book。
该base
属性有助于判断我们是否拥有视图或原始数组。如果我们需要知道在删除子类数组时是否进行一些特定的清理,这反过来会很有用。例如,如果原始数组被删除,我们可能只想做清理,而不是视图。对于如何能工作的例子,看看在memmap
上课 numpy.core
。
子类化和下游兼容性
当子类化ndarray
或创建模仿ndarray
接口的鸭子类型时,您有责任决定您的 API 与 numpy 的 API 的对齐程度。为了方便起见,具有相应的许多numpy的功能 ndarray
的方法(例如,sum
,mean
,take
,reshape
)通过检查第一个参数的函数具有相同的名称的方法工作。如果存在,则调用该方法,而不是将参数强制转换为 numpy 数组。
例如,如果您希望您的子类或鸭子类型与 numpy 的sum
函数兼容,则该对象的sum
方法的方法签名应如下所示:
def sum(self, axis=None, dtype=None, out=None, keepdims=False):
...
这是完全相同的方法签名np.sum
,所以现在如果用户调用 np.sum
这个对象,numpy将调用对象自己的sum
方法并在签名中传递上面枚举的这些参数,并且不会引发错误,因为签名完全兼容彼此。
但是,如果您决定偏离此签名并执行以下操作:
def sum(self, axis=None, dtype=None):
...
此对象不再与 兼容,np.sum
因为如果您调用np.sum
,它将传入意外的参数out
和keepdims
,从而引发 TypeError 。
如果您希望保持与 numpy 及其后续版本(可能会添加新的关键字参数)的兼容性,但又不想显示 numpy 的所有参数,则您的函数签名应接受**kwargs
. 例如:
def sum(self, axis=None, dtype=None, **unused_kwargs):
...
这个对象现在np.sum
再次兼容,因为任何无关的参数(即不是axis
或 的关键字dtype
)将隐藏在 **unused_kwargs
参数中。
更多建议: