[Numpy-svn] r8583 - branches/1.5.x/numpy/lib

numpy-svn@scip... numpy-svn@scip...
Sun Aug 1 06:21:38 CDT 2010

Author: rgommers
Date: 2010-08-01 06:21:38 -0500 (Sun, 01 Aug 2010)
New Revision: 8583

Modified:
branches/1.5.x/numpy/lib/format.py
branches/1.5.x/numpy/lib/function_base.py
branches/1.5.x/numpy/lib/npyio.py
Log:
DOC: wiki merge, npyio, format and function_base

Modified: branches/1.5.x/numpy/lib/format.py
===================================================================
--- branches/1.5.x/numpy/lib/format.py	2010-08-01 11:21:13 UTC (rev 8582)
+++ branches/1.5.x/numpy/lib/format.py	2010-08-01 11:21:38 UTC (rev 8583)
@@ -366,19 +366,19 @@
"""
Write an array to an NPY file, including a header.

-    If the array is neither C-contiguous or Fortran-contiguous AND if the
-    filelike object is not a real file object, then this function will have
-    to copy data in memory.
+    If the array is neither C-contiguous nor Fortran-contiguous AND the
+    file_like object is not a real file object, this function will have to
+    copy data in memory.

Parameters
----------
-    fp : filelike object
-        An open, writable file object or similar object with a .write()
+    fp : file_like object
+        An open, writable file object, or similar object with a .write()
method.
-    array : numpy.ndarray
+    array : ndarray
The array to write to disk.
version : (int, int), optional
-        The version number of the format.
+        The version number of the format.  Default: (1, 0)

Raises
------
@@ -386,7 +386,7 @@
If the array cannot be persisted.
Various other errors
If the array contains Python objects as part of its dtype, the
-        process of pickling them may raise arbitrary errors if the objects
+        process of pickling them may raise various errors if the objects
are not picklable.

"""
@@ -418,13 +418,13 @@

Parameters
----------
-    fp : filelike object
-        If this is not a real file object, then this may take extra memory and
-        time.
+    fp : file_like object
+        If this is not a real file object, then this may take extra memory
+        and time.

Returns
-------
-    array : numpy.ndarray
+    array : ndarray
The array from the data on disk.

Raises
@@ -477,27 +477,31 @@
Parameters
----------
filename : str
-        The name of the file on disk. This may not be a file-like object.
+        The name of the file on disk.  This may *not* be a file-like
+        object.
mode : str, optional
-        The mode to open the file with. In addition to the standard file modes,
-        'c' is also accepted to mean "copy on write". See numpy.memmap for
-        the available mode strings.
-    dtype : dtype, optional
+        The mode in which to open the file; the default is 'r+'.  In
+        addition to the standard file modes, 'c' is also accepted to
+        mean "copy on write."  See memmap for the available mode strings.
+    dtype : data-type, optional
The data type of the array if we are creating a new file in "write"
-        mode.
-    shape : tuple of int, optional
+        mode, if not, dtype is ignored.  The default value is None,
+        which results in a data-type of float64.
+    shape : tuple of int
The shape of the array if we are creating a new file in "write"
-        mode.
+        mode, in which case this parameter is required.  Otherwise, this
+        parameter is ignored and is thus optional.
fortran_order : bool, optional
Whether the array should be Fortran-contiguous (True) or
-        C-contiguous (False) if we are creating a new file in "write" mode.
+        C-contiguous (False, the default) if we are creating a new file
+        in "write" mode.
version : tuple of int (major, minor)
If the mode is a "write" mode, then this is the version of the file
-        format used to create the file.
+        format used to create the file.  Default: (1,0)

Returns
-------
-    marray : numpy.memmap
+    marray : memmap
The memory-mapped array.

Raises
@@ -509,7 +513,7 @@

--------
-    numpy.memmap
+    memmap

"""
if not isinstance(filename, basestring):

Modified: branches/1.5.x/numpy/lib/function_base.py
===================================================================
--- branches/1.5.x/numpy/lib/function_base.py	2010-08-01 11:21:13 UTC (rev 8582)
+++ branches/1.5.x/numpy/lib/function_base.py	2010-08-01 11:21:38 UTC (rev 8583)
@@ -29,9 +29,31 @@
from utils import deprecate
import numpy as np

-#end Fernando's utilities

def iterable(y):
+    """
+    Check whether or not an object can be iterated over.
+
+    Parameters
+    ----------
+    y : object
+      Input object.
+
+    Returns
+    -------
+    b : {0, 1}
+      Return 1 if the object has an iterator method or is a sequence,
+      and 0 otherwise.
+
+
+    Examples
+    --------
+    >>> np.iterable([1, 2, 3])
+    1
+    >>> np.iterable(2)
+    0
+
+    """
try: iter(y)
except: return 0
return 1
@@ -1237,7 +1259,7 @@
"""
Change elements of an array based on conditional and input values.

-    Similar to np.putmask(a, mask, vals), the difference is that place
+    Similar to np.putmask(arr, mask, vals), the difference is that place
uses the first N elements of vals, where N is the number of True values
in mask, while putmask uses the elements where mask is True.

@@ -1245,7 +1267,7 @@

Parameters
----------
-    a : array_like
+    arr : array_like
Array to put data into.
Boolean mask array. Must have the same size as a.
@@ -1260,9 +1282,9 @@

Examples
--------
-    >>> x = np.arange(6).reshape(2, 3)
-    >>> np.place(x, x>2, [44, 55])
-    >>> x
+    >>> arr = np.arange(6).reshape(2, 3)
+    >>> np.place(arr, arr>2, [44, 55])
+    >>> arr
array([[ 0,  1,  2],
[44, 55, 44]])

@@ -1936,12 +1958,12 @@
Return correlation coefficients.

Please refer to the documentation for cov for more detail.  The
-    relationship between the correlation coefficient matrix, P, and the
-    covariance matrix, C, is
+    relationship between the correlation coefficient matrix, P, and the
+    covariance matrix, C, is

.. math:: P_{ij} = \\frac{ C_{ij} } { \\sqrt{ C_{ii} * C_{jj} } }

-    The values of P are between -1 and 1.
+    The values of P are between -1 and 1, inclusive.

Parameters
----------
@@ -1989,22 +2011,22 @@
"""
Return the Blackman window.

-    The Blackman window is a taper formed by using the the first
-    three terms of a summation of cosines. It was designed to have close
-    to the minimal leakage possible.
-    It is close to optimal, only slightly worse than a Kaiser window.
+    The Blackman window is a taper formed by using the the first three
+    terms of a summation of cosines. It was designed to have close to the
+    minimal leakage possible.  It is close to optimal, only slightly worse
+    than a Kaiser window.

Parameters
----------
M : int
-        Number of points in the output window. If zero or less, an
-        empty array is returned.
+        Number of points in the output window. If zero or less, an empty
+        array is returned.

Returns
-------
-    out : array
-        The window, normalized to one (the value one
-        appears only if the number of samples is odd).
+    out : ndarray
+        The window, normalized to one (the value one appears only if the
+        number of samples is odd).

--------
@@ -2016,7 +2038,6 @@

.. math::  w(n) = 0.42 - 0.5 \\cos(2\\pi n/M) + 0.08 \\cos(4\\pi n/M)

-
Most references to the Blackman window come from the signal processing
literature, where it is used as one of many windowing functions for
smoothing values.  It is also known as an apodization (which means
@@ -2027,13 +2048,12 @@

References
----------
-    .. [1] Blackman, R.B. and Tukey, J.W., (1958) The measurement of power
-           spectra, Dover Publications, New York.
-    .. [2] Wikipedia, "Window function",
-           http://en.wikipedia.org/wiki/Window_function
-    .. [3] Oppenheim, A.V., and R.W. Schafer. Discrete-Time Signal Processing.
-           Upper Saddle River, NJ: Prentice-Hall, 1999, pp. 468-471.
+    Blackman, R.B. and Tukey, J.W., (1958) The measurement of power spectra,
+    Dover Publications, New York.

+    Oppenheim, A.V., and R.W. Schafer. Discrete-Time Signal Processing.
+    Upper Saddle River, NJ: Prentice-Hall, 1999, pp. 468-471.
+
Examples
--------
>>> from numpy import blackman

Modified: branches/1.5.x/numpy/lib/npyio.py
===================================================================
--- branches/1.5.x/numpy/lib/npyio.py	2010-08-01 11:21:13 UTC (rev 8582)
+++ branches/1.5.x/numpy/lib/npyio.py	2010-08-01 11:21:38 UTC (rev 8583)
@@ -367,7 +367,7 @@

def savez(file, *args, **kwds):
"""
-    Save several arrays into a single, compressed file in .npz format.
+    Save several arrays into a single, archive file in .npz format.

If arguments are passed in with no keywords, the corresponding variable
names, in the .npz file, are 'arr_0', 'arr_1', etc. If keyword arguments
@@ -401,8 +401,9 @@
Notes
-----
The .npz file format is a zipped archive of files named after the
-    variables they contain.  Each file contains one variable in .npy
-    format. For a description of the .npy format, see format.
+    variables they contain.  The archive is not compressed and each file
+    in the archive contains one variable in .npy format. For a
+    description of the .npy format, see format.

When opening the saved .npz file with load a NpzFile object is
returned. This is a dictionary-like object which can be queried for
@@ -509,30 +510,32 @@
fname : file or str
File or filename to read.  If the filename extension is .gz or
.bz2, the file is first decompressed.
-    dtype : dtype, optional
-        Data type of the resulting array.  If this is a record data-type,
-        the resulting array will be 1-dimensional, and each row will be
-        interpreted as an element of the array.   In this case, the number
-        of columns used must match the number of fields in the data-type.
+    dtype : data-type, optional
+        Data-type of the resulting array; default: float.  If this is a record
+        data-type, the resulting array will be 1-dimensional, and each row
+        will be interpreted as an element of the array.  In this case, the
+        number of columns used must match the number of fields in the
+        data-type.
-        The character used to indicate the start of a comment.
+        The character used to indicate the start of a comment; default: '#'.
delimiter : str, optional
The string used to separate values.  By default, this is any
whitespace.
converters : dict, optional
A dictionary mapping column number to a function that will convert
that column to a float.  E.g., if column 0 is a date string:
-        converters = {0: datestr2num}. Converters can also be used to
+        converters = {0: datestr2num}.  Converters can also be used to
provide a default value for missing data:
-        converters = {3: lambda s: float(s or 0)}.
+        converters = {3: lambda s: float(s or 0)}.  Default: None.
skiprows : int, optional
-        Skip the first skiprows lines.
+        Skip the first skiprows lines; default: 0.
usecols : sequence, optional
Which columns to read, with 0 being the first.  For example,
usecols = (1,4,5) will extract the 2nd, 5th and 6th columns.
+        The default, None, results in all columns being read.
unpack : bool, optional
If True, the returned array is transposed, so that arguments may be
-        unpacked using x, y, z = loadtxt(...). Default is False.
+        unpacked using x, y, z = loadtxt(...).  The default is False.

Returns
-------
@@ -543,11 +546,11 @@
--------
genfromtxt : Load data with missing values handled as specified.
genfromtxt function provides more sophisticated handling of, e.g.,