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

numpy-svn@scip... numpy-svn@scip...
Thu Sep 13 22:46:01 CDT 2007


Author: charris
Date: 2007-09-13 22:45:59 -0500 (Thu, 13 Sep 2007)
New Revision: 4035

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


Modified: trunk/numpy/core/fromnumeric.py
===================================================================
--- trunk/numpy/core/fromnumeric.py	2007-09-13 21:43:16 UTC (rev 4034)
+++ trunk/numpy/core/fromnumeric.py	2007-09-14 03:45:59 UTC (rev 4035)
@@ -112,7 +112,7 @@
 
     *See Also*:
 
-        `numpy.ndarray.reshape` : Equivalent method.
+        `ndarray.reshape` : Equivalent method.
 
     """
     try:
@@ -156,7 +156,7 @@
 
     *See Also*:
 
-        `numpy.ndarray.choose` : equivalent method
+        `ndarray.choose` : equivalent method
 
     *Examples*
 
@@ -200,7 +200,7 @@
 
     *See Also*:
 
-        `numpy.ndarray.repeat` : equivalent method
+        `ndarray.repeat` : equivalent method
 
     *Examples*
 
@@ -844,7 +844,7 @@
         a : array_type
 
         axis : {None, integer}
-            Axis over which the sums are taken. If None is used, then the sum is
+            Axis over which the sum is taken. If None is used, then the sum is
             over all the array elements.
 
         dtype : {None, dtype}, optional
@@ -860,20 +860,24 @@
 
     *Returns*:
 
-        Sum along specified axis : {array, scalar}, type as explained above.
+        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.
 
+    *See Also*:
+
+        `ndarray.sum` : equivalent method
+
     *Examples*
 
-        >>> N.sum([0.5, 1.5])
+        >>> sum([0.5, 1.5])
         2.0
-        >>> N.sum([0.5, 1.5], dtype=N.int32)
+        >>> sum([0.5, 1.5], dtype=N.int32)
         1
-        >>> N.sum([[0, 1], [0, 5]])
+        >>> sum([[0, 1], [0, 5]])
         6
-        >>> N.sum([[0, 1], [0, 5]], axis=1)
+        >>> sum([[0, 1], [0, 5]], axis=1)
         array([1, 5])
 
     """
@@ -893,8 +897,48 @@
 def product (a, axis=None, dtype=None, out=None):
     """Product of the array elements over the given axis.
 
-    Blah, Blah.
+    *Parameters*:
 
+        a : array_type
+
+        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.
+
+        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.
+
+    *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.
+
+    *See Also*:
+
+        `ndarray.prod` : equivalent method
+
+    *Examples*
+
+        >>> product([1.,2.])
+        2.0
+        >>> product([1.,2.], dtype=int32)
+        2
+        >>> product([[1.,2.],[3.,4.]])
+        24.0
+        >>> product([[1.,2.],[3.,4.]], axis=1)
+        array([  2.,  12.])
+
+
     """
     try:
         prod = a.prod
@@ -906,8 +950,10 @@
 def sometrue (a, axis=None, out=None):
     """Perform a logical_or over the given axis.
 
-    Blah, Blah.
+    *See Also*:
 
+        `ndarray.any` : equivalent method
+
     """
     try:
         any = a.any
@@ -919,8 +965,12 @@
 def alltrue (a, axis=None, out=None):
     """Perform a logical_and over the given axis.
 
-    Blah, Blah.
+    *See Also*:
 
+        `ndarray.all` : equivalent method
+
+        `all` : equivalent function
+
     """
     try:
         all = a.all
@@ -932,8 +982,10 @@
 def any(a,axis=None, out=None):
     """Return true if any elements of x are true.
 
-    Blah, Blah.
+    *See Also*:
 
+        `ndarray.any` : equivalent method
+
     """
     try:
         any = a.any
@@ -945,8 +997,12 @@
 def all(a,axis=None, out=None):
     """Return true if all elements of x are true:
 
-    Blah, Blah.
+    *See Also*:
 
+        `ndarray.all` : equivalent method
+
+        `alltrue` : equivalent function
+
     """
     try:
         all = a.all
