[Numpy-svn] r3082 - in trunk/numpy: . core core/src

numpy-svn at scipy.org numpy-svn at scipy.org
Sun Aug 27 13:08:30 CDT 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