torch.histogramdd

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

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

将最内层维度大小为 N 的输入张量的元素解释为 N 维点的集合。将每个点映射到一组 N 维 bin 中，并返回每个 bin 中点的数量（或总权重）。

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

每个维度都独立地与其自身的严格递增的 bin 边缘序列相关联。bin 边缘可以通过传递 1D 张量序列来显式指定。或者，bin 边缘可以通过传递指定每个维度中等宽 bin 数量的整数序列来自动构建。

对于输入中的每个 N 维点

• 其每个坐标都在与其维度对应的 bin 边缘之间独立分箱

  与其维度对应的

• 分箱结果被组合以识别点落入的 N 维 bin（如果有）

  点落入的 bin

• 如果点落入 bin，则 bin 的计数（或总权重）会递增

• 未落入任何 bin 的点不会对输出做出贡献

bins 可以是 N 个 1D 张量的序列、N 个整数的序列或单个整数。

如果 bins 是 N 个 1D 张量的序列，则它显式指定 bin 边缘的 N 个序列。每个 1D 张量应包含至少一个元素的严格递增序列。K 个 bin 边缘的序列定义 K-1 个 bin，显式指定所有 bin 的左右边缘。每个 bin 都不包括其左边缘。只有最右边的 bin 包括其右边缘。

如果 bins 是 N 个整数的序列，则它指定每个维度中等宽 bin 的数量。默认情况下，每个维度中最左边和最右边的 bin 边缘由输入张量在相应维度中的最小和最大元素确定。range 参数可以提供以手动指定每个维度中最左边和最右边的 bin 边缘。

如果 bins 是一个整数，则它为所有维度指定等宽 bin 的数量。

注意

另请参阅 torch.histogram()，它专门计算一维直方图。虽然 torch.histogramdd() 从 input 的形状推断其 bin 和分箱值的维度，但 torch.histogram() 接受并展平任何形状的 input。

参数

• input (张量) – 输入张量。

• bins – Tensor[]、int[] 或 int。如果为 Tensor[]，则定义 bin 边缘的序列。如果为 int[]，则定义每个维度中等宽 bin 的数量。如果为 int，则为所有维度定义等宽 bin 的数量。

关键字参数

• range (float 序列) – 定义每个维度中最左边和最右边的 bin 边缘。

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

• density (bool) – 如果为 False（默认），则结果将包含每个 bin 中的计数（或总权重）。如果为 True，则每个计数（权重）除以总计数（总权重），然后除以其关联 bin 的体积。

返回

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

返回类型

hist (张量)

示例：

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