[Numpy-svn] r4037 - trunk/numpy/core

numpy-svn@scip... numpy-svn@scip...
Sun Sep 16 00:42:03 CDT 2007


Author: charris
Date: 2007-09-16 00:42:01 -0500 (Sun, 16 Sep 2007)
New Revision: 4037

Modified:
   trunk/numpy/core/fromnumeric.py
Log:
More documentation.


Modified: trunk/numpy/core/fromnumeric.py
===================================================================
--- trunk/numpy/core/fromnumeric.py	2007-09-16 05:40:34 UTC (rev 4036)
+++ trunk/numpy/core/fromnumeric.py	2007-09-16 05:42:01 UTC (rev 4037)
@@ -52,18 +52,14 @@
 
         a : array
             The source array
-
         indices : int array
             The indices of the values to extract.
-
         axis : {None, int}, optional
             The axis over which to select values. None signifies that the
             operation should be performed over the flattened array.
-
         out : {None, array}, optional
             If provided, the result will be inserted into this array. It should
             be of the appropriate shape and dtype.
-
         mode : {'raise', 'wrap', 'clip'}, optional
             Specifies how out-of-bounds indices will behave.
             'raise' -- raise an error
@@ -95,11 +91,9 @@
 
         a : array
             Array to be reshaped.
-
         newshape : shape tuple or int
            The new shape should be compatible with the original shape. If an
            integer, then the result will be a 1D array of that length.
-
         order : {'C', 'FORTRAN'}, optional
             Determines whether the array data should be viewed as in C
             (row-major) order or FORTRAN (column-major) order.
@@ -135,15 +129,12 @@
         a : int array
             This array must contain integers in [0, n-1], where n is the number
             of choices.
-
         choices : sequence of arrays
             Each of the choice arrays should have the same shape as the index
             array.
-
         out : array, optional
             If provided, the result will be inserted into this array. It should
             be of the appropriate shape and dtype
-
         mode : {'raise', 'wrap', 'clip'}, optional
             Specifies how out-of-bounds indices will behave.
             'raise' : raise an error
@@ -182,14 +173,13 @@
 
     *Parameters*:
 
-        a : array
-
-        repeats : int or int array
+        a : {array_like}
+            Blah.
+        repeats : {integer, integer_array}
             The number of repetitions for each element. If a plain integer, then
             it is applied to all elements. If an array, it needs to be of the
             same length as the chosen axis.
-
-        axis : {None, int}, optional
+        axis : {None, integer}, optional
             The axis along which to repeat values. If None, then this function
             will operated on the flattened array `a` and return a similarly flat
             result.
@@ -271,14 +261,11 @@
 
         a : array
             Array to be sorted.
-
         axis : {None, int} optional
             Axis along which to sort. None indicates that the flattened
             array should be used.
-
         kind : {'quicksort', 'mergesort', 'heapsort'}, optional
             Sorting algorithm to use.
-
         order : {None, list type}, optional
             When a is an array with fields defined, this argument specifies
             which fields to compare first, second, etc.  Not all fields need be
@@ -340,14 +327,11 @@
 
         a : array
             Array to be sorted.
-
         axis : {None, int} optional
             Axis along which to sort. None indicates that the flattened
             array should be used.
-
         kind : {'quicksort', 'mergesort', 'heapsort'}, optional
             Sorting algorithm to use.
-
         order : {None, list type}, optional
             When a is an array with fields defined, this argument specifies
             which fields to compare first, second, etc.  Not all fields need be
@@ -355,7 +339,7 @@
 
     *Returns*:
 
-        indices : integer array
+        index_array : {integer_array}
             Array of indices that sort 'a' along the specified axis.
 
     *See Also*:
@@ -400,16 +384,15 @@
 
     *Parameters*:
 
-        a : array
+        a : {array_like}
             Array to look in.
-
         axis : {None, integer}
             If None, the index is into the flattened array, otherwise along
             the specified axis
 
     *Returns*:
 
-        Array of indices
+        index_array : {integer_array}
 
     *Examples*
 
@@ -434,16 +417,15 @@
 
     *Parameters*:
 
-        a : array
+        a : {array_like}
             Array to look in.
-
         axis : {None, integer}
             If None, the index is into the flattened array, otherwise along
             the specified axis
 
     *Returns*:
 
-        Array of indices
+        index_array : {integer_array}
 
     *Examples*
 
@@ -477,10 +459,8 @@
 
         a : 1-d array
             Array must be sorted in ascending order.
