How to Use NumPy clip() in Python

In NumPy, the clip() function is used to clip(limit) the values in an array to be within a specified range. In the clip() function, pass the interval(combination of minimum value and maximum value), values outside the interval are clipped to the interval edges. For example, if an interval of [1, 2] is specified, the values smaller than 1 are replaced with 1, and values larger than 2 are replaced with 2.

In this article, I will explain the Python NumPy clip() function syntax, parameters, and how it behaves while clipping or trimming the NumPy array at a particular interval.

1. Quick Examples of NumPy Clip Function

If you are in a hurry, below are some quick examples of how to use the Python NumPy clip() function. For more information about NumPy refer NumPy Tutorial.

# Quick examples of numpy clip() function

# Example 1: Use numpy.clip() function
arr = np.arange(15)
arr1 = np.clip(arr, 2, 10)

# Example 2: Use numpy.clip() function
# Use apply numpy.clip() on user defined array
arr = np.array([1,5,8,15,25,29,35,38,49,52,61,66])
arr1 = np.clip(arr, a_min = 8, a_max = 49)

# Example 3: When Lower limit Of numpy clip is an array
arr1 = np.clip(arr, a_min = [6, 8, 11, 15, 10, 8, 8, 4, 4, 4,7,7], a_max = 52)

# Example 4: Set a_max = None
arr1 = np.clip(arr, a_min = 8, a_max = None )
print("Clipped array:\n", arr1)

# Example 5: Attempt to clip with both a_min and a_max as None 
arr1 = np.clip(arr, a_min = None, a_max = None )

# Example 6: Use numpy.clip() with the out parameter
arr1 = np.zeros_like(arr)
np.clip(arr, a_min=7, a_max=37, out=arr1)

2. Syntax of NumPy clip()

Following is the syntax of clip() function.

# Syntax of clip() function
numpy.clip(arr, a_min, a_max, out=None)

2.1 Parameters of clip() Function

Following is the parameters of NumPy clip() function.

• arr – The input array that you want to clip.
• a_min – It is a scalar or an array. If it is set to None, clipping is not performed on the lower interval edge. Not more than one of arr_min and arr_max may be None.
• a_max – It is a scalar or an array. If it is set to None, clipping is not performed on the upper interval edge. Not more than one of a_min and a_max may be None.
• out – An optional parameter where you can provide a pre-allocated array to store the result. If not provided, a new array will be created.

2.2 Return Value

It returns a clipped array and the original array remains unchanged.

3. Usage of NumPy clip() Function

For clipping values in an array, the NumPy module of Python provides a function called numpy.clip(). When you specify the lower and upper limits of an array using this function, it will return an array where the elements less than the specified limit are replaced with the lowest limit, and greater than the specified limit are replaced with the highest limit.

You can use the numpy.clip() function to clip the values in the array arr between 2 and 10. The numpy.arange(15) function creates an array with values from 0 to 14, and then the numpy.clip() function is applied to clip these values between 2 and 10.

# Import numpy module
import numpy as np

# Create an array using numpy.arange()
arr = np.arange(15)
print("Original array:\n", arr)

# Use numpy.clip() function
arr1 = np.clip(arr, 2, 10)
print("Clipped array:\n", arr1)

Yields below output.

In the clipped array (arr1), values less than 2 are set to 2, and values greater than 10 are set to 10, effectively limiting the range of values in the array.

4. Apply NumPy clip() on User Defined Array

Let’s create an array using numpy.array() function and apply clip() function along with the specified interval, it will return the clipped array.

In the below example, the numpy.clip() function is applied to the user-defined array arr, and values less than 8 are set to 8, while values greater than 49 are set to 49. Adjust the values of a_min and a_max as needed for your specific clipping requirements.

# User-defined array
arr = np.array([1,5,8,15,25,29,35,38,49,52,61,66])
print("Original array:\n",arr)

# Use numpy.clip() function
# Use apply numpy.clip() on user defined array
arr1 = np.clip(arr, a_min = 8, a_max = 49)
print("Clipped array:\n",arr1)

# Output:
# Original array:
#  [ 1  5  8 15 25 29 35 38 49 52 61 66]
# Clipped array:
#  [ 8  8  8 15 25 29 35 38 49 49 49 49]

5. Set Lower limit is NumPy Array

