• Post author:
  • Post category:NumPy / Python
  • Post last modified:March 27, 2024
  • Reading time:18 mins read
You are currently viewing 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

What does the NumPy clip() function do?

The numpy.clip() function is used to limit the values in a NumPy array to be within a specified range. It ensures that all elements in the array are within the specified minimum and maximum values.

How can I use numpy.clip() to set a minimum value for array elements?

You can use the numpy.clip() function to set a minimum value for array elements by providing the desired minimum value to the a_min parameter.

Can I use numpy.clip() on floating-point numbers?

You can absolutely use numpy.clip() on floating-point numbers as well. The numpy.clip() function is designed to work with arrays of any numeric type, including integers and floating-point numbers. It performs element-wise clipping regardless of the data type of the array.

How does numpy.clip() handle arrays with different dimensions?

The numpy.clip() function can handle arrays with different dimensions, and it performs element-wise clipping. When you use numpy.clip() on arrays with different dimensions, the operation is broadcasted to ensure that the clipping is applied to corresponding elements.

Can I provide my own output array using the out parameter?

You can provide your own output array using the out parameter in the numpy.clip() function. This allows you to control where the result of the clipping operation is stored, rather than having the function create a new array. The out parameter is an optional argument that specifies the array where the result will be stored.

Is it possible to specify both a minimum and maximum value with numpy.clip()?

It is possible to specify both a minimum and a maximum value with the numpy.clip() function. You can use both the a_min and a_max parameters to set the desired range for clipping.

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!!

References

Malli

Malli is an experienced technical writer with a passion for translating complex Python concepts into clear, concise, and user-friendly articles. Over the years, he has written hundreds of articles in Pandas, NumPy, Python, and takes pride in ability to bridge the gap between technical experts and end-users.