[Numpy-discussion] sort documentation

[Robert Kern]

On Sun, Aug 31, 2008 at 09:26, Alan G Isaac <aisaac at 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`.

    See Also
    --------
    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