[Numpy-svn] r3082 - in trunk/numpy: . core core/src
numpy-svn at scipy.org
numpy-svn at scipy.org
Sun Aug 27 14:08:30 EDT 2006
Author: charris
Date: 2006-08-27 13:08:18 -0500 (Sun, 27 Aug 2006)
New Revision: 3082
Modified:
trunk/numpy/add_newdocs.py
trunk/numpy/core/fromnumeric.py
trunk/numpy/core/src/arraymethods.c
Log:
Move the documentation of the sort, argsort, and searchsorted methods into
add_newdocs. Rewrite the documentation of sort and argsort. Replace the
documentation of these functions in fromnumeric with the new documentation.
Modified: trunk/numpy/add_newdocs.py
===================================================================
--- trunk/numpy/add_newdocs.py 2006-08-27 08:02:19 UTC (rev 3081)
+++ trunk/numpy/add_newdocs.py 2006-08-27 18:08:18 UTC (rev 3082)
@@ -46,16 +46,16 @@
ndarray.__new__(subtype, shape=, dtype=float, buffer=None,
offset=0, strides=None, order=None)
-
+
There are two modes of creating an array using __new__:
- 1) If buffer is None, then only shape, dtype, and order
+ 1) If buffer is None, then only shape, dtype, and order
are used
2) If buffer is an object exporting the buffer interface, then
all keywords are interpreted.
- The dtype parameter can be any object that can be interpreted
+ The dtype parameter can be any object that can be interpreted
as a numpy.dtype object.
-
- No __init__ method is needed because the array is fully
+
+ No __init__ method is needed because the array is fully
initialized after the __new__ method.
"""
)
@@ -82,7 +82,7 @@
('__array_priority__', 'Array priority'),
('__array_finalize__', 'None')
]
- )
+ )
add_newdoc('numpy.core', 'flatiter',
@@ -108,20 +108,20 @@
add_newdoc('numpy.core.multiarray','array',
"""array(object, dtype=None, copy=1,order=None, subok=0,ndmin=0)
-
+
Return an array from object with the specified date-type.
Inputs:
- object - an array, any object exposing the array interface, any
- object whose __array__ method returns an array, or any
+ object - an array, any object exposing the array interface, any
+ object whose __array__ method returns an array, or any
(nested) sequence.
dtype - The desired data-type for the array. If not given, then
the type will be determined as the minimum type required
to hold the objects in the sequence. This argument can only
- be used to 'upcast' the array. For downcasting, use the
+ be used to 'upcast' the array. For downcasting, use the
.astype(t) method.
copy - If true, then force a copy. Otherwise a copy will only occur
- if __array__ returns a copy, obj is a nested sequence, or
+ if __array__ returns a copy, obj is a nested sequence, or
a copy is needed to satisfy any of the other requirements
order - Specify the order of the array. If order is 'C', then the
array will be in C-contiguous order (last-index varies the
@@ -232,9 +232,9 @@
The tuple of sequences (a1, a2, ...) are joined along the given axis
(default is the first one) into a single numpy array.
-
+
Example:
-
+
>>> concatenate( ([0,1,2], [5,6,7]) )
array([0, 1, 2, 5, 6, 7])
@@ -313,7 +313,7 @@
To group the indices by element, rather than dimension, use
transpose(where(condition, | x, y))
-
+
instead. This always results in a 2d array, with a row of indices for
each element that satisfies the condition.
@@ -357,4 +357,81 @@
""")
+add_newdoc('numpy.core.multiarray', 'ndarray', ('sort',
+"""a.sort(axis=-1, kind='quicksort') -> None. Sort a along the given axis.
+Keyword arguments:
+
+axis -- axis to be sorted (default -1)
+kind -- sorting algorithm (default 'quicksort')
+ Possible values: 'quicksort', 'mergesort', or 'heapsort'.
+
+Returns: None.
+
+This method sorts a in place along the given axis using the algorithm
+specified by the kind keyword.
+
+The various sorts may characterized by average speed, worst case
+performance, need for work space, and whether they are stable. A stable
+sort keeps items with the same key in the same relative order and is most
+useful when used with argsort where the key might differ from the items
+being sorted. The three available algorithms have the following properties:
+
+|------------------------------------------------------|
+| kind | speed | worst case | work space | stable|
+|------------------------------------------------------|
+|'quicksort'| 1 | o(n) | 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 the sort is
+not along the last axis. Consequently, sorts along the last axis are faster
+and use less space than sorts along other axis.
+
+"""))
+
+add_newdoc('numpy.core.multiarray', 'ndarray', ('argsort',
+"""a.sort(axis=-1, kind='quicksort') -> indices that sort a along given axis.
+
+Keyword arguments:
+
+axis -- axis to be indirectly sorted (default -1)
+kind -- sorting algorithm (default 'quicksort')
+ Possible values: 'quicksort', 'mergesort', or 'heapsort'
+
+Returns: array of indices that sort a along the specified axis.
+
+This method executes an indirect sort along the given axis using the
+algorithm specified by the kind keyword. It returns an array of indices of
+the same shape as a that index data along the given axis in sorted order.
+
+The various sorts are characterized by average speed, worst case
+performance, need for work space, 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 the sort is not
+along the last axis. Consequently, sorts along the last axis are faster and use
+less space than sorts along other axis.
+
+"""))
+
+add_newdoc('numpy.core.multiarray', 'ndarray', ('searchsorted',
+"""a.searchsorted(v)
+
+ Assuming that a is a 1-D array, in ascending order and represents
+ bin boundaries, then a.searchsorted(values) gives an array of bin
+ numbers, giving the bin into which each value would be placed.
+ This method is helpful for histograming. Note: No warning is
+ given if the boundaries, in a, are not in ascending order.;
+
+"""))
Modified: trunk/numpy/core/fromnumeric.py
===================================================================
--- trunk/numpy/core/fromnumeric.py 2006-08-27 08:02:19 UTC (rev 3081)
+++ trunk/numpy/core/fromnumeric.py 2006-08-27 18:08:18 UTC (rev 3082)
@@ -125,15 +125,74 @@
return transpose(axes)
def sort(a, axis=-1, kind='quicksort'):
- """sort(a,axis=-1) returns array with elements sorted along given axis.
+ """Return copy of array sorted along the given axis.
+
+ Keyword arguments:
+
+ axis -- axis to be sorted (default -1)
+ kind -- sorting algorithm (default 'quicksort')
+ Possible values: 'quicksort', 'mergesort', or 'heapsort'.
+
+ Returns: None.
+
+ This method sorts a in place along the given axis using the algorithm
+ specified by the kind keyword.
+
+ The various sorts may characterized by average speed, worst case
+ performance, need for work space, and whether they are stable. A stable
+ sort keeps items with the same key in the same relative order and is most
+ useful when used with argsort where the key might differ from the items
+ being sorted. The three available algorithms have the following properties:
+
+ |------------------------------------------------------|
+ | kind | speed | worst case | work space | stable|
+ |------------------------------------------------------|
+ |'quicksort'| 1 | o(n) | 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 the sort is
+ not along the last axis. Consequently, sorts along the last axis are faster
+ and use less space than sorts along other axis.
+
"""
a = asanyarray(a).copy()
a.sort(axis, kind)
return a
def argsort(a, axis=-1, kind='quicksort'):
- """argsort(a,axis=-1) return the indices into a of the sorted array
- along the given axis.
+ """Return array of indices that index a in sorted order.
+
+ Keyword arguments:
+
+ axis -- axis to be indirectly sorted (default -1)
+ kind -- sorting algorithm (default 'quicksort')
+ Possible values: 'quicksort', 'mergesort', or 'heapsort'
+
+ Returns: array of indices that sort a along the specified axis.
+
+ This method executes an indirect sort along the given axis using the
+ algorithm specified by the kind keyword. It returns an array of indices of
+ the same shape as a that index data along the given axis in sorted order.
+
+ The various sorts are characterized by average speed, worst case
+ performance, need for work space, 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 the sort is not
+ along the last axis. Consequently, sorts along the last axis are faster and use
+ less space than sorts along other axis.
+
"""
try:
argsort = a.argsort
@@ -160,7 +219,7 @@
except AttributeError:
return _wrapit(a, 'argmin', axis)
return argmin(axis)
-
+
def searchsorted(a, v):
"""searchsorted(a, v)
"""
@@ -239,7 +298,7 @@
else:
res = nonzero()
return res
-
+
def shape(a):
"""shape(a) returns the shape of a (as a function call which
also works on nested sequences).
@@ -328,7 +387,7 @@
return all(axis, out)
def any(x,axis=None, out=None):
- """Return true if any elements of x are true:
+ """Return true if any elements of x are true:
"""
try:
any = x.any
@@ -337,7 +396,7 @@
return any(axis, out)
def all(x,axis=None, out=None):
- """Return true if all elements of x are true:
+ """Return true if all elements of x are true:
"""
try:
all = x.all
@@ -467,9 +526,9 @@
def mean(a, axis=None, dtype=None, out=None):
"""mean(a, axis=None, dtype=None)
Return the arithmetic mean.
-
- The mean is the sum of the elements divided by the number of elements.
-
+
+ The mean is the sum of the elements divided by the number of elements.
+
See also: average
"""
try:
@@ -484,7 +543,7 @@
The standard deviation is the square root of the average of the squared
deviations from the mean, i.e. std = sqrt(mean((x - x.mean())**2)).
-
+
See also: var
"""
try:
@@ -499,7 +558,7 @@
The variance is the average of the squared deviations from the mean,
i.e. var = mean((x - x.mean())**2).
-
+
See also: std
"""
try:
Modified: trunk/numpy/core/src/arraymethods.c
===================================================================
--- trunk/numpy/core/src/arraymethods.c 2006-08-27 08:02:19 UTC (rev 3081)
+++ trunk/numpy/core/src/arraymethods.c 2006-08-27 18:08:18 UTC (rev 3082)
@@ -743,8 +743,6 @@
return _ARET(PyArray_Choose(self, choices, out, clipmode));
}
-static char doc_sort[] = "a.sort(axis=-1,kind='quicksort') sorts in place along axis. Return is None and kind can be 'quicksort', 'mergesort', or 'heapsort'";
-
static PyObject *
array_sort(PyArrayObject *self, PyObject *args, PyObject *kwds)
{
@@ -763,10 +761,6 @@
return Py_None;
}
-static char doc_argsort[] = "a.argsort(axis=-1,kind='quicksort')\n"\
- " Return the indexes into a that would sort it along the"\
- " given axis; kind can be 'quicksort', 'mergesort', or 'heapsort'";
-
static PyObject *
array_argsort(PyArrayObject *self, PyObject *args, PyObject *kwds)
{
@@ -781,14 +775,6 @@
return _ARET(PyArray_ArgSort(self, axis, which));
}
-static char doc_searchsorted[] = "a.searchsorted(v)\n"\
- " Assuming that a is a 1-D array, in ascending order and\n"\
- " represents bin boundaries, then a.searchsorted(values) gives an\n"\
- " array of bin numbers, giving the bin into which each value would\n"\
- " be placed. This method is helpful for histograming. \n"\
- " Note: No warning is given if the boundaries, in a, are not \n"\
- " in ascending order.";
-
static PyObject *
array_searchsorted(PyArrayObject *self, PyObject *args)
{
@@ -1783,11 +1769,11 @@
{"choose", (PyCFunction)array_choose,
METH_VARARGS|METH_KEYWORDS, doc_choose},
{"sort", (PyCFunction)array_sort,
- METH_VARARGS|METH_KEYWORDS, doc_sort},
+ METH_VARARGS|METH_KEYWORDS, NULL},
{"argsort", (PyCFunction)array_argsort,
- METH_VARARGS|METH_KEYWORDS, doc_argsort},
+ METH_VARARGS|METH_KEYWORDS, NULL},
{"searchsorted", (PyCFunction)array_searchsorted,
- METH_VARARGS, doc_searchsorted},
+ METH_VARARGS, NULL},
{"argmax", (PyCFunction)array_argmax,
METH_VARARGS|METH_KEYWORDS, doc_argmax},
{"argmin", (PyCFunction)array_argmin,
More information about the Numpy-svn
mailing list