-
         v : array or list type
             Array of keys to be searched for in a.
-
         side : {'left', 'right'}, optional
             If 'left', the index of the first location where the key could be
             inserted is found, if 'right', the index of the last such element is
@@ -528,21 +508,20 @@
 
     *Parameters*:
 
-        a : array_like
+        a : {array_like}
             Array to be reshaped.
 
-        new_shape : tuple
-            Shape of the new array.
+        new_shape : {tuple}
+            Shape of reshaped array.
 
     *Returns*:
 
-        new_array : array
+        reshaped_array : {array}
             The new array is formed from the data in the old array, repeated if
             necessary to fill out the required number of elements, with the new
             shape.
 
     """
-
     if isinstance(new_shape, (int, nt.integer)):
         new_shape = (new_shape,)
     a = ravel(a)
@@ -601,17 +580,14 @@
 
     *Parameters*:
 
-        a : array_like
+        a : {array_like}
             Array from whis the diagonals are taken.
-
         offset : {0, integer}, optional
             Offset of the diagonal from the main diagonal. Can be both positive
             and negative. Defaults to main diagonal.
-
         axis1 : {0, integer}, optional
             Axis to be used as the first axis of the 2-d subarrays from which
             the diagonals should be taken. Defaults to first axis.
-
         axis2 : {1, integer}, optional
             Axis to be used as the second axis of the 2-d subarrays from which
             the diagonals should be taken. Defaults to second axis.
@@ -669,28 +645,23 @@
 
     *Parameters*:
 
-        a : array_like
+        a : {array_like}
             Array from whis the diagonals are taken.
-
         offset : {0, integer}, optional
             Offset of the diagonal from the main diagonal. Can be both positive
             and negative. Defaults to main diagonal.
-
         axis1 : {0, integer}, optional
             Axis to be used as the first axis of the 2-d subarrays from which
             the diagonals should be taken. Defaults to first axis.
-
         axis2 : {1, integer}, optional
             Axis to be used as the second axis of the 2-d subarrays from which
             the diagonals should be taken. Defaults to second axis.
-
         dtype : {None, dtype}, optional
             Determines the type of the returned array and of the accumulator
             where the elements are summed. If dtype has the value None and a is
             of integer type of precision less than the default integer
             precision, then the default integer precision is used. Otherwise,
             the precision is the same as that of a.
-
         out : {None, array}, optional
             Array into which the sum can be placed. It's type is preserved and
             it must be of the right shape to hold the output.
@@ -722,7 +693,7 @@
 
     *Parameters*:
 
-        a : array_like
+        a : {array_like}
 
         order : {'C','F'}, optional
             If order is 'C' the elements are taken in row major order. If order
@@ -730,7 +701,7 @@
 
     *Returns*:
 
-        1d array of the elements of a.
+        1d_array : {array}
 
     *See Also*:
 
@@ -756,11 +727,11 @@
 
     *Parameters*:
 
-        a : array_like
+        a : {array_like}
 
     *Returns*:
 
-        Tuple of arrays of indices.
+        tuple_of_arrays : {tuple}
 
     *Examples*
 
@@ -786,11 +757,13 @@
 
     *Parameters*:
 
-        a : array type
+        a : {array_like}
+            Array whose shape is desired. If a is not an array, a conversion is
+            attempted.
 
     *Returns*:
 
-        tuple of integers :
+        tuple_of_integers :
             The elements of the tuple are the length of the corresponding array
             dimension.
 
@@ -841,29 +814,28 @@
 
     *Parameters*:
 
-        a : array_type
-
+        a : {array_type}
+            Array containing elements whose sum is desired. If a is not an array, a
+            conversion is attempted.
         axis : {None, integer}
             Axis over which the sum is taken. If None is used, then the sum is
             over all the array elements.
-
         dtype : {None, dtype}, optional
             Determines the type of the returned array and of the accumulator
-            where the elements are summed. If dtype has the value None and a is
-            of integer type of precision less than the default platform integer
-            precision, then the default integer precision is used. Otherwise,
-            the precision is the same as that of a.
-
+            where the elements are summed. If dtype has the value None and the
+            type of a is an integer type of precision less than the default
+            platform integer, then the default platform integer precision is
+            used.  Otherwise, the dtype is the same as that of a.
         out : {None, array}, optional
             Array into which the sum can be placed. It's type is preserved and
             it must be of the right shape to hold the output.
 
     *Returns*:
 
-        Sum along specified axis : {array, scalar}, type as above.
-            If the sum is along an axis, then an array is returned whose shape
-            is the same as a with the specified axis removed. For 1d arrays or
-            dtype=None, the result is a 0d array.
+        sum_along_axis : {array, scalar}, see dtype parameter above.
+            Returns an array whose shape is the same as a with the specified
+            axis removed. Returns a 0d array when a is 1d or dtype=None.
+            Returns a reference to the specified output array if specified.
 
     *See Also*:
 
@@ -899,29 +871,29 @@
 
     *Parameters*:
 
-        a : array_type
-
+        a : {array_like}
+            Array containing elements whose product is desired. If a is not an array, a
+            conversion is attempted.
         axis : {None, integer}
             Axis over which the product is taken. If None is used, then the
             product is over all the array elements.
-
         dtype : {None, dtype}, optional
             Determines the type of the returned array and of the accumulator
-            where the elements are multiplied. If dtype has the value None and a
-            is of integer type of precision less than the default platform
-            integer precision, then the default integer precision is used.
-            Otherwise, the precision is the same as that of a.
-
+            where the elements are multiplied. If dtype has the value None and
+            the type of a is an integer type of precision less than the default
+            platform integer, then the default platform integer precision is
+            used.  Otherwise, the dtype is the same as that of a.
         out : {None, array}, optional
-            Array into which the product can be placed. It's type is preserved and
-            it must be of the right shape to hold the output.
+            Alternative output array in which to place the result. It must have
+            the same shape as the expected output but the type will be cast if
+            necessary.
 
     *Returns*:
 
-        product along specified axis : {array, scalar}, type as above.
-            If the product is along an axis, then an array is returned whose shape
-            is the same as a with the specified axis removed. For 1d arrays or
-            dtype=None, the result is a 0d array.
+        product_along_axis : {array, scalar}, see dtype parameter above.
+            Returns an array whose shape is the same as a with the specified
+            axis removed. Returns a 0d array when a is 1d or dtype=None.
+            Returns a reference to the specified output array if specified.
 
     *See Also*:
 
@@ -1123,13 +1095,14 @@
 
     *Parameters*:
 
-        a : array_like
-            Array_like object whose dimensions are counted.
+        a : {array_like}
+            Array whose number of dimensions are desired. If a is not an array, a
+            conversion is attempted.
 
     *Returns*:
 
-        number of dimensions : int
-            Just so.
+        number_of_dimensions : {integer}
+            Returns the number of dimensions.
 
     *See Also*:
 
@@ -1166,13 +1139,14 @@
 
     *Parameters*:
 
-        a : array_like
-            Array_like object whose dimensions are counted.
+        a : {array_like}
+            Array whose number of dimensions is desired. If a is not an array, a
+            conversion is attempted.
 
     *Returns*:
 
-        number of dimensions : int
-            Just so.
+        number_of_dimensions : {integer}
+            Returns the number of dimensions.
 
     *See Also*:
 
@@ -1205,15 +1179,17 @@
 
     *Parameters*:
 
-        a : array_like
-            If a is not an array, a conversion is attempted.
-        axis : {None, int}, optional
-            Axis along which elements are counted. None means all elements.
+        a : {array_like}
+            Array whose axis size is desired. If a is not an array, a conversion
+            is attempted.
+        axis : {None, integer}, optional
+            Axis along which the elements are counted. None means all elements
+            in the array.
 
     *Returns*:
 
-        element count : int
-            Count of elements.
+        element_count : {integer}
+            Count of elements along specified axis.
 
     *See Also*:
 
@@ -1249,27 +1225,30 @@
 def around(a, decimals=0, out=None):
     """Round a to the given number of decimals.
 
