How to Use np.searchsorted in NumPy: Syntax and Examples

Use np.searchsorted to find the index where elements should be inserted in a sorted array to maintain order. It returns the insertion positions for given values, optionally specifying whether to insert before or after existing entries with the side parameter.

Syntax

The basic syntax of np.searchsorted is:

• np.searchsorted(sorted_array, values, side='left', sorter=None)

Explanation:

• sorted_array: A 1-D sorted NumPy array where you want to find insertion points.
• values: The values to insert into sorted_array.
• side: Either 'left' or 'right'. Determines whether to insert before ('left') or after ('right') existing entries.
• sorter: Optional array of indices that sort sorted_array. Used if sorted_array is not sorted but you know the sorting order.

python

np.searchsorted(sorted_array, values, side='left', sorter=None)

Example

This example shows how to find insertion points for values in a sorted array using np.searchsorted. It demonstrates both side='left' and side='right' options.

python

import numpy as np

sorted_arr = np.array([1, 3, 4, 7, 9])
values = np.array([2, 5, 7])

# Find insertion indices with side='left'
indices_left = np.searchsorted(sorted_arr, values, side='left')

# Find insertion indices with side='right'
indices_right = np.searchsorted(sorted_arr, values, side='right')

print('Sorted array:', sorted_arr)
print('Values to insert:', values)
print('Insertion indices (left):', indices_left)
print('Insertion indices (right):', indices_right)

Output

Sorted array: [1 3 4 7 9]
Values to insert: [2 5 7]
Insertion indices (left): [1 3 3]
Insertion indices (right): [1 3 4]

Common Pitfalls

Common mistakes when using np.searchsorted include:

• Using it on an unsorted array without providing the sorter parameter, which leads to incorrect results.
• Confusing side='left' and side='right', which affects whether the insertion index is before or after existing equal values.
• Passing multi-dimensional arrays instead of 1-D arrays, which is not supported.

Example of a wrong and right usage:

python

import numpy as np

unsorted_arr = np.array([3, 1, 4, 7, 9])
values = np.array([2, 5])

# Wrong: Using searchsorted on unsorted array
wrong_indices = np.searchsorted(unsorted_arr, values)

# Right: Sort array first or provide sorter
sorted_arr = np.sort(unsorted_arr)
right_indices = np.searchsorted(sorted_arr, values)

print('Wrong indices:', wrong_indices)
print('Right indices:', right_indices)

Output

Wrong indices: [1 1]
Right indices: [1 3]

Quick Reference

Parameter	Description	Default
sorted_array	1-D sorted array to search	Required
values	Values to find insertion indices for	Required
side	Insert before ('left') or after ('right') equal values	'left'
sorter	Indices that sort the array if not sorted	None

Key Takeaways

np.searchsorted finds indices to insert values into a sorted array to keep it sorted.

Use the 'side' parameter to control insertion before or after equal values.

Always ensure the array is sorted or provide a sorter to get correct results.

It only works with 1-D arrays for searching insertion points.

Useful for binary search tasks and efficient data insertion.