NumPy clip()
The numpy.clip() function limits the values in an array to a specified range. Any values lower than the minimum threshold are set to the minimum, and any values higher than the maximum threshold are set to the maximum.
Syntax
numpy.clip(a, a_min, a_max, out=None, *, min=None, max=None)Parameters
| Parameter | Type | Description |
|---|---|---|
a | array_like | Input array containing elements to clip. |
a_min | array_like or None | Minimum value. Elements below this value are clipped to a_min. If None, no lower bound is applied. |
a_max | array_like or None | Maximum value. Elements above this value are clipped to a_max. If None, no upper bound is applied. |
out | ndarray, optional | Optional output array where the result is stored. It must have the same shape as the input array. |
min | array_like or None | Alternative for a_min, introduced in NumPy 2.1.0. |
max | array_like or None | Alternative for a_max, introduced in NumPy 2.1.0. |
Return Value
Returns an array where values lower than a_min are replaced with a_min, and values higher than a_max are replaced with a_max. The shape and type of the input array are preserved.
Examples
1. Clipping Values in a NumPy Array
In this example, we clip an array so that values are limited between 2 and 8.
import numpy as np
# Define an array with values outside the clipping range
arr = np.array([1, 3, 5, 7, 9, 11])
# Clip values below 2 to 2, and above 8 to 8
clipped_arr = np.clip(arr, 2, 8)
# Print the result
print("Original array:", arr)
print("Clipped array:", clipped_arr)Output:
Original array: [ 1 3 5 7 9 11]
Clipped array: [2 3 5 7 8 8]
2. Clipping with No Lower Bound
In this case, we clip only the upper values by setting a_min=None.
import numpy as np
# Define an array
arr = np.array([-5, 0, 5, 10, 15])
# Clip only the upper values (set lower bound to None)
clipped_arr = np.clip(arr, None, 10)
# Print the result
print("Original array:", arr)
print("Clipped array:", clipped_arr)Output:
Original array: [-5 0 5 10 15]
Clipped array: [-5 0 5 10 10]
3. Clipping Using the out Parameter
Using an output array to store results instead of creating a new array.
import numpy as np
# Define an array
arr = np.array([2, 4, 6, 8, 10])
# Create an output array with the same shape
output_array = np.empty_like(arr)
# Clip values and store in output_array
np.clip(arr, 3, 7, out=output_array)
# Print the result
print("Original array:", arr)
print("Output array after clipping:", output_array)Output:
Original array: [ 2 4 6 8 10]
Output array after clipping: [3 4 6 7 7]
4. Clipping with a Condition Using the where Parameter
Using a mask to apply clipping only to specific elements.
import numpy as np
# Define an array
arr = np.array([-10, 5, 15, 20])
# Define a mask (apply clipping only where mask is True)
mask = np.array([True, False, True, True])
# Clip values to the range [0, 10] only where mask is True
clipped_arr = np.clip(arr, 0, 10, where=mask)
# Print the result
print("Original array:", arr)
print("Masked clipping result:", clipped_arr)Output:
Original array: [-10 5 15 20]
Masked clipping result: [ 0 5 10 10]
The clipping is applied only to the elements where mask=True, leaving other elements unchanged.