@@ -1062,8 +1118,38 @@
 def ndim(a):
     """Return the number of dimensions of a.
 
-    Blah, Blah.
+    If a is not already an array, a conversion is attempted. Scalars are zero
+    dimensional.
 
+    *Parameters*:
+
+        a : array_like
+            Array_like object whose dimensions are counted.
+
+    *Returns*:
+
+        number of dimensions : int
+            Just so.
+
+    *See Also*:
+
+        `rank` : equivalent function.
+
+        `ndarray.ndim` : equivalent method
+
+        `shape` : dimensions of array
+
+        `ndarray.shape` : dimensions of array
+
+    *Examples*
+
+        >>> ndim([[1,2,3],[4,5,6]])
+        2
+        >>> ndim(array([[1,2,3],[4,5,6]]))
+        2
+        >>> ndim(1)
+        0
+
     """
     try:
         return a.ndim
@@ -1072,11 +1158,41 @@
 
 
 def rank(a):
-    """Return the rank of sequence a (the number of dimensions, not
-    the matrix rank).  The rank of a scalar is zero.
+    """Return the number of dimensions of a.
 
-    Blah, Blah.
+    In old Numeric, rank was the term used for the number of dimensions. If a is
+    not already an array, a conversion is attempted. Scalars are zero
+    dimensional.
 
+    *Parameters*:
+
+        a : array_like
+            Array_like object whose dimensions are counted.
+
+    *Returns*:
+
+        number of dimensions : int
+            Just so.
+
+    *See Also*:
+
+        `ndim` : equivalent function
+
+        `ndarray.ndim` : equivalent method
+
+        `shape` : dimensions of array
+
+        `ndarray.shape` : dimensions of array
+
+    *Examples*
+
+        >>> rank([[1,2,3],[4,5,6]])
+        2
+        >>> rank(array([[1,2,3],[4,5,6]]))
+        2
+        >>> rank(1)
+        0
+
     """
     try:
         return a.ndim
@@ -1085,12 +1201,39 @@
 
 
 def size(a, axis=None):
-    """Return the number of elements in sequence a, or along a given axis.
+    """Return the number of elements along given axis.
 
-    Blah, Blah.
+    *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.
+
+    *Returns*:
+
+        element count : int
+            Count of elements.
+
+    *See Also*:
+
+        `shape` : dimensions of array
+
+        `ndarray.shape` : dimensions of array
+
+        `ndarray.size` : number of elements in array
+
+    *Examples*
+
+        >>> a = array([[1,2,3],[4,5,6]])
+        >>> size(a)
+        6
+        >>> size(a,1)
+        3
+        >>> size(a,0)
+        2
+
     """
-
     if axis is None:
         try:
             return a.size
@@ -1103,6 +1246,53 @@
             return asarray(a).shape[axis]
 
 
+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.
+
+    *Parameters*:
+
+        a : array_like
+
+        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).
+
+    *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.
+
+    *See Also*:
+
+        `round_` : equivalent function
+
+        `ndarray.round` : equivalent method
+
+    *Notes*
+
+        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.
+
+    """
+    try:
+        round = a.round
+    except AttributeError:
+        return _wrapit(a, 'round', decimals, out)
+    return round(decimals, out)
+
+
 def round_(a, decimals=0, out=None):
     """Round a to the given number of decimals.
 
@@ -1111,6 +1301,8 @@
 
     *Parameters*:
 
+        a : array_like
+
         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.
@@ -1128,8 +1320,10 @@
 
     *See Also*:
 
-        `around` : alias of this function
+        `around` : equivalent function
 
+        `ndarray.round` : equivalent method
+
     *Notes*
 
         Numpy rounds to even. Thus 1.5 and 2.5 round to 2.0, -0.5 and 0.5 round
@@ -1273,7 +1467,7 @@
 
         `mean` : Average
 
-    *Notes*:
+    *Notes*
 
         The variance is the average of the squared deviations from the mean,
         i.e.  var = mean((x - x.mean())**2).  The computed variance is biased,
@@ -1286,8 +1480,3 @@
     except AttributeError:
         return _wrapit(a, 'var', axis, dtype, out)
     return var(axis, dtype, out)
-
-# functions that are now aliases
-
-around = round_
-



More information about the Numpy-svn mailing list