Sorting, searching and sets

np.sort(a, [options])

Returns a sorted copy. a.sort(options) sorts in place along an integer axis.

Parameters

aArrayLike

Input array.

[options.axis]number | null

Axis to work along (default -1). null uses the flattened array.

[options.kind]string

"quicksort", "heapsort", "mergesort" or "stable". Cannot be combined with stable/descending.

[options.stable]boolean

Keep equal elements in their original order.

[options.descending]boolean

Sort largest first. NaNs still go last.

Returns

NDArray

Example

np.sort([3, 1, 2]); // => [1, 2, 3]
np.sort([[3, 1], [0, 2]], { axis: 0 }); // => [[0, 1], [3, 2]]
np.sort([[3, 1], [0, 2]], { axis: null }); // => [0, 1, 2, 3]
np.sort([3, 1, 2], { descending: true }); // => [3, 2, 1]
const a = np.array([[3, 1, 2], [9, 7, 8]]);
a.sort();
a; // => [[1, 2, 3], [7, 8, 9]]

np.sort(a: ArrayLike, opts?: SortOptions | undefined): NDArray

np.argsort(a, [options])

Indices that would sort the array, as int64. Also available as a.argsort(options).

Parameters

aArrayLike

Input array.

[options.axis]number | null

Axis to work along (default -1). null uses the flattened array.

[options.kind]string

"quicksort", "heapsort", "mergesort" or "stable". Cannot be combined with stable/descending.

[options.stable]boolean

Keep equal elements in their original order.

[options.descending]boolean

Sort largest first. NaNs still go last.

Returns

NDArray (int64)

Example

np.argsort([1, 0, 1, 0], { stable: true }); // => [1, 3, 0, 2]
np.array([3, 1, 2]).argsort(); // => [1, 2, 0]

np.argsort(a: ArrayLike, opts?: SortOptions | undefined): NDArray

np.sortComplex(a)

Sorts along the last axis and returns a complex array (complex64 for 8- and 16-bit integer input, otherwise complex128).

Returns

NDArray (complex)

Example

np.sortComplex([5, 3, 6]).dtype.name; // => "complex128"
np.real(np.sortComplex([5, 3, 6])); // => [3, 5, 6]

np.sortComplex(a: ArrayLike): NDArray

np.partition(a, kth, [options])

Copy in which element kth (an index or list of indices) is where it would be after sorting. Smaller elements come before it and larger ones after it, in no particular order. a.partition(kth) works in place.

Parameters

aArrayLike

Input array.

kthnumber | number[] | NDArray

Index or indices to place. Negative values count from the end.

[options.axis]number | null

Axis (default -1). null uses the flattened array.

[options.kind]"introselect"

Selection algorithm.

Returns

NDArray

Example

np.partition([3, 4, 2, 1], 2).get(2).item(); // => 3
np.partition([3, 4, 2, 1], [1, 2]); // => [1, 2, 3, 4]

np.partition(a: ArrayLike, kth: Kth, opts?: PartitionOptions | undefined): NDArray

np.argpartition(a, kth, [options])

Indices that would partition the array, as int64. Also available as a.argpartition(kth).

Returns

NDArray (int64)

Example

np.argpartition([4, 3, 9], [0, 2]); // => [1, 0, 2]

np.argpartition(a: ArrayLike, kth: Kth, opts?: PartitionOptions | undefined): NDArray

np.lexsort(keys, [options])

Stable indirect sort on several keys. The last key is the primary sort key. keys is a list of equal-shape arrays, or an array whose rows are the keys.

Parameters

keysArrayLike[] | NDArray

Sort keys.

[options.axis]number

Axis to sort along (default -1).

Returns

NDArray (int64)

Example

const first = [0, 2, 1, 1];
const last = [3, 1, 2, 1];
np.lexsort([first, last]); // => [3, 1, 2, 0]

np.lexsort(keys: NDArray | readonly ArrayLike[], opts?: { axis?: number | null | undefined; } | undefined): NDArray

np.searchsorted(a, v, [options])

Indices at which to insert v into the sorted 1-D array a so that it stays sorted. Comparisons use the common dtype of a and v. Also available as a.searchsorted(v).

Parameters

aArrayLike

Sorted 1-D array (or unsorted with sorter).

vArrayLike | number

Values to insert.

[options.side]"left" | "right"

left gives the first suitable index, right the last.

[options.sorter]ArrayLike

Indices that sort a, e.g. from argsort.

Returns

NDArray (int64)

Example

np.searchsorted([1, 2, 2, 3], [2, 0, 4]); // => [1, 0, 4]
np.searchsorted([1, 2, 2, 3], 2, { side: "right" }).item(); // => 3
np.searchsorted([3, 1, 2], [2.5], { sorter: [1, 2, 0] }); // => [2]

np.searchsorted(a: ArrayLike, v: number | bigint | boolean | NDArray | Complex | { readonly re: number; readonly im?: number | undefined; } | readonly NestedArray[], opts?: SearchsortedOptions | undefined): NDArray

np.unique(a, [options])

Sorted unique values. If any return* flag is set, it returns { values, indices?, inverse?, counts? } instead. With axis, whole sub-arrays along that axis are compared. Results are always sorted, even with sorted: false.

Parameters

aArrayLike

Input array (flattened unless axis is given).

[options.returnIndex]boolean

Also return the index of the first occurrence of each value.

[options.returnInverse]boolean

Also return the indices that rebuild a from values.

[options.returnCounts]boolean

Also return how many times each value occurs.

[options.axis]number | null

Axis whose sub-arrays are compared.

[options.equalNan]boolean

Count all NaNs as one value (default true).

Returns

NDArray | UniqueResult

Example

np.unique([1, 1, 2, 2, 3]); // => [1, 2, 3]
const r = np.unique([1, 3, 4, 3], { returnInverse: true, returnCounts: true });
r.inverse; // => [0, 1, 2, 1]
r.counts; // => [1, 2, 1]
np.unique([[1, 0], [0, 1], [1, 0]], { axis: 0 }); // => [[0, 1], [1, 0]]

np.unique(a: ArrayLike, opts?: (UniqueOptions & { returnIndex?: false | undefined; returnInverse?: false | undefined; returnCounts?: false | undefined; }) | undefined): NDArray
np.unique(a: ArrayLike, opts: UniqueOptions): UniqueResult

np.uniqueAll(x)

Array API helpers. uniqueAll returns { values, indices, inverseIndices, counts }. uniqueCounts returns { values, counts }, uniqueInverse returns { values, inverseIndices }, and uniqueValues returns the values only. NaNs are not merged.

Returns

object | NDArray

Example

np.uniqueAll([2, 1, 2]).indices; // => [1, 0]
np.uniqueCounts([2, 1, 2]).counts; // => [1, 2]
np.uniqueInverse([2, 1, 2]).inverseIndices; // => [1, 0, 1]
np.uniqueValues([2, 1, 2]); // => [1, 2]

np.uniqueAll(x: ArrayLike): UniqueAllResult

np.intersect1d(a, b, [options])

Sorted unique values present in both inputs. With returnIndices: true, it returns { values, indices1, indices2 }, giving the first occurrences in each input.

Parameters

[options.assumeUnique]boolean

Skip removing duplicates first (inputs must already be unique).

[options.returnIndices]boolean

Also return the indices into a and b.

Returns

NDArray | IntersectResult

Example

np.intersect1d([1, 3, 4, 3], [3, 1, 2, 1]); // => [1, 3]
np.intersect1d([1, 3, 4, 3], [3, 1, 2, 1], { returnIndices: true }).indices2; // => [1, 0]

np.intersect1d(a: ArrayLike, b: ArrayLike, opts?: { assumeUnique?: boolean | undefined; returnIndices?: false | undefined; } | undefined): NDArray
np.intersect1d(a: ArrayLike, b: ArrayLike, opts: { assumeUnique?: boolean | undefined; returnIndices: true; }): IntersectResult

np.union1d(a, b)

Sorted unique values found in either input.

Returns

NDArray

Example

np.union1d([-1, 0, 1], [-2, 0, 2]); // => [-2, -1, 0, 1, 2]

np.union1d(a: ArrayLike, b: ArrayLike): NDArray

np.setdiff1d(a, b, [options])

Sorted unique values of a that are not in b. With assumeUnique, a keeps its original order.

Returns

NDArray

Example

np.setdiff1d([1, 2, 3, 2, 4, 1], [3, 4, 5, 6]); // => [1, 2]

np.setdiff1d(a: ArrayLike, b: ArrayLike, opts?: { assumeUnique?: boolean | undefined; } | undefined): NDArray

np.setxor1d(a, b, [options])

Sorted unique values found in exactly one of the inputs.

Returns

NDArray

Example

np.setxor1d([1, 2, 3, 2, 4], [2, 3, 5, 7, 5]); // => [1, 4, 5, 7]

np.setxor1d(a: ArrayLike, b: ArrayLike, opts?: { assumeUnique?: boolean | undefined; } | undefined): NDArray

np.isin(element, testElements, [options])

Boolean array with the shape of element: whether each value appears in testElements. kind accepts null, "sort" or "table" (bool/integer inputs only). Every kind gives the same result.

Parameters

[options.invert]boolean

Return true for values that are not present.

[options.assumeUnique]boolean

Accepted for NumPy parity.

[options.kind]"sort" | "table" | null

Algorithm hint.

Returns

NDArray (bool)

Example

np.isin([[0, 2], [4, 6]], [1, 2, 4, 8]); // => [[false, true], [true, false]]
np.isin([1, 5], [1], { invert: true }); // => [false, true]

np.isin(element: ArrayLike, testElements: ArrayLike, opts?: IsinOptions | undefined): NDArray

np.ediff1d(a, [options])

Differences between consecutive elements of the flattened array. Values from toBegin/toEnd are added to the start/end and must cast to the input dtype under same_kind.

Parameters

[options.toBegin]ArrayLike

Values to prepend.

[options.toEnd]ArrayLike

Values to append.

Returns

NDArray

Example

np.ediff1d([1, 2, 4, 7]); // => [1, 2, 3]
np.ediff1d([[1, 2], [4, 7]], { toBegin: [-9], toEnd: [100] }); // => [-9, 1, 2, 3, 100]

np.ediff1d(a: ArrayLike, opts?: Ediff1dOptions | undefined): NDArray