[Numpy-svn] r5965 - in branches/1.2.x/numpy: core core/code_generators lib random/mtrand
numpy-svn at scipy.org
numpy-svn at scipy.org
Mon Oct 27 20:38:55 EDT 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