[Numpy-svn] r5965 - in branches/1.2.x/numpy: core core/code_generators lib random/mtrand

numpy-svn@scip... numpy-svn@scip...
Mon Oct 27 19:38:55 CDT 2008


Author: ptvirtan
Date: 2008-10-27 19:38:35 -0500 (Mon, 27 Oct 2008)
New Revision: 5965

Modified:
   branches/1.2.x/numpy/core/code_generators/docstrings.py
   branches/1.2.x/numpy/core/defmatrix.py
   branches/1.2.x/numpy/core/fromnumeric.py
   branches/1.2.x/numpy/core/numeric.py
   branches/1.2.x/numpy/lib/function_base.py
   branches/1.2.x/numpy/lib/polynomial.py
   branches/1.2.x/numpy/lib/twodim_base.py
   branches/1.2.x/numpy/random/mtrand/mtrand.pyx
Log:
1.2.x: Backport r5962: improved docstrings from trunk (part 1)

Modified: branches/1.2.x/numpy/core/code_generators/docstrings.py
===================================================================
--- branches/1.2.x/numpy/core/code_generators/docstrings.py	2008-10-28 00:24:27 UTC (rev 5964)
+++ branches/1.2.x/numpy/core/code_generators/docstrings.py	2008-10-28 00:38:35 UTC (rev 5965)
@@ -11,22 +11,20 @@
 
 add_newdoc('numpy.core.umath', 'absolute',
     """
-    Calculate the absolute value elementwise.
+    Calculate the absolute value element-wise.
 
     Parameters
     ----------
     x : array_like
-        An array-like sequence of values or a scalar.
+        Input array.
 
     Returns
     -------
-    res : {ndarray, scalar}
+    res : ndarray
         An ndarray containing the absolute value of
         each element in `x`.  For complex input, ``a + ib``, the
         absolute value is :math:`\\sqrt{ a^2 + b^2 }`.
 
-        Returns a scalar for scalar input.
-
     Examples
     --------
     >>> x = np.array([-1.2, 1.2])
@@ -1126,6 +1124,13 @@
     >>> np.greater([4,2],[2,2])
     array([ True, False], dtype=bool)
 
+    If the inputs are ndarrays, then np.greater is equivalent to '>'.
+
+    >>> a = np.array([4,2])
+    >>> b = np.array([2,2])
+    >>> a > b
+    array([ True, False], dtype=bool)
+
     """)
 
 add_newdoc('numpy.core.umath', 'greater_equal',
@@ -2104,14 +2109,15 @@
     Returns
     -------
     y : ndarray
-        The square-root of each element in `x`.  If any element in `x`
+        An array of the same shape as `x`, containing the square-root of
+        each element in `x`.  If any element in `x`
         is complex, a complex array is returned.  If all of the elements
-        of `x` are real, negative elements will return numpy.nan elements.
+        of `x` are real, negative elements return numpy.nan elements.
 
     See Also
     --------
     numpy.lib.scimath.sqrt
-        A version which will return complex numbers when given negative reals.
+        A version which returns complex numbers when given negative reals.
 
     Notes
     -----

Modified: branches/1.2.x/numpy/core/defmatrix.py
===================================================================
--- branches/1.2.x/numpy/core/defmatrix.py	2008-10-28 00:24:27 UTC (rev 5964)
+++ branches/1.2.x/numpy/core/defmatrix.py	2008-10-28 00:38:35 UTC (rev 5965)
@@ -590,6 +590,11 @@
         Input data.  Variables names in the current scope may
         be referenced, even if `obj` is a string.
 
+    Returns
+    -------
+    out : matrix
+        Returns a matrix object, which is a specialized 2-D array.
+
     See Also
     --------
     matrix

Modified: branches/1.2.x/numpy/core/fromnumeric.py
===================================================================
--- branches/1.2.x/numpy/core/fromnumeric.py	2008-10-28 00:24:27 UTC (rev 5964)
+++ branches/1.2.x/numpy/core/fromnumeric.py	2008-10-28 00:38:35 UTC (rev 5965)
@@ -294,7 +294,7 @@
     Returns
     -------
     a_swapped : ndarray
-        If `a` is an ndarray, then a view on `a` is returned, otherwise
+        If `a` is an ndarray, then a view of `a` is returned; otherwise
         a new array is created.
 
     Examples
@@ -1176,11 +1176,9 @@
     """
     Return the product of array elements over a given axis.
 
-    Refer to `numpy.prod` for full documentation.
-
     See Also
     --------
-    prod : equivalent function
+    prod : equivalent function; see for details.
 
     """
     try:
@@ -1390,11 +1388,10 @@
     """
     Return the cumulative product over the given axis.
 
-    See `cumprod` for full documentation.
 
     See Also
     --------
-    cumprod
+    cumprod : equivalent function; see for details.
 
     """
     try:
@@ -1449,7 +1446,7 @@
 
 def amax(a, axis=None, out=None):
     """
-    Return the maximum along a given axis.
+    Return the maximum along an axis.
 
     Parameters
     ----------
@@ -1463,19 +1460,19 @@
 
     Returns
     -------
-    amax : {ndarray, scalar}
+    amax : ndarray
         A new array or a scalar with the result, or a reference to `out`
         if it was specified.
 
     Examples
     --------
-    >>> x = np.arange(4).reshape((2,2))
-    >>> x
+    >>> a = np.arange(4).reshape((2,2))
+    >>> a
     array([[0, 1],
            [2, 3]])
-    >>> np.amax(x,0)
+    >>> np.amax(a, axis=0)
     array([2, 3])
-    >>> np.amax(x,1)
+    >>> np.amax(a, axis=1)
     array([1, 3])
 
     """
@@ -1488,7 +1485,7 @@
 
 def amin(a, axis=None, out=None):
     """
-    Return the minimum along a given axis.
+    Return the minimum along an axis.
 
     Parameters
     ----------
@@ -1502,19 +1499,21 @@
 
     Returns
     -------
-    amin : {ndarray, scalar}
+    amin : ndarray
         A new array or a scalar with the result, or a reference to `out` if it
         was specified.
 
     Examples
     --------
-    >>> x = np.arange(4).reshape((2,2))
-    >>> x
+    >>> a = np.arange(4).reshape((2,2))
+    >>> a
     array([[0, 1],
            [2, 3]])
-    >>> np.amin(x,0)
+    >>> np.amin(a)           # Minimum of the flattened array
+    0
+    >>> np.amin(a, axis=0)         # Minima along the first axis
     array([0, 1])
-    >>> np.amin(x,1)
+    >>> np.amin(a, axis=1)         # Minima along the second axis
     array([0, 2])
 
     """
@@ -1638,7 +1637,7 @@
 
     Parameters
     ----------
-    a : array-like
+    a : array_like
         Input array.
     axis : int, optional
         Axis along which the cumulative product is computed.  By default the
@@ -1656,7 +1655,7 @@
 
     Returns
     -------
-    cumprod : ndarray.
+    cumprod : ndarray
         A new array holding the result is returned unless `out` is
         specified, in which case a reference to out is returned.
 
@@ -1923,21 +1922,21 @@
     a : array_like
         Array containing numbers whose mean is desired. If `a` is not an
         array, a conversion is attempted.
-    axis : {None, int}, optional
+    axis : int, optional
         Axis along which the means are computed. The default is to compute
         the mean of the flattened array.
-    dtype : {None, dtype}, optional
-        Type to use in computing the mean. For integer inputs the default
-        is float64; for floating point inputs it is the same as the input
+    dtype : dtype, optional
+        Type to use in computing the mean. For integer inputs, the default
+        is float64; for floating point, inputs it is the same as the input
         dtype.
-    out : {None, ndarray}, optional
+    out : ndarray, 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 : {ndarray, scalar}, see dtype parameter above
+    mean : ndarray, see dtype parameter above
         If `out=None`, returns a new array containing the mean values,
         otherwise a reference to the output array is returned.
 
@@ -2048,27 +2047,27 @@
     Parameters
     ----------
     a : array_like
-        Array containing numbers whose variance is desired. If a is not an
+        Array containing numbers whose variance is desired. If `a` is not an
         array, a conversion is attempted.
     axis : int, optional
         Axis along which the variance is computed. The default is to compute
         the variance of the flattened array.
     dtype : 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 default is float32; for arrays of float types it is the same as
         the array type.
     out : ndarray, 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
+        the same shape as the expected output but the type is cast if
         necessary.
     ddof : positive int,optional
-        Means Delta Degrees of Freedom.  The divisor used in calculation is
+        "Delta Degrees of Freedom": the divisor used in calculation is
         N - ddof.
 
     Returns
     -------
-    variance : {ndarray, scalar}, see dtype parameter above
-        If out=None, returns a new array containing the variance, otherwise
+    variance : ndarray, 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
@@ -2079,7 +2078,7 @@
     Notes
     -----
     The variance is the average of the squared deviations from the mean,
-    i.e.  var = mean(abs(x - x.mean())**2).  The computed variance is biased,
+    i.e.,  var = mean(abs(x - x.mean())**2).  The computed variance is biased,
     i.e., the mean is computed by dividing by the number of elements, N,
     rather than by N-1. Note that for complex numbers the absolute value is
     taken before squaring, so that the result is always real and nonnegative.

Modified: branches/1.2.x/numpy/core/numeric.py
===================================================================
--- branches/1.2.x/numpy/core/numeric.py	2008-10-28 00:24:27 UTC (rev 5964)
+++ branches/1.2.x/numpy/core/numeric.py	2008-10-28 00:38:35 UTC (rev 5965)
@@ -687,20 +687,18 @@
 except ImportError:
     def alterdot():
         """
-        Change `dot`, `vdot`, and `innerproduct` to use accelerated BLAS
-        functions.
+        Change `dot`, `vdot`, and `innerproduct` to use accelerated BLAS functions.
 
-        When numpy is built with an accelerated BLAS like ATLAS, the above
-        functions will be replaced to make use of the faster implementations.
-        The faster implementations only affect float32, float64, complex64, and
-        complex128 arrays. Furthermore, only matrix-matrix, matrix-vector, and
-        vector-vector products are accelerated. Products of arrays with larger
-        dimensionalities will not be accelerated since the BLAS API only
-        includes these.
+        Typically, as a user of Numpy, you do not explicitly call this function. If
+        Numpy is built with an accelerated BLAS, this function is automatically
+        called when Numpy is imported.
 
-        Typically, the user will never have to call this function. If numpy was
-        built with an accelerated BLAS, this function will be called when numpy
-        is imported.
+        When Numpy is built with an accelerated BLAS like ATLAS, these functions
+        are replaced to make use of the faster implementations.  The faster
+        implementations only affect float32, float64, complex64, and complex128
+        arrays. Furthermore, the BLAS API only includes matrix-matrix,
+        matrix-vector, and vector-vector products. Products of arrays with larger
+        dimensionalities use the built in functions and are not accelerated.
 
         See Also
         --------

Modified: branches/1.2.x/numpy/lib/function_base.py
===================================================================
--- branches/1.2.x/numpy/lib/function_base.py	2008-10-28 00:24:27 UTC (rev 5964)
+++ branches/1.2.x/numpy/lib/function_base.py	2008-10-28 00:38:35 UTC (rev 5965)
@@ -1128,6 +1128,17 @@
     >>> np.interp(3.14, xp, fp, right=UNDEF)
     -99.0
 
+    Plot an interpolant to the sine function:
+
+    >>> x = np.linspace(0, 2*np.pi, 10)
+    >>> y = np.sin(x)
+    >>> xvals = np.linspace(0, 2*np.pi, 50)
+    >>> yinterp = np.interp(xvals, x, y)
+    >>> import matplotlib.pyplot as plt
+    >>> plt.plot(x, y, 'o')
+    >>> plt.plot(xvals, yinterp, '-x')
+    >>> plt.show()
+
     """
     if isinstance(x, (float, int, number)):
         return compiled_interp([x], xp, fp, left, right).item()

Modified: branches/1.2.x/numpy/lib/polynomial.py
===================================================================
--- branches/1.2.x/numpy/lib/polynomial.py	2008-10-28 00:24:27 UTC (rev 5964)
+++ branches/1.2.x/numpy/lib/polynomial.py	2008-10-28 00:38:35 UTC (rev 5965)
@@ -277,7 +277,7 @@
 
 def polyder(p, m=1):
     """
-    Return the derivative of order m of a polynomial.
+    Return the derivative of the specified order of a polynomial.
 
     Parameters
     ----------
@@ -295,6 +295,7 @@
     See Also
     --------
     polyint : Anti-derivative of a polynomial.
+    poly1d : Class for one-dimensional polynomials.
 
     Examples
     --------

Modified: branches/1.2.x/numpy/lib/twodim_base.py
===================================================================
--- branches/1.2.x/numpy/lib/twodim_base.py	2008-10-28 00:24:27 UTC (rev 5964)
+++ branches/1.2.x/numpy/lib/twodim_base.py	2008-10-28 00:38:35 UTC (rev 5965)
@@ -165,14 +165,14 @@
       Number of columns in the output. If None, defaults to `N`.
     k : int, optional
       Index of the diagonal: 0 refers to the main diagonal, a positive value
-      refers to an upper diagonal and a negative value to a lower diagonal.
+      refers to an upper diagonal, and a negative value to a lower diagonal.
     dtype : dtype, optional
       Data-type of the returned array.
 
     Returns
     -------
     I : ndarray (N,M)
-      An array where all elements are equal to zero, except for the k'th
+      An array where all elements are equal to zero, except for the `k`-th
       diagonal, whose values are equal to one.
 
     See Also

Modified: branches/1.2.x/numpy/random/mtrand/mtrand.pyx
===================================================================
--- branches/1.2.x/numpy/random/mtrand/mtrand.pyx	2008-10-28 00:24:27 UTC (rev 5964)
+++ branches/1.2.x/numpy/random/mtrand/mtrand.pyx	2008-10-28 00:38:35 UTC (rev 5965)
@@ -1902,7 +1902,7 @@
         """
         lognormal(mean=0.0, sigma=1.0, size=None)
 
-        Log-normal distribution.
+        Return samples drawn from a log-normal distribution.
 
         Draw samples from a log-normal distribution with specified mean, standard
         deviation, and shape. Note that the mean and standard deviation are not the
@@ -1938,7 +1938,7 @@
         where :math:`\\mu` is the mean and :math:`\\sigma` is the standard deviation
         of the normally distributed logarithm of the variable.
 
-        A log normal distribution results if a random variable is the *product* of
+        A log-normal distribution results if a random variable is the *product* of
         a large number of independent, identically-distributed variables in the
         same way that a normal distribution results if the variable is the *sum*
         of a large number of independent, identically-distributed variables
@@ -1947,7 +1947,7 @@
 
         The log-normal distribution is commonly used to model the lifespan of units
         with fatigue-stress failure modes. Since this includes
-        most mechanical systems, the lognormal distribution has widespread
+        most mechanical systems, the log-normal distribution has widespread
         application.
 
         It is also commonly used to model oil field sizes, species abundance, and
@@ -1986,7 +1986,7 @@
         >>> plt.show()
 
         Demonstrate that taking the products of random samples from a uniform
-        distribution can be fit well by a log-normal pdf.
+        distribution can be fit well by a log-normal probability density function.
 
         >>> # Generate a thousand samples: each is the product of 100 random
         >>> # values, drawn from a normal distribution.



More information about the Numpy-svn mailing list