# [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 @@

"""
-    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)
+
""")

@@ -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.

--------
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.
+
--------
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.
-
--------
-    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.

--------
-    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.

@@ -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.

--------

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 @@
--------
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.

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.