You can set the lower limit with a scalar or an array for the clipped values of a given array. It will return the clipped array where the elements outside the interval are replaced with the specified limits.

You can use an array as the lower limit (a_min) in the numpy.clip() function. This is a valid use case, and the function will apply element-wise clipping based on the specified lower and upper limits. For example, the numpy.clip() function clips each element of the input array arr based on the corresponding lower limit specified in the array [6, 8, 11, 15, 10, 8, 8, 4, 4, 4, 7, 7]. If the original element is less than the specified lower limit, it is replaced with the lower limit. The upper limit is set to 52 for all elements.

# Create numpy input array
arr = np.array([1, 5, 8, 15, 25, 29, 35, 38, 49, 52, 61, 66])
print("Original array:\n", arr)

# When Lower limit Of numpy clip is an array
arr1 = np.clip(arr, a_min = [6, 8, 11, 15, 10, 8, 8, 4, 4, 4,7,7], a_max = 52)
print("Clipped array:\n",arr1)

# Output
# Original array:
#  [ 1  5  8 15 25 29 35 38 49 52 61 66]
# Clipped array:
#  [ 6  8 11 15 25 29 35 38 49 52 52 52]

6. Set Higher Limit is None

Use None if you want to specify only one of the minimum and maximum values of the NumPy array. This function will return clipped array with the outer elements of replaced with the specified elements.

To use numpy.clip() function to set a lower limit (a_min) and leave the upper limit (a_max) as None, effectively clipping values below the specified minimum. For instance, values in the array arr that are less than 8 are set to 8, and there is no upper limit (a_max=None), so values greater than 8 remain unchanged.

# User-defined array
arr = np.array([1,5,8,15,25,29,35,38,49,52,61,66])
print("Original array:\n",arr)

# Set a_max = None
arr1 = np.clip(arr, a_min = 8, a_max = None )
print("Clipped array:\n", arr1)

# Output:
# Original array:
#  [ 1  5  8 15 25 29 35 38 49 52 61 66]
# Clipped array:
#  [ 8  8  8 15 25 29 35 38 49 52 61 66]

If you try to set both a_min and a_max to None in the numpy.clip() function, you will get a ValueError. This is because setting both limits to None essentially means no constraint, and it contradicts the purpose of clipping.

# User-defined array
arr = np.array([1,5,8,15,25,29,35,38,49,52,61,66])
print("Original array:\n",arr)

# Attempt to clip with both a_min and a_max as None 
arr1 = np.clip(arr, a_min = None, a_max = None )
print("Clipped array:\n", arr1)

# Output:
# ValueError: One of max or min must be given

7. Get the Clipped Array along Out Param

If you want to get the clipped array along with using the out parameter to specify a pre-allocated array for the result.

In the below example, numpy.zeros_like() is used to create an empty array with the same shape and data type as arr. The numpy.clip() function is then used with the out parameter to store the clipped values in the pre-allocated arr1. This approach can be useful for memory efficiency and reusing existing arrays. Adjust the values of a_min and a_max as needed for your specific case.

# Create numpy input array
arr = np.array([1, 5, 8, 15, 25, 29, 35, 38, 49, 52, 61, 66])
print("Original array:\n", arr)

# Use numpy.clip() with the out parameter
arr1 = np.zeros_like(arr)
np.clip(arr, a_min=7, a_max=37, out=arr1)
print("Clipped array:\n",arr1)

# Output:
# Original array:
#  [ 1  5  8 15 25 29 35 38 49 52 61 66]
# Clipped array:
#  [ 7  7  8 15 25 29 35 37 37 37 37 37]

Frequently Asked Questions

Conclusion

In this article, I have explained how to use the Python NumPy clip() function and using this function along with specified intervals, how you can get the clipped array with examples.

Happy Learning!!

Related Articles

• Get the maximum value of array
• How to get the average of an array?
• Create an array using arange() function
• How to do matrix multiplication in NumPy?
• NumPy Array Addition
• Python NumPy Array Operations
• Get the minimum value of array
• NumPy broadcast() Function in Python
• NumPy Inverse Matrix in Python
• NumPy Variance Function in Python
• How to Use NumPy random seed() in Python
• How to Use NumPy random.uniform() in Python?

References

• https://numpy.org/doc/stable/reference/