-    The real and imaginary parts of complex numbers are rounded separately.
-    Nothing is done if the input is an integer array with decimals >= 0.
+    The real and imaginary parts of complex numbers are rounded separately. The
+    result of rounding a float is a float so the type must be cast if integers
+    are desired.  Nothing is done if the input is an integer array and the
+    decimals parameter has a value >= 0.
 
     *Parameters*:
 
-        a : array_like
-
+        a : {array_like}
+            Array containing numbers whose rounded values are desired. If a is
+            not an array, a conversion is attempted.
         decimals : {0, int}, optional
             Number of decimal places to round to. When decimals is negative it
             specifies the number of positions to the left of the decimal point.
         out : {None, array}, optional
-            Existing array to use for output (by default, make a copy of a).
+            Alternative output array in which to place the result. It must have
+            the same shape as the expected output but the type will be cast if
+            necessary. Numpy rounds floats to floats by default.
 
-    *Returns*:
+        *Returns*:
 
-        out : array
-            May be used to specify a different array to hold the result rather
-            than the default a. If the type of the array specified by 'out'
-            differs from that of a, the result is cast to the new type,
-            otherwise the original type is kept. Floats round to floats by
-            default.
+        rounded_array : {array}
+            If out=None, returns a new array of the same type as a containing
+            the rounded values, otherwise a reference to the output array is
+            returned.
 
     *See Also*:
 
