numpy.ma 模块#

基本原理#

掩码数组是可以包含缺失或无效条目的数组。 numpy.ma 模块提供了 numpy 的一个几乎完全兼容的替代方案,支持带有掩码的数据数组。

什么是掩码数组?#

在许多情况下,数据集可能不完整或由于无效数据的存在而受到污染。例如,传感器可能无法记录数据,或者记录了无效值。 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

numpy.ma 模块#

numpy.ma 模块的主要功能是 MaskedArray 类,它是 numpy.ndarray 的子类。该类及其属性和方法在 MaskedArray 类 部分进行了更详细的描述。

numpy.ma 模块可以用作 numpy 的补充

>>> 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 类。

  • 第二种可能性是使用两个掩码数组构造函数,arraymasked_array

    array(data[, dtype, copy, order, mask, ...])

    一个可能包含掩码值的数组类。

    masked_array

    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])

    掩码出现无效值的数组(NaN 或 inf)。

    masked_less(x, value[, copy])

    掩码小于给定值的数组。

    masked_less_equal(x, value[, copy])

    掩码小于或等于给定值的数组。

    masked_not_equal(x, value[, copy])

    掩码等于给定值的数组。

    masked_object(x, value[, copy, shrink])

    掩码数组 x,其中数据完全等于 value。

    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 条目表示无效数据。

另一种可能性是使用 getmaskgetmaskarray 函数。 getmask(x) 如果 x 是掩码数组,则输出 x 的掩码,否则输出特殊值 nomaskgetmaskarray(x) 如果 x 是掩码数组,则输出 x 的掩码。如果 x 没有无效条目或不是掩码数组,则该函数输出一个布尔值数组 False,其元素数量与 x 相同。

仅访问有效条目#

要仅检索有效条目,我们可以使用掩码的反向作为索引。可以使用 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])

请注意,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)

索引和切片#

由于MaskedArraynumpy.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对象(如果没有任何字段被掩盖),或者返回与初始数组具有相同dtype的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属性是原始数据的视图,其掩码要么是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模块附带了大多数ufunc的特定实现。具有有效域(如logdivide)的一元和二元函数在输入被掩盖或超出有效域时返回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 ufunc。输出将是一个掩码数组。一元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 -- --]

输出的四个值无效:第一个来自取负数的平方根,第二个来自除以零,最后两个来自输入被掩盖。

忽略极值#

让我们考虑一个浮点数数组d,其值介于0和1之间。我们希望计算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