torch.histogramdd

torch.histogramdd(input, bins, *, range=None, weight=None, density=False, out=None) -> (Tensor, Tensor[])

计算张量值的多维直方图。

将输入张量的元素视为一组N维点,这些点位于最内层维度大小为N的空间中。然后将每个点映射到一组N维单元格,并返回每个单元格中的点数(或总权重)。

input 必须是一个至少二维的张量。如果 input 的形状为 (M, N),则其 M 行中的每一行定义了一个 N 维空间中的点。如果 input 具有三个或更多维度,则除了最后一个维度之外的所有维度都将被展平。

每一维都独立地与其自身的严格递增的箱边缘序列相关联。箱边缘可以显式指定为一维张量序列,或者通过传递一系列表示每个维度中等宽箱子数量的整数来自动构建。

对于输入中的每一个N维点:
  • 其每个坐标都独立地在 bin 边界上进行离散化

    与其维度对应的

  • 量化结果被结合起来识别N维的箱(如果存在)

    该点所在的区域

  • 如果点落在某个区间内,该区间的计数(或总权重)将会增加

  • 没有落入任何区间的点不会影响输出结果

bins 可以是包含 N 个一维张量的列表,N 个整数的列表,或单一的整数。

如果 bins 是一个包含 N 个一维张量的序列,它明确指定了 N 个区间的边缘。每个一维张量应包含至少一个元素,并且是严格递增的序列。K 个区间边缘定义了 K-1 个区间,并明确了所有区间的左右边界。每个区间都是左开右闭的,只有最右边的区间是左开右闭中的右闭。

如果 bins 是一个包含 N 个整数的序列,它指定了每个维度中等宽区间的数量。默认情况下,每个维度中的最左和最右区间边界由输入张量在相应维度中的最小值和最大值确定。也可以通过提供 range 参数来手动指定每个维度中最左和最右的区间边界。

如果 bins 是一个整数,它表示所有维度上的等宽区间的数量。

注意

另请参阅torch.histogram(),该函数专门用于计算一维直方图。虽然torch.histogramdd()input 的形状推断桶的维度和分桶值的维度,而torch.histogram() 可以接受任何形状的input 并将其展平。

参数
  • input (Tensor) – 需要输入的张量。

  • bins – Tensor[]、int[] 或 int。若为 Tensor[],则表示分箱边界的序列;若为 int[],则表示每个维度上的等宽分箱数量;若为 int,则表示所有维度上等宽分箱的总数。

关键字参数
  • range (序列中的浮点数) – 定义每个维度中左边界和右边界的柱状图范围。

  • weight (Tensor) – 默认情况下,输入中的每个值的权重为 1。如果传递了权重张量,则输入中的每个 N 维坐标会将其关联的权重贡献给其所在箱的结果。权重张量应与 input 张量具有相同的形状,但不包括最内层维度 N。

  • density (bool) – 如果为 False(默认值),结果将包含每个区间内的计数或总权重。如果为 True,每个计数值或权重会先除以总的计数和总权重,然后再除以其所在区间的体积。

返回值

N维张量,包含直方图的值。bin_edges(Tensor[]):包含直方图边界的N个一维张量序列。

返回类型

hist (Tensor)

示例:
>>> torch.histogramdd(torch.tensor([[0., 1.], [1., 0.], [2., 0.], [2., 2.]]), bins=[3, 3],
...                   weight=torch.tensor([1., 2., 4., 8.]))
    torch.return_types.histogramdd(
        hist=tensor([[0., 1., 0.],
                     [2., 0., 0.],
                     [4., 0., 8.]]),
        bin_edges=(tensor([0.0000, 0.6667, 1.3333, 2.0000]),
                   tensor([0.0000, 0.6667, 1.3333, 2.0000])))
>>> torch.histogramdd(torch.tensor([[0., 0.], [1., 1.], [2., 2.]]), bins=[2, 2],
...                   range=[0., 1., 0., 1.], density=True)
    torch.return_types.histogramdd(
       hist=tensor([[2., 0.],
                    [0., 2.]]),
       bin_edges=(tensor([0.0000, 0.5000, 1.0000]),
                  tensor([0.0000, 0.5000, 1.0000])))
本页目录