[Numpy-discussion] sort documentation

Robert Kern robert.kern@gmail....
Sun Aug 31 12:27:59 CDT 2008

```On Sun, Aug 31, 2008 at 09:26, Alan G Isaac <aisaac@american.edu> wrote:
> I find this confusing:
>
>     numpy.sort(a, axis=-1, kind='quicksort', order=None)
>
>     Return copy of 'a' sorted along the given axis.
>
>     Perform an inplace sort along the given axis using the algorithm
>     specified by the kind keyword.
>
> I suppose the last bit is supposed to refer to the ``sort``
> method rather than the function, but I do not see any signal
> that this is the case.

The docstring is much more complete and correct in SVN.

In [18]: sort?
Type:             function
Base Class:       <type 'function'>
Namespace:        Interactive
File:             /Users/rkern/svn/grin/numpy/core/fromnumeric.py
Definition:       sort(a, axis=-1, kind='quicksort', order=None)
Docstring:
Return a sorted copy of an array.

Parameters
----------
a : array-like
Array to be sorted.
axis : int, optional
Axis along which to sort.  If not specified, the flattened array
is used.
kind : {'quicksort', 'mergesort', 'heapsort'}, optional
Sorting algorithm.
order : list, optional
When `a` is an ndarray with fields defined, this argument specifies
which fields to compare first, second, etc.  Not all fields need be
specified.

Returns
-------
sorted_array : ndarray
Array of same type and shape as `a`.

--------
argsort : Indirect sort.
lexsort : Indirect stable sort on multiple keys.
searchsorted : Find keys in sorted array.

Notes
-----
The various sorting 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 three available algorithms have the following
properties:

=========== ======= ============= ============ =======
kind      speed   worst case    work space  stable
=========== ======= ============= ============ =======
'quicksort'    1     O(n^2)            0          no
'mergesort'    2     O(n*log(n))      ~n/2        yes
'heapsort'     3     O(n*log(n))       0          no
=========== ======= ============= ============ =======

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

Examples
--------
>>> a=np.array([[1,4],[3,1]])
>>> a.sort(1)
>>> a
array([[1, 4],
[1, 3]])
>>> a.sort(0)
>>> a
array([[1, 3],
[1, 4]])

--
Robert Kern

"I have come to believe that the whole world is an enigma, a harmless
enigma that is made terrible by our own mad attempt to interpret it as
though it had an underlying truth."
-- Umberto Eco
```