NumPy bincount(): Count Occurrences of Integer Values

What Is numpy.bincount()? 🔝

The NumPy bincount() function counts how many times each non-negative integer occurs in a one-dimensional array.

The index of each value in the output array represents the integer being counted. The value stored at that index represents how many times that integer appears in the input.

For example:

import numpy as np

my_array=np.array(
    [0, 2, 2, 6, 5]
)

result=np.bincount(my_array)

print(result)

[1 0 2 0 0 1 1]

The result tells us:

• 0 occurs 1 time.
• 1 occurs 0 times.
• 2 occurs 2 times.
• 3 occurs 0 times.
• 4 occurs 0 times.
• 5 occurs 1 time.
• 6 occurs 1 time.

Syntax of bincount() 🔝

np.bincount(
    x,
    weights=None,
    minlength=0
)

Without weights, the returned array contains integer counts.

When weights is supplied, the returned array contains the sum of weights for each integer value rather than simple occurrence counts.

Basic bincount() Example 🔝

import numpy as np

my_array=np.array(
    [0, 2, 2, 6, 5]
)

result=np.bincount(my_array)

print(result)

[1 0 2 0 0 1 1]

The largest value in the input is 6, so the returned array contains positions for integers from 0 through 6.

Size of the Output Array 🔝

By default, the output must contain one position for every integer from 0 through the largest value in the input.

Therefore, for a non-empty input array:

output length = maximum input value + 1

For example:

import numpy as np

my_array=np.array(
    [2, 4, 4, 5]
)

result=np.bincount(my_array)

print(result)
print(len(result))

[0 0 1 0 2 1]
6

The largest input value is 5, so the output has 6 elements.

Missing Integer Values 🔝

If an integer between 0 and the maximum value does not occur in the input, its count is 0.

import numpy as np

my_array=np.array(
    [1, 1, 3, 5]
)

result=np.bincount(my_array)

print(result)

[0 2 0 1 0 1]

Here:

• 0 is missing, so its count is 0.
• 1 occurs twice.
• 2 is missing.
• 3 occurs once.
• 4 is missing.
• 5 occurs once.

Using minlength 🔝

The optional minlength argument sets the minimum length of the returned array.

import numpy as np

my_array=np.array(
    [0, 1, 1, 2]
)

result=np.bincount(
    my_array,
    minlength=6
)

print(result)

[1 2 1 0 0 0]

The highest input value is only 2, but minlength=6 ensures that the result contains at least six elements.

Extra positions are filled with zeros.

minlength Smaller Than Required

my_array=np.array(
    [0, 5]
)

result=np.bincount(
    my_array,
    minlength=3
)

print(result)

[1 0 0 0 0 1]

Because the value 5 is present, the result still needs six positions.

Using weights with bincount() 🔝

The weights argument changes the meaning of the result.

Instead of counting each occurrence as 1, NumPy adds the corresponding weight for each value.

import numpy as np

values=np.array(
    [0, 2, 2, 6, 5]
)

weights=np.array(
    [2, 2, 1, 3, 4]
)

result=np.bincount(
    values,
    weights=weights
)

print(result)

[2. 0. 3. 0. 0. 4. 3.]

How Weighted bincount() Works 🔝

Consider the two arrays:

values  = [0, 2, 2, 6, 5]

weights = [2, 2, 1, 3, 4]

For integer value 2, there are two corresponding weights:

2 + 1 = 3

Therefore, position 2 in the output contains 3.0.

The other weighted values are:

• value 0 receives weight 2;
• value 5 receives weight 4;
• value 6 receives weight 3.

This produces:

[2. 0. 3. 0. 0. 4. 3.]

Another Weighted Example

import numpy as np

values=np.array(
    [0, 3, 3, 5]
)

weights=np.array(
    [2, 1, 4, 6]
)

result=np.bincount(
    values,
    weights=weights
)

print(result)

[2. 0. 0. 5. 0. 6.]

The value 3 occurs twice. Its corresponding weights are 1 and 4, so:

1 + 4 = 5

Using bincount() with an Empty Array 🔝

An empty integer array returns an empty result when no minimum length is requested.

import numpy as np

my_array=np.array(
    [],
    dtype=int
)

result=np.bincount(my_array)

print(result)

[]

Empty Array with minlength

result=np.bincount(
    my_array,
    minlength=4
)

print(result)

[0 0 0 0]

Common Errors and Limitations 🔝

1. Negative Values Are Not Allowed

The input values must be non-negative integers.

import numpy as np

my_array=np.array(
    [1, -1, 2]
)

np.bincount(my_array)

This raises an error because -1 cannot be used as a bin index.

2. Floating-Point Input Is Not Accepted as Integer Bins

bincount() is designed for integer values.

my_array=np.array(
    [1.0, 2.0, 2.0]
)

np.bincount(my_array)

Use an integer array when the values represent integer categories or bin numbers.

3. Input Must Be One-Dimensional

A two-dimensional array cannot be passed directly to bincount().

my_array=np.array(
    [
        [1, 2],
        [2, 3]
    ]
)

np.bincount(my_array)

If appropriate for the task, flatten the array first:

result=np.bincount(
    my_array.ravel()
)

print(result)

[0 1 2 1]

4. weights Must Match the Input Length

Each value in the input array must have a corresponding weight.

Therefore, these arrays should have the same number of elements:

values  = [0, 2, 2]
weights = [5, 10, 20]

Summary of numpy.bincount() 🔝

• numpy.bincount() counts occurrences of non-negative integer values.
• The input must be a one-dimensional integer array.
• The output index represents the integer value being counted.
• The value stored at each output index represents its frequency.
• Missing integers receive a count of 0.
• For a non-empty array, the default output length is based on the largest input value plus one.
• minlength can request a minimum output size.
• weights changes the operation from simple counting to summing weights for each integer value.
• The weights array must correspond element-by-element with the input array.
• Negative integer values are not supported.
• Floating-point values cannot be used directly as integer bins.
• A multidimensional array should be converted to one dimension first when flattening is appropriate for the calculation.

Subhendu Mohapatra

Author & Instructor at plus2net

I write and maintain practical tutorials on Python, PHP, SQL, JavaScript, HTML, jQuery, and web development at plus2net. The tutorials focus on clear explanations, working examples, and code that readers can test and adapt while learning.

About the author   Watch on YouTube

Connect: