NumPy percentile()

The percentile() method computes the q-th percentile of the data along the specified axis.


import numpy as np

# create an array
array1 = np.array([0, 1, 2, 3, 4, 5, 6, 7])

# calculate the 25th, 50th and 75th percentile of the array p25 = np.percentile(array1, 25) p50 = np.percentile(array1, 50) p75 = np.percentile(array1, 75)
print(p25, p50, p75) # Output: 1.75 3.5 5.25

percentile() Syntax

The syntax of percentile() is:

numpy.percentile(array, q, axis=None, out=None, overwrite_input=False, method='linear', keepdims=False, interpolation=None)

percentile() Arguments

The percentile() method takes the following arguments:

  • array - input array(can be array_like)
  • q- qth percentile to find(can be array_like of float)
  • axis(optional)- axis or axes along which the means are computed(int or tuple of int)
  • out(optional)- output array in which to place the result(ndarray)
  • keepdims(optional)- specifies whether to preserve the shape of the original array(bool)
  • override_input(optional)- bool value that determines if intermediate calculations can modify an array
  • method(optional)- interpolation method to use
  • interpolation(optional)- the deprecated name for the method keyword argument


The default values of,

  • axis = None, i.e. the percentile of the entire array is taken.
    • By default, keepdims and override_input will be False.
    • The interpolation method is 'linear'.
    • If the input contains integers or floats smaller than float64, the output data type is float64. Otherwise, the output data type is the same as that of the input.

percentile() Return Value

The percentile() method returns the q-th percentile(s) of the input array along the specified axis.


The percentile is a statistical measure that represents the value below which a specific percentage of data falls. It helps analyze the distribution of a dataset.

In NumPy, the percentile() function computes the q-th percentile of data along the specified axis.

The q-th percentile represents the value below which q percent of the data falls. For example, the 50th percentile (also known as the median) divides the data into two equal halves, with 50% of the values below it.

Example 1: Find the Percentile of a ndArray

import numpy as np

# create an array
array1 = np.array([[[0, 1],[2, 3]],
   [[4, 5],[6, 7]]])

# find the 50th percentile of entire array percentile1 = np.percentile(array1, q=50) # find the 50th percentile across axis 0 percentile2 = np.percentile(array1, q=50, axis=0) # find the 50th percentile across axis 0 and 1 percentile3 = np.percentile(array1, q=50, axis=(0, 1))
print('\n50th Percentile of the entire array:', percentile1) print('\n50th Percentile across axis 0:\n', percentile2) print('\n50th Percentile across axis 0 and 1:', percentile3)


50th Percentile of the entire array: 3.5

50th Percentile across axis 0:
[[2. 3.]
 [4. 5.]]

50th Percentile across axis 0 and 1:[3. 4.]

Example 2: Use out to Store the Result in Desired Location

The out parameter allows to specify an output array where the result will be stored.

import numpy as np

arr = np.array([[1, 2, 3],
                [4, 5, 6]])

# create an output array
output = np.zeros(3)

# compute 25th percentile and store the result in the output array
np.percentile(arr, 25, out = output, axis = 0)

print('25th Percentile:', output)


25th Percentile: [1.75 2.75 3.75]

Example 3: Using Optional keepdims Argument

If keepdims is set to True, the resultant mean array is of the same number of dimensions as the original array.

import numpy as np

arr = np.array([[1, 2, 3],
                [4, 5, 6]])

# keepdims defaults to False result1 = np.percentile(arr, 50 , axis = 0) # pass keepdims as True result2 = np.percentile(arr, 50, axis = 0, keepdims = True)
print('Dimensions in original array:', arr.ndim) print('Without keepdims:', result1, 'with dimensions', result1.ndim) print('With keepdims:', result2, 'with dimensions', result2.ndim)


Dimensions in original array: 2
Without keepdims: [2.5 3.5 4.5] with dimensions 1
With keepdims: [[2.5 3.5 4.5]] with dimensions 2