torch.histogramdd

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

計算張量中值的多維直方圖。

將輸入張量的元素（其最內層維度的大小為 N）解釋為 N 維點的集合。將每個點對應到一組 N 維儲存格，並傳回每個儲存格中的點數（或總權重）。

input 必須是一個至少有 2 個維度的張量。如果 input 的形狀是 (M, N)，那麼它的每一列 M 都定義了 N 維空間中的一個點。如果 input 有三個或更多維度，除了最後一個維度之外的所有維度都會被展平。

每個維度都獨立地與其自身嚴格遞增的 bin 邊緣序列相關聯。Bin 邊緣可以通過傳遞一個 1D 張量的序列來顯式指定。或者，可以通過傳遞一個指定每個維度中等寬 bin 數量的整數序列來自動構建 bin 邊緣。

對於 input 中的每個 N 維點

• 它的每個坐標都會在其維度所對應的 bin 邊緣之間獨立進行分箱

  對應於其維度

• 分箱結果會被組合起來以識別 N 維 bin（如果有的話）

  該點落入的

• 如果該點落入一個 bin 中，則該 bin 的計數（或總權重）會增加

• 未落入任何 bin 中的點不會對輸出產生影響

bins 可以是 N 個 1D 張量的序列、N 個整數的序列或單個整數。

如果 bins 是一個 N 個 1D 張量的序列，它會顯式指定 N 個 bin 邊緣序列。每個 1D 張量應包含一個至少有一個元素的嚴格遞增序列。一個 K 個 bin 邊緣的序列定義了 K-1 個 bin，顯式指定了所有 bin 的左邊緣和右邊緣。每個 bin 都不包含它的左邊緣。只有最右邊的 bin 包含它的右邊緣。

如果 bins 是一個 N 個整數的序列，它會指定每個維度中等寬 bin 的數量。預設情況下，每個維度中最左邊和最右邊的 bin 邊緣由 input 張量在相應維度中的最小值和最大值決定。可以提供 range 參數來手動指定每個維度中最左邊和最右邊的 bin 邊緣。

如果 bins 是一個整數，它會指定所有維度的等寬 bin 的數量。

注意

另請參閱 torch.histogram()，它專門計算 1D 直方圖。雖然 torch.histogramdd() 從 input 的形狀推斷其 bin 和分箱值的維度，但 torch.histogram() 接受並展平任何形狀的 input。

參數

• input (Tensor) – 輸入張量。

• bins – Tensor[]、int[] 或 int。如果是 Tensor[]，則定義 bin 邊緣的序列。如果是 int[]，則定義每個維度中等寬 bin 的數量。如果是 int，則定義所有維度的等寬 bin 的數量。

關鍵字參數

• range (float 的 序列) – 定義每個維度中最左邊和最右邊的 bin 邊緣。

• weight (Tensor) – 預設情況下，input 中的每個值都具有權重 1。如果傳遞了權重張量，則 input 中的每個 N 維坐標都會將其關聯的權重貢獻給其 bin 的結果。權重張量應具有與 input 張量相同的形狀，但不包括其最內層的維度 N。

• density (bool) – 如果為 False（預設），則結果將包含每個 bin 中的計數（或總權重）。如果為 True，則每個計數（權重）都將除以總計數（總權重），然後除以其關聯 bin 的體積。

回傳值

包含直方圖值的 N 維張量。bin_edges(Tensor[]): 包含 bin 邊緣的 N 個 1D 張量的序列。

回傳類型

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