torch.histogramdd

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

Вычисляет многомерную гистограмму значений тензора.

Интерпретирует элементы входного тензора, размер последнего измерения которого равен N, как набор точек в N-мерном пространстве. Относит каждую точку к набору N-мерных бинов и возвращает количество точек (или суммарный вес) в каждом бине.

input должен быть тензором как минимум с двумя измерениями. Если входной тензор имеет форму (M, N), каждая из его M строк задаёт точку в N-мерном пространстве. Если входной тензор имеет три или более измерений, все измерения, кроме последнего, преобразуются в одномерную последовательность.

С каждым измерением независимо связывается собственная строго возрастающая последовательность границ бинов. Границы бинов можно задать явно, передав последовательность одномерных тензоров. Также границы бинов можно сформировать автоматически, передав последовательность целых чисел, задающих количество бинов одинаковой ширины в каждом измерении.

Для каждой N-мерной точки во входном тензоре:

• Каждая из её координат независимо относится к бину согласно границам бинов

  соответствующего измерения

• Результаты распределения по бинам объединяются, чтобы определить 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 (последовательность float) – Задаёт самые левые и самые правые границы бинов в каждом измерении.
• 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])))