The numpy.ma 模块#
理由#
掩码数组是可能包含缺失或无效条目的数组.:mod:numpy.ma 模块提供了一个几乎与 numpy 兼容的替代品,支持带掩码的数据数组.
什么是掩码数组?#
在许多情况下,数据集可能是不完整的或因存在无效数据而被污染.例如,传感器可能未能记录数据,或记录了无效值.:mod:numpy.ma 模块通过引入掩码数组提供了一种便捷的解决方法.
掩码数组是标准 numpy.ndarray 和一个掩码的组合.掩码要么是 nomask,表示关联数组中没有值是无效的,要么是一个布尔数组,用于确定关联数组的每个元素是否有效.当掩码的一个元素为 False 时,关联数组的相应元素是有效的,并且被称为未掩码.当掩码的一个元素为 True 时,关联数组的相应元素被称为掩码（无效）.
该包确保在计算中不使用掩码条目.
作为一个例子,让我们考虑以下数据集:
>>> import numpy as np >>> import numpy.ma as ma >>> x = np.array([1, 2, 3, -1, 5])我们希望将第四个条目标记为无效.最简单的方法是创建一个掩码数组:
>>> mx = ma.masked_array(x, mask=[0, 0, 0, 1, 0])我们现在可以计算数据集的平均值,而不考虑无效数据:
>>> mx.mean() 2.75
The numpy.ma 模块#
The main feature of the numpy.ma module is the MaskedArray
class, which is a subclass of numpy.ndarray. The class, its
attributes and methods are described in more details in the
MaskedArray class section.
>>> import numpy as np >>> import numpy.ma as ma要创建一个第二个元素无效的数组,我们会这样做:
>>> y = ma.array([1, 2, 3], mask = [0, 1, 0])要创建一个掩码数组,其中所有接近 1.e20 的值都是无效的,我们会这样做:
>>> z = ma.masked_values([1.0, 1.e20, 3.0, 4.0], 1.e20)
关于掩码数组的创建方法的完整讨论,请参见章节 构建掩码数组.
使用 numpy.ma#
构建掩码数组#
有几种方法可以构造一个掩码数组.
第一种可能性是直接调用
MaskedArray类.第二种可能性是使用两个掩码数组构造函数,:func:
array和masked_array.array(data[, dtype, copy, order, mask, ...])一个可能包含掩码值的数组类.
MaskedArray的别名第三个选项是采用现有数组的视图.在这种情况下,如果数组没有命名字段,视图的掩码将设置为
nomask,否则将设置为与数组结构相同的布尔数组.>>> import numpy as np >>> x = np.array([1, 2, 3]) >>> x.view(ma.MaskedArray) masked_array(data=[1, 2, 3], mask=False, fill_value=999999) >>> x = np.array([(1, 1.), (2, 2.)], dtype=[('a',int), ('b', float)]) >>> x.view(ma.MaskedArray) masked_array(data=[(1, 1.0), (2, 2.0)], mask=[(False, False), (False, False)], fill_value=(999999, 1e+20), dtype=[('a', '<i8'), ('b', '<f8')])
另一种可能性是使用以下任何函数:
asarray(a[, dtype, order])将输入转换为给定数据类型的掩码数组.
asanyarray(a[, dtype])将输入转换为掩码数组,保留子类.
fix_invalid(a[, mask, copy, fill_value])返回输入数据中无效数据被屏蔽并替换为填充值.
masked_equal(x, value[, copy])屏蔽等于给定值的数组.
masked_greater(x, value[, copy])掩码数组中大于给定值的部分.
masked_greater_equal(x, value[, copy])掩码数组中大于或等于给定值的部分.
masked_inside(x, v1, v2[, copy])在给定区间内掩码一个数组.
masked_invalid(a[, copy])屏蔽一个数组,其中出现无效值（NaNs 或 infs）.
masked_less(x, value[, copy])掩码数组中给定值以下的部分.
masked_less_equal(x, value[, copy])掩码数组中小于或等于给定值的部分.
masked_not_equal(x, value[, copy])掩码数组,其中 不 等于给定值.
masked_object(x, value[, copy, shrink])在数组 x 中,将数据完全等于该值的位置进行掩码.
masked_outside(x, v1, v2[, copy])在给定区间外屏蔽数组.
masked_values(x, value[, rtol, atol, copy, ...])使用浮点数相等性进行掩码.
masked_where(condition, a[, copy])在满足条件的情况下屏蔽数组.
访问数据#
掩码数组的底层数据可以通过几种方式访问:
通过
data属性.输出是数组的一个视图,作为numpy.ndarray或其子类之一,具体取决于掩码数组创建时底层数据的类型.通过
__array__方法.输出是一个numpy.ndarray.通过直接将掩码数组视为
numpy.ndarray或其子类（这实际上是使用data属性所做的）.通过使用
getdata函数.
如果某些条目已被标记为无效,这些方法中没有一个能完全令人满意.一般来说,如果需要在没有掩码条目的情况下表示数组,建议使用 filled 方法填充数组.
访问掩码#
掩码数组的掩码可以通过其 mask 属性访问.我们必须记住,掩码中的 True 条目表示*无效*数据.
另一种可能性是使用 getmask 和 getmaskarray 函数.``getmask(x)`` 如果 x 是一个掩码数组,则输出 x 的掩码,否则输出特殊值 nomask.``getmaskarray(x)`` 如果 x 是一个掩码数组,则输出 x 的掩码.如果 x 没有无效条目或不是一个掩码数组,该函数输出一个与 x 元素数量相同的 False 布尔数组.
仅访问有效条目#
要仅检索有效条目,我们可以使用掩码的反向作为索引.掩码的反向可以通过 numpy.logical_not 函数或简单地通过 ~ 运算符计算:
>>> import numpy as np >>> x = ma.array([[1, 2], [3, 4]], mask=[[0, 1], [1, 0]]) >>> x[~x.mask] masked_array(data=[1, 4], mask=[False, False], fill_value=999999)另一种获取有效数据的方法是使用
compressed方法,该方法返回一个一维的ndarray（或其子类之一,取决于baseclass属性的值）:>>> x.compressed() array([1, 4])注意,:meth:
compressed的输出总是1D.
修改掩码#
屏蔽一个条目#
推荐将掩码数组的一个或多个特定条目标记为无效的方法是将特殊值 masked 赋值给他们:
>>> x = ma.array([1, 2, 3])
>>> x[0] = ma.masked
>>> x
masked_array(data=[--, 2, 3],
mask=[ True, False, False],
fill_value=999999)
>>> y = ma.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> y[(0, 1, 2), (1, 2, 0)] = ma.masked
>>> y
masked_array(
data=[[1, --, 3],
[4, 5, --],
[--, 8, 9]],
mask=[[False, True, False],
[False, False, True],
[ True, False, False]],
fill_value=999999)
>>> z = ma.array([1, 2, 3, 4])
>>> z[:-2] = ma.masked
>>> z
masked_array(data=[--, --, 3, 4],
mask=[ True, True, False, False],
fill_value=999999)
第二种可能性是直接修改 mask ,但这种用法不推荐.
备注
当创建一个具有简单、非结构化数据类型的新掩码数组时,掩码最初设置为特殊值 nomask,这大致对应于布尔值 False.尝试设置 nomask 的元素将失败,并出现 TypeError 异常,因为布尔值不支持项目赋值.
可以通过将 True 赋值给掩码来一次性屏蔽数组的所有条目:
>>> import numpy.ma as ma >>> x = ma.array([1, 2, 3], mask=[0, 0, 1]) >>> x.mask = True >>> x masked_array(data=[--, --, --], mask=[ True, True, True], fill_value=999999, dtype=int64)最后,通过将掩码分配给布尔序列,可以屏蔽和/或取消屏蔽特定条目:
>>> x = ma.array([1, 2, 3]) >>> x.mask = [0, 1, 0] >>> x masked_array(data=[1, --, 3], mask=[False, True, False], fill_value=999999)
揭露一个条目#
要解开一个或几个特定条目,我们可以直接给它们分配一个或几个新的有效值:
>>> import numpy.ma as ma
>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])
>>> x
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x[-1] = 5
>>> x
masked_array(data=[1, 2, 5],
mask=[False, False, False],
fill_value=999999)
备注
通过直接赋值来取消屏蔽一个条目会静默失败,如果掩码数组有一个 硬 掩码,如 hardmask 属性所示.这个特性是为了防止覆盖掩码而引入的.要强制取消屏蔽一个条目,而数组有一个硬掩码,必须首先使用 soften_mask 方法软化掩码,然后再进行赋值.之后可以用 harden_mask 重新硬化掩码,如下所示:
>>> import numpy.ma as ma
>>> x = ma.array([1, 2, 3], mask=[0, 0, 1], hard_mask=True)
>>> x
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x[-1] = 5
>>> x
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x.soften_mask()
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x[-1] = 5
>>> x
masked_array(data=[1, 2, 5],
mask=[False, False, False],
fill_value=999999)
>>> x.harden_mask()
masked_array(data=[1, 2, 5],
mask=[False, False, False],
fill_value=999999)
要解开掩码数组的所有掩码条目（前提是掩码不是硬掩码）,最简单的解决方案是将常量 nomask 赋值给掩码:
>>> import numpy.ma as ma
>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])
>>> x
masked_array(data=[1, 2, --],
mask=[False, False, True],
fill_value=999999)
>>> x.mask = ma.nomask
>>> x
masked_array(data=[1, 2, 3],
mask=[False, False, False],
fill_value=999999)
索引和切片#
作为一个 MaskedArray 是 numpy.ndarray 的子类,它继承了其索引和切片机制.
当访问一个没有命名字段的掩码数组的单个条目时,输出要么是一个标量（如果掩码的相应条目是 False）,要么是特殊值 masked`（如果掩码的相应条目是 ``True`）:
>>> import numpy.ma as ma
>>> x = ma.array([1, 2, 3], mask=[0, 0, 1])
>>> x[0]
1
>>> x[-1]
masked
>>> x[-1] is ma.masked
True
如果掩码数组有命名字段,访问单个条目会返回一个 numpy.void 对象,如果没有任何字段被掩码,或者返回一个与初始数组具有相同数据类型的 0d 掩码数组,如果至少有一个字段被掩码.
>>> import numpy.ma as ma
>>> y = ma.masked_array([(1,2), (3, 4)],
... mask=[(0, 0), (0, 1)],
... dtype=[('a', int), ('b', int)])
>>> y[0]
(1, 2)
>>> y[-1]
(3, --)
当访问一个切片时,输出是一个掩码数组,其 data 属性是原始数据的视图,而其掩码要么是 :attr:`nomask`（如果原始数组中没有无效条目）,要么是原始掩码相应切片的视图.视图是必需的,以确保对掩码的任何修改都能传播到原始数据.
>>> import numpy.ma as ma
>>> x = ma.array([1, 2, 3, 4, 5], mask=[0, 1, 0, 0, 1])
>>> mx = x[:3]
>>> mx
masked_array(data=[1, --, 3],
mask=[False, True, False],
fill_value=999999)
>>> mx[1] = -1
>>> mx
masked_array(data=[1, -1, 3],
mask=[False, False, False],
fill_value=999999)
>>> x.mask
array([False, False, False, False, True])
>>> x.data
array([ 1, -1, 3, 4, 5])
访问具有结构化数据类型的掩码数组的字段会返回一个 MaskedArray.
掩码数组的操作#
掩码数组支持算术和比较操作.尽可能地,掩码数组的无效条目不会被处理,这意味着相应的 data 条目 应该 在操作前后保持不变.
警告
我们需要强调的是,这种行为可能不是系统性的,在某些情况下,屏蔽的数据可能会受到影响,因此用户不应依赖这些数据保持不变.
numpy.ma 模块带有大多数 ufuncs 的特定实现.具有有效域的一元和二元函数（如 log 或 divide）在输入被掩码或超出有效域时返回 masked 常量:
>>> import numpy.ma as ma
>>> ma.log([-1, 0, 1, 2])
masked_array(data=[--, --, 0.0, 0.6931471805599453],
mask=[ True, True, False, False],
fill_value=1e+20)
掩码数组也支持标准的 numpy ufuncs.输出结果是一个掩码数组.一元 ufunc 的结果在输入被掩码的地方被掩码.二元 ufunc 的结果在任意输入被掩码的地方被掩码.如果 ufunc 还返回可选的上下文输出（包含 ufunc 名称、其参数和其域的 3 元素元组）,上下文会被处理,并且输出掩码数组的条目在相应输入落在有效域之外的地方被掩码:
>>> import numpy.ma as ma
>>> x = ma.array([-1, 1, 0, 2, 3], mask=[0, 0, 0, 0, 1])
>>> np.log(x)
masked_array(data=[--, 0.0, --, 0.6931471805599453, --],
mask=[ True, False, True, False, True],
fill_value=1e+20)
示例#
具有给定值表示缺失数据的值#
让我们考虑一个元素列表 x,其中值 -9999. 表示缺失数据.我们希望计算数据的平均值和异常向量（与平均值的偏差）:
>>> import numpy.ma as ma
>>> x = [0.,1.,-9999.,3.,4.]
>>> mx = ma.masked_values (x, -9999.)
>>> print(mx.mean())
2.0
>>> print(mx - mx.mean())
[-2.0 -1.0 -- 1.0 2.0]
>>> print(mx.anom())
[-2.0 -1.0 -- 1.0 2.0]
填补缺失的数据#
假设我们现在希望打印相同的数据,但用平均值替换缺失值.
>>> import numpy.ma as ma
>>> mx = ma.masked_values (x, -9999.)
>>> print(mx.filled(mx.mean()))
[0. 1. 2. 3. 4.]
数值运算#
数值运算可以轻松执行,而无需担心缺失值、除以零、负数的平方根等问题.:
>>> import numpy.ma as ma
>>> x = ma.array([1., -1., 3., 4., 5., 6.], mask=[0,0,0,0,1,0])
>>> y = ma.array([1., 2., 0., 4., 5., 6.], mask=[0,0,0,0,0,1])
>>> print(ma.sqrt(x/y))
[1.0 -- -- 1.0 -- --]
输出的四个值是无效的:第一个来自对负数取平方根,第二个来自除以零,最后两个值在输入被掩码的情况下.
忽略极端值#
让我们考虑一个介于0和1之间的浮点数数组 d.我们希望计算 d 的值的平均值,同时忽略范围 [0.2, 0.9] 之外的任何数据:
>>> import numpy as np
>>> import numpy.ma as ma
>>> d = np.linspace(0, 1, 20)
>>> print(d.mean() - ma.masked_outside(d, 0.2, 0.9).mean())
-0.05263157894736836