@@ -1282,9 +1261,17 @@
         Numpy rounds to even. Thus 1.5 and 2.5 round to 2.0, -0.5 and 0.5 round
         to 0.0, etc. Results may also be surprising due to the inexact
         representation of decimal fractions in IEEE floating point and the
-        errors introduced in scaling the numbers when decimals is something
-        other than 0.
+        errors introduced when scaling by powers of ten.
 
+    *Examples*
+
+        >>> around([.5, 1.5, 2.5, 3.5, 4.5])
+        array([ 0.,  2.,  2.,  4.,  4.])
+        >>> around([1,2,3,11], decimals=1)
+        array([ 1,  2,  3, 11])
+        >>> around([1,2,3,11], decimals=-1)
+        array([ 0,  0,  0, 10])
+
     """
     try:
         round = a.round
@@ -1296,27 +1283,30 @@
 def round_(a, decimals=0, out=None):
     """Round a to the given number of decimals.
 
-    The real and imaginary parts of complex numbers are rounded separately.
-    Nothing is done if the input is an integer array with decimals >= 0.
+    The real and imaginary parts of complex numbers are rounded separately. The
+    result of rounding a float is a float so the type must be cast if integers
+    are desired.  Nothing is done if the input is an integer array and the
+    decimals parameter has a value >= 0.
 
     *Parameters*:
 
-        a : array_like
-
-        decimals : {0, int}, optional
+        a : {array_like}
+            Array containing numbers whose rounded values are desired. If a is
+            not an array, a conversion is attempted.
+        decimals : {0, integer}, optional
             Number of decimal places to round to. When decimals is negative it
             specifies the number of positions to the left of the decimal point.
         out : {None, array}, optional
-            Existing array to use for output (by default, make a copy of a).
+            Alternative output array in which to place the result. It must have
+            the same shape as the expected output but the type will be cast if
+            necessary.
 
     *Returns*:
 
-        out : array
-            May be used to specify a different array to hold the result rather
-            than the default a. If the type of the array specified by 'out'
-            differs from that of a, the result is cast to the new type,
-            otherwise the original type is kept. Floats round to floats by
-            default.
+        rounded_array : {array}
+            If out=None, returns a new array of the same type as a containing
+            the rounded values, otherwise a reference to the output array is
+            returned.
 
     *See Also*:
 
@@ -1329,9 +1319,17 @@
         Numpy rounds to even. Thus 1.5 and 2.5 round to 2.0, -0.5 and 0.5 round
         to 0.0, etc. Results may also be surprising due to the inexact
         representation of decimal fractions in IEEE floating point and the
-        errors introduced in scaling the numbers when decimals is something
-        other than 0.
+        errors introduced when scaling by powers of ten.
 
+    *Examples*
+
+        >>> round_([.5, 1.5, 2.5, 3.5, 4.5])
+        array([ 0.,  2.,  2.,  4.,  4.])
+        >>> round_([1,2,3,11], decimals=1)
+        array([ 1,  2,  3, 11])
+        >>> round_([1,2,3,11], decimals=-1)
+        array([ 0,  0,  0, 10])
+
     """
     try:
         round = a.round
@@ -1345,27 +1343,30 @@
 
     Returns the average of the array elements.  The average is taken
     over the flattened array by default, otherwise over the specified
-    axis.
+    axis. The dtype returned for integer type arrays is float
 
     *Parameters*:
 
-        axis : integer
+        a : {array_like}
+            Array containing numbers whose mean is desired. If a is not an
+            array, a conversion is attempted.
+        axis : {None, integer}, optional
             Axis along which the means are computed. The default is to compute
             the standard deviation of the flattened array.
-        dtype : type
+        dtype : {None, dtype}, optional
             Type to use in computing the means. For arrays of integer type the
             default is float32, for arrays of float types it is the same as the
             array type.
-        out : ndarray
+        out : {None, array}, optional
             Alternative output array in which to place the result. It must have
             the same shape as the expected output but the type will be cast if
             necessary.
 
     *Returns*:
 
-        mean : array (see dtype parameter above)
-            A new array holding the result is returned unless out is specified,
-            in which case a reference to out is returned.
+        mean : {array, scalar}, see dtype parameter above
+            If out=None, returns a new array containing the mean values,
+            otherwise a reference to the output array is returned.
 
     *See Also*:
 
@@ -1378,6 +1379,16 @@
         The mean is the sum of the elements along the axis divided by the number
         of elements.
 
+    *Examples*
+
+        >>> a = array([[1,2],[3,4]])
+        >>> mean(a)
+        2.5
+        >>> mean(a,0)
+        array([ 2.,  3.])
+        >>> mean(a,1)
+        array([ 1.5,  3.5])
+
     """
     try:
         mean = a.mean
@@ -1395,23 +1406,26 @@
 
     *Parameters*:
 
-        axis : integer
+        a : {array_like}
+            Array containing numbers whose standard deviation is desired. If a
+            is not an array, a conversion is attempted.
+        axis : {None, integer}, optional
             Axis along which the standard deviation is computed. The default is
             to compute the standard deviation of the flattened array.
-        dtype : type
+        dtype : {None, dtype}, optional
             Type to use in computing the standard deviation. For arrays of
             integer type the default is float32, for arrays of float types it is
             the same as the array type.
-        out : ndarray
+        out : {None, array}, optional
             Alternative output array in which to place the result. It must have
             the same shape as the expected output but the type will be cast if
             necessary.
 
     *Returns*:
 
-        standard_deviation : The return type varies, see above.
-            A new array holding the result is returned unless out is specified,
-            in which case a reference to out is returned.
+        standard_deviation : {array, scalar}, see dtype parameter above.
+            If out=None, returns a new array containing the standard deviation,
+            otherwise a reference to the output array is returned.
 
     *See Also*:
 
@@ -1419,13 +1433,23 @@
 
         `mean` : Average
 
-    *Notes*:
+    *Notes*
 
         The standard deviation is the square root of the average of the squared
         deviations from the mean, i.e. var = sqrt(mean((x - x.mean())**2)).  The
         computed standard deviation is biased, i.e., the mean is computed by
         dividing by the number of elements, N, rather than by N-1.
 
+    *Examples*
+
+        >>> a = array([[1,2],[3,4]])
+        >>> std(a)
+        1.1180339887498949
+        >>> std(a,0)
+        array([ 1.,  1.])
+        >>> std(a,1)
+        array([ 0.5,  0.5])
+
     """
     try:
         std = a.std
@@ -1438,28 +1462,31 @@
     """Compute the variance along the specified axis.
 
     Returns the variance of the array elements, a measure of the spread of a
-    distribution.  The variance is computed for the flattened array by default,
+    distribution. The variance is computed for the flattened array by default,
     otherwise over the specified axis.
 
     *Parameters*:
 
-        axis : integer
+        a : {array_like}
+            Array containing numbers whose variance is desired. If a is not an
+            array, a conversion is attempted.
+        axis : {None, integer}, optional
             Axis along which the variance is computed. The default is to compute
             the variance of the flattened array.
-        dtype : type
+        dtype : {None, dtype}, optional
             Type to use in computing the variance. For arrays of integer type
             the default is float32, for arrays of float types it is the same as
             the array type.
-        out : ndarray
+        out : {None, array}, optional
             Alternative output array in which to place the result. It must have
             the same shape as the expected output but the type will be cast if
             necessary.
 
     *Returns*:
 
-        variance : array (see dtype parameter above)
-            A new array holding the result is returned unless out is specified,
-            in which case a reference to out is returned.
+        variance : {array, scalar}, see dtype parameter above
+            If out=None, returns a new array containing the variance, otherwise
+            a reference to the output array is returned.
 
     *See Also*:
 
@@ -1474,6 +1501,16 @@
         i.e., the mean is computed by dividing by the number of elements, N,
         rather than by N-1.
 
+    *Examples*
+
+        >>> a = array([[1,2],[3,4]])
+        >>> var(a)
+        1.25
+        >>> var(a,0)
+        array([ 1.,  1.])
+        >>> var(a,1)
+        array([ 0.25,  0.25])
+
     """
     try:
         var = a.var



More information about the Numpy-svn mailing list