numpy.partition#

numpy.partition(a, kth, axis=-1, kind=<no value>, order=None, descending=<no value>)[source]#

Return a partitioned copy of an array.

Creates a copy of the array and partially sorts it in such a way that the value of the element in the k-th position is in the position it would be in a sorted array. In the output array, all elements that would be to the left of the k-th element in a sorted array are located to the left of this element and all that would be to the right are located to its right. The ordering of the elements in the two partitions on the either side of the k-th element in the output array is undefined.

Parameters:

aarray_like: Array to be sorted.
kthint or sequence of ints: Element index to partition by. In the returned array, the k-th value of the array will be in the position it would be in a sorted array, all elements that are less than this element (or greater if descending is True) will be moved before it, and all elements that are greater than or equal to this element (or less than or equal if descending is True) will be moved after it. The order of all elements within each partition is undefined. If provided with a sequence of k-th it will partition all elements indexed by k-th of them into their sorted position at once.
axisint or None, optional: Axis along which to sort. If None, the array is flattened before sorting. The default is -1, which sorts along the last axis.
kind{‘introselect’}, optional: NumPy currently offers only one selection algorithm, ‘introselect’, and this parameter provides no additional functionality. Default is None.
orderstr or list of str, optional: When a is an array with fields defined, this argument specifies which fields to compare first, second, etc. A single field can be specified as a string. Not all fields need be specified, but unspecified fields will still be used, in the order in which they come up in the dtype, to break ties.
descendingbool, optional: Sort order. If True, the array will be partitioned in descending order. If False or None, the array will be partitioned in ascending order. Values that are NaN are partitioned towards the end of the array regardless of order. Default: None.

New in version 2.6.0.

Returns:

partitioned_arrayndarray: Array of the same type and shape as a.

See also

ndarray.partition: Method to sort an array in-place.
argpartition: Indirect partition.
sort: Full sorting

Notes

The various selection algorithms are characterized by their average speed, worst case performance, work space size, and whether they are stable. A stable sort keeps items with the same key in the same relative order. The available algorithms have the following properties:

kind	speed	worst case	work space	stable
‘introselect’	1	O(n)	0	no

All the partition algorithms make temporary copies of the data when partitioning along any but the last axis. Consequently, partitioning along the last axis is faster and uses less space than partitioning along any other axis.

The sort order for complex numbers is lexicographic. If both the real and imaginary parts are non-nan then the order is determined by the real parts except when they are equal, in which case the order is determined by the imaginary parts.

Regardless of sort order, np.nan is partitioned to the right of any other value.

Examples

>>> import numpy as np
>>> a = np.array([7, 1, 7, 7, 1, 5, 7, 2, 3, 2, 6, 2, 3, 0])
>>> p = np.partition(a, 4)
>>> p
array([0, 1, 2, 1, 2, 5, 2, 3, 3, 6, 7, 7, 7, 7]) # may vary

p[4] is 2; all elements in p[:4] are less than or equal to p[4], and all elements in p[5:] are greater than or equal to p[4]. The partition is:

[0, 1, 2, 1], [2], [5, 2, 3, 3, 6, 7, 7, 7, 7]

The next example shows the use of multiple values passed to kth.

>>> p2 = np.partition(a, (4, 8))
>>> p2
array([0, 1, 2, 1, 2, 3, 3, 2, 5, 6, 7, 7, 7, 7])

p2[4] is 2 and p2[8] is 5. All elements in p2[:4] are less than or equal to p2[4], all elements in p2[5:8] are greater than or equal to p2[4] and less than or equal to p2[8], and all elements in p2[9:] are greater than or equal to p2[8]. The partition is:

[0, 1, 2, 1], [2], [3, 3, 2], [5], [6, 7, 7, 7, 7]