(原型) MaskedTensor 高级语义

创建日期：2022 年 10 月 28 日 | 最后更新：2022 年 10 月 28 日 | 最后验证：未验证

在学习本教程之前，请务必查阅我们的MaskedTensor 概述教程 <https://pytorch.ac.cn/tutorials/prototype/maskedtensor_overview.html>。

本教程的目的是帮助用户理解一些高级语义的工作原理及其形成原因。我们将重点关注以下两个方面：

*. MaskedTensor 与 NumPy 的 MaskedArray 之间的区别 *. 归约语义

准备

import torch
from torch.masked import masked_tensor
import numpy as np
import warnings

# Disable prototype warnings and such
warnings.filterwarnings(action='ignore', category=UserWarning)

MaskedTensor 对比 NumPy 的 MaskedArray

NumPy 的 MaskedArray 与 MaskedTensor 有一些根本的语义差异。

*. 它们的工厂函数和基本定义反转了掩码（类似于 torch.nn.MHA）；也就是说，MaskedTensor

使用 True 表示“指定”和 False 表示“未指定”，或“有效”/“无效”，而 NumPy 则相反。我们认为我们的掩码定义不仅更直观，而且与 PyTorch 整体现有的语义更一致。

*. 交集语义。在 NumPy 中，如果两个元素中的一个被掩码掉，结果元素也将被

掩码掉——实际上，它们应用的是 逻辑或 (logical_or) 算子。

data = torch.arange(5.)
mask = torch.tensor([True, True, False, True, False])
npm0 = np.ma.masked_array(data.numpy(), (~mask).numpy())
npm1 = np.ma.masked_array(data.numpy(), (mask).numpy())

print("npm0:\n", npm0)
print("npm1:\n", npm1)
print("npm0 + npm1:\n", npm0 + npm1)

npm0:
 [0.0 1.0 -- 3.0 --]
npm1:
 [-- -- 2.0 -- 4.0]
npm0 + npm1:
 [-- -- -- -- --]

同时，MaskedTensor 不支持掩码不匹配的加法或二元算子——要理解原因，请参阅关于归约的部分。

mt0 = masked_tensor(data, mask)
mt1 = masked_tensor(data, ~mask)
print("mt0:\n", mt0)
print("mt1:\n", mt1)

try:
    mt0 + mt1
except ValueError as e:
    print ("mt0 + mt1 failed. Error: ", e)

mt0:
 MaskedTensor(
  [  0.0000,   1.0000,       --,   3.0000,       --]
)
mt1:
 MaskedTensor(
  [      --,       --,   2.0000,       --,   4.0000]
)
mt0 + mt1 failed. Error:  Input masks must match. If you need support for this, please open an issue on Github.

然而，如果需要这种行为，MaskedTensor 通过提供数据和掩码访问，并方便地使用 to_tensor() 将 MaskedTensor 转换为填充了掩码值的 Tensor 来支持这些语义。例如

t0 = mt0.to_tensor(0)
t1 = mt1.to_tensor(0)
mt2 = masked_tensor(t0 + t1, mt0.get_mask() & mt1.get_mask())

print("t0:\n", t0)
print("t1:\n", t1)
print("mt2 (t0 + t1):\n", mt2)

t0:
 tensor([0., 1., 0., 3., 0.])
t1:
 tensor([0., 0., 2., 0., 4.])
mt2 (t0 + t1):
 MaskedTensor(
  [      --,       --,       --,       --,       --]
)

注意，掩码是 mt0.get_mask() & mt1.get_mask()，因为 MaskedTensor 的掩码是 NumPy 掩码的反转。

归约语义

回想在MaskedTensor 概述教程中，我们讨论了“实现缺失的 torch.nan* 算子”。这些都是归约的例子——从 Tensor 中移除一个（或多个）维度然后聚合结果的算子。在本节中，我们将使用归约语义来阐释我们对上述掩码匹配的严格要求。

从根本上说，:class:`MaskedTensor` 执行相同的归约操作，同时忽略被掩码掉（未指定）的值。例如：

data = torch.arange(12, dtype=torch.float).reshape(3, 4)
mask = torch.randint(2, (3, 4), dtype=torch.bool)
mt = masked_tensor(data, mask)

print("data:\n", data)
print("mask:\n", mask)
print("mt:\n", mt)

data:
 tensor([[ 0.,  1.,  2.,  3.],
        [ 4.,  5.,  6.,  7.],
        [ 8.,  9., 10., 11.]])
mask:
 tensor([[False,  True, False, False],
        [False,  True, False, False],
        [False,  True, False, False]])
mt:
 MaskedTensor(
  [
    [      --,   1.0000,       --,       --],
    [      --,   5.0000,       --,       --],
    [      --,   9.0000,       --,       --]
  ]
)

现在，不同的归约（都在 dim=1 上）

print("torch.sum:\n", torch.sum(mt, 1))
print("torch.mean:\n", torch.mean(mt, 1))
print("torch.prod:\n", torch.prod(mt, 1))
print("torch.amin:\n", torch.amin(mt, 1))
print("torch.amax:\n", torch.amax(mt, 1))

torch.sum:
 MaskedTensor(
  [  1.0000,   5.0000,   9.0000]
)
torch.mean:
 MaskedTensor(
  [  1.0000,   5.0000,   9.0000]
)
torch.prod:
 MaskedTensor(
  [  1.0000,   5.0000,   9.0000]
)
torch.amin:
 MaskedTensor(
  [  1.0000,   5.0000,   9.0000]
)
torch.amax:
 MaskedTensor(
  [  1.0000,   5.0000,   9.0000]
)

值得注意的是，被掩码掉的元素下的值不保证有任何特定值，特别是当行或列完全被掩码掉时（标准化也是如此）。有关掩码语义的更多详细信息，请参阅此RFC。

现在，我们可以回顾这个问题：为什么我们强制要求二元算子的掩码必须匹配这一不变性？换句话说，为什么我们不像 np.ma.masked_array 那样使用相同的语义？考虑以下示例

data0 = torch.arange(10.).reshape(2, 5)
data1 = torch.arange(10.).reshape(2, 5) + 10
mask0 = torch.tensor([[True, True, False, False, False], [False, False, False, True, True]])
mask1 = torch.tensor([[False, False, False, True, True], [True, True, False, False, False]])
npm0 = np.ma.masked_array(data0.numpy(), (mask0).numpy())
npm1 = np.ma.masked_array(data1.numpy(), (mask1).numpy())

print("npm0:", npm0)
print("npm1:", npm1)

npm0: [[-- -- 2.0 3.0 4.0]
 [5.0 6.0 7.0 -- --]]
npm1: [[10.0 11.0 12.0 -- --]
 [-- -- 17.0 18.0 19.0]]

现在，我们尝试加法

print("(npm0 + npm1).sum(0):\n", (npm0 + npm1).sum(0))
print("npm0.sum(0) + npm1.sum(0):\n", npm0.sum(0) + npm1.sum(0))

(npm0 + npm1).sum(0):
 [-- -- 38.0 -- --]
npm0.sum(0) + npm1.sum(0):
 [15.0 17.0 38.0 21.0 23.0]

求和和加法显然应该是可结合的，但使用 NumPy 的语义时却不是，这无疑会让用户感到困惑。

另一方面，MaskedTensor 则根本不允许这种操作，因为 mask0 != mask1。话虽如此，如果用户愿意，也有绕过此限制的方法（例如，使用 to_tensor() 将 MaskedTensor 中未定义的元素填充为 0 值，如下所示），但此时用户必须更明确地表达他们的意图。

mt0 = masked_tensor(data0, ~mask0)
mt1 = masked_tensor(data1, ~mask1)

(mt0.to_tensor(0) + mt1.to_tensor(0)).sum(0)

tensor([15., 17., 38., 21., 23.])

结论

在本教程中，我们了解了 MaskedTensor 与 NumPy 的 MaskedArray 背后的不同设计决策，以及归约语义。总的来说，MaskedTensor 的设计旨在避免歧义和令人困惑的语义（例如，我们尽量保持二元操作的可结合性），这有时可能需要用户在编写代码时更加明确，但我们认为这是一个更好的方向。如果您对此有任何想法，请告知我们！