torch.histc(): Computes the Histogram of a Tensor

The torch.histc() method calculates the histogram of an input tensor by counting occurrences of values in equally spaced bins over a specified range.

Let me simplify this. Imagine you have a test subject’s scores and you want to see how often different ranges of values appear. That’s where a histogram comes into the picture!

First, it creates ranges based on the number of bins, and then, based on the score, how many ranges are frequently occurring.

The .histc() method is optimized for uniform binning and ignores values outside the [min, max] range.

The output is a tensor that contains the frequency of values falling within each bin.

Syntax

torch.histc(input, bins=100, min=0, max=0, out=None)

Parameters

Argument	Description
input (Tensor)	It represents a 1D tensor that is about to be histogrammed. It must be of the type float.
bins (int, optional)	It defines the number of histogram bins. By default, its value is 100.
min (float, optional)	It states the lower bound of the histogram range. The default value is 0.
max (float, optional)	It is the upper bound of the histogram range. The default is 0.0 If min == max, the range will be the input tensor’s minimum and maximum values.
out (Tensor, optional)	It is an output tensor to store the histogram results. By default, its value is None.  But if you have a pre-allocated tensor, it will be very helpful to you!

Simple histogram

Let’s say we have a 1D tensor of students’ test scores. We will create five bins with a range from 50 to 100.

import torch

scores = torch.tensor([55., 60., 65., 70., 75., 80., 85., 95.])

hist = torch.histc(scores, bins=5, min=50, max=100)

print(hist)

# Output: tensor([1., 2., 2., 2., 1.])

Here, we have created five bins, whose ranges are these:

• Between 50 and 60

• Between 60 and 70

• Between 70 and 80

• Between 80 and 90

• Between 90 and 100

Here is the short and complete explanation for the output tensor:

Bin 1: Between 50 and 60

1. Range: [50, 60) — includes 50, but not 60
2. Values: 55.0
3. Count = 1

Bin 2: Between 60 and 70

1. Range: [60, 70)
2. Values: 60.0, 65.0
3. Count = 2

Bin 3: Between 70 and 80

1. Range: [70, 80)
2. Values: 70.0, 75.0
3. Count = 2

Bin 4: Between 80 and 90

1. Range: [80, 90)
2. Values: 80.0, 85.0
3. Count = 2

Bin 5: Between 90 and 100

1. Range: [90, 100] — this bin includes both 90 and 100
2. Values: 95.0
3. Count = 1

Hence, we obtain the output tensor with values 1, 2, 2, 2, 1.

Automatic range

What if your min and max range is 0.0? How will it decide then? It automatically determines the input tensor’s minimum and maximum values.

import torch

tensor = torch.tensor([1.0, 2.0, 3.0, 4.0, 5.0])

hist = torch.histc(tensor, bins=3, min=0.0, max=0.0)

print(hist)

# Output: tensor([2., 1., 2.])

So, based on the input tensor’s value, it created three bins. The bins are [1.0, 2.33), [2.33, 3.67), [3.67, 5.0]. Values are distributed accordingly. And based on that, it returns the frequency of each bin.

Values outside the range

If the values reside outside the [min, max] range, they will be excluded.

import torch

data = torch.tensor([0.0, 1.0, 6.0, 3.0])

hist = torch.histc(data, bins=3, min=1.0, max=4.0)

print(hist)

# Output: tensor([1., 0., 1.])

In this code, the range [1.0, 4.0] is divided into 3 bins: [1.0, 2.0), [2.0, 3.0), [3.0, 4.0). Only 1.0 and 3.0 fall within the range; 0.0 and 6.0 are excluded.

Empty tensor

What if the input tensor is empty? In this case, it will return a tensor filled with 0s.

import torch

empty_tensor = torch.tensor([])

hist = torch.histc(empty_tensor, bins=3)

print(f"Empty tensor histogram: {hist}")

# Output: Empty tensor histogram: tensor([0., 0., 0.])

In this code, there are 3 bins, so the output contains 3 zeros.

Single value tensor

import torch

single_val = torch.tensor([2.5])

hist = torch.histc(single_val, bins=3)

print(f"Single value histogram: {hist}")

# Output: Single value histogram: tensor([0., 1., 0.])

Since there is only one value, min = 2.5, max = 2.5 (since there’s only one value). 

If min == max, PyTorch treats the entire range as a single point, and all values go into the single bin. In the output, that bin is second, but it can also be the first bin, depending on the system you are running.

Identical values

What if the input tensor contains the identical values?

import torch

identical = torch.tensor([3.0, 3.0, 3.0, 3.0, 3.0])

hist = torch.histc(identical, bins=5, min=2.0, max=4.0)

print(f"Identical values histogram: {hist}")

# Output: Identical values histogram: tensor([0., 0., 5., 0., 0.])

Since 3.0 lies within the third bin (index 2): 2.8 ≤ 3.0 < 3.2

All 5 values fall into this bin, so the histogram looks like: tensor([0., 0., 5., 0., 0.]).

That’s all!