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

numpy-svn@scip... numpy-svn@scip...
Wed Feb 20 03:08:01 CST 2008


Author: stefan
Date: 2008-02-20 03:07:45 -0600 (Wed, 20 Feb 2008)
New Revision: 4814

Modified:
   trunk/numpy/core/fromnumeric.py
Log:
Restructure and add to documentation.


Modified: trunk/numpy/core/fromnumeric.py
===================================================================
--- trunk/numpy/core/fromnumeric.py	2008-02-19 23:49:50 UTC (rev 4813)
+++ trunk/numpy/core/fromnumeric.py	2008-02-20 09:07:45 UTC (rev 4814)
@@ -48,33 +48,33 @@
     This function does the same thing as "fancy" indexing; however, it can
     be easier to use if you need to specify a given axis.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : array
+        The source array
+    indices : int array
+        The indices of the values to extract.
+    axis : {None, int}, optional
+        The axis over which to select values. None signifies that the
+        operation should be performed over the flattened array.
+    out : {None, array}, optional
+        If provided, the result will be inserted into this array. It should
+        be of the appropriate shape and dtype.
+    mode : {'raise', 'wrap', 'clip'}, optional
+        Specifies how out-of-bounds indices will behave.
+        'raise' -- raise an error
+        'wrap' -- wrap around
+        'clip' -- clip to the range
 
-        a : array
-            The source array
-        indices : int array
-            The indices of the values to extract.
-        axis : {None, int}, optional
-            The axis over which to select values. None signifies that the
-            operation should be performed over the flattened array.
-        out : {None, array}, optional
-            If provided, the result will be inserted into this array. It should
-            be of the appropriate shape and dtype.
-        mode : {'raise', 'wrap', 'clip'}, optional
-            Specifies how out-of-bounds indices will behave.
-            'raise' -- raise an error
-            'wrap' -- wrap around
-            'clip' -- clip to the range
+    Returns
+    -------
+    subarray : array
+        The returned array has the same type as a.
 
-    *Returns*:
+    See Also
+    --------
+    ndarray.take : equivalent method
 
-        subarray : array
-            The returned array has the same type as a.
-
-    *See Also*:
-
-       `ndarray.take` : equivalent method
-
     """
     try:
         take = a.take
@@ -87,27 +87,27 @@
 def reshape(a, newshape, order='C'):
     """Returns an array containing the data of a, but with a new shape.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : array
+        Array to be reshaped.
+    newshape : shape tuple or int
+       The new shape should be compatible with the original shape. If an
+       integer, then the result will be a 1D array of that length.
+    order : {'C', 'FORTRAN'}, optional
+        Determines whether the array data should be viewed as in C
+        (row-major) order or FORTRAN (column-major) order.
 
-        a : array
-            Array to be reshaped.
-        newshape : shape tuple or int
-           The new shape should be compatible with the original shape. If an
-           integer, then the result will be a 1D array of that length.
-        order : {'C', 'FORTRAN'}, optional
-            Determines whether the array data should be viewed as in C
-            (row-major) order or FORTRAN (column-major) order.
+    Returns
+    -------
+    reshaped_array : array
+        This will be a new view object if possible; otherwise, it will
+        return a copy.
 
-    *Returns*:
+    See Also
+    --------
+    ndarray.reshape : Equivalent method.
 
-        reshaped_array : array
-            This will be a new view object if possible; otherwise, it will
-            return a copy.
-
-    *See Also*:
-
-        `ndarray.reshape` : Equivalent method.
-
     """
     try:
         reshape = a.reshape
@@ -117,49 +117,52 @@
 
 
 def choose(a, choices, out=None, mode='raise'):
-    """Use an index array to construct a new array from a set of choices.
+    """Use an index array to construct a new array from a set of
+    choices.
 
-    Given an array of integers in {0, 1, ..., n-1} and a set of n choice arrays,
-    this function will create a new array that merges each of the choice arrays.
-    Where a value in `a` is i, then the new array will have the value that
-    choices[i] contains in the same place.
+    Given an array of integers in {0, 1, ..., n-1} and a set of n
+    choice arrays, this function will create a new array that merges
+    each of the choice arrays.  Where a value in `a` is i, then the
+    new array will have the value that choices[i] contains in the same
+    place.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : int array
+        This array must contain integers in [0, n-1], where n is the number
+        of choices.
+    choices : sequence of arrays
+        Each of the choice arrays should have the same shape as the index
+        array.
+    out : array, optional
+        If provided, the result will be inserted into this array. It should
+        be of the appropriate shape and dtype
+    mode : {'raise', 'wrap', 'clip'}, optional
+        Specifies how out-of-bounds indices will behave.
+        'raise' : raise an error
+        'wrap' : wrap around
+        'clip' : clip to the range
 
-        a : int array
-            This array must contain integers in [0, n-1], where n is the number
-            of choices.
-        choices : sequence of arrays
-            Each of the choice arrays should have the same shape as the index
-            array.
-        out : array, optional
-            If provided, the result will be inserted into this array. It should
-            be of the appropriate shape and dtype
-        mode : {'raise', 'wrap', 'clip'}, optional
-            Specifies how out-of-bounds indices will behave.
-            'raise' : raise an error
-            'wrap' : wrap around
-            'clip' : clip to the range
+    Returns
+    -------
+    merged_array : array
 
-    *Returns*:
+    See Also
+    --------
+    ndarray.choose : equivalent method
 
-        merged_array : array
+    Examples
+    --------
 
-    *See Also*:
+    >>> choices = [[0, 1, 2, 3], [10, 11, 12, 13],
+    ...   [20, 21, 22, 23], [30, 31, 32, 33]]
+    >>> choose([2, 3, 1, 0], choices)
+    array([20, 31, 12,  3])
+    >>> choose([2, 4, 1, 0], choices, mode='clip')
+    array([20, 31, 12,  3])
+    >>> choose([2, 4, 1, 0], choices, mode='wrap')
+    array([20,  1, 12,  3])
 
-        `ndarray.choose` : equivalent method
-
-    *Examples*
-
-        >>> choices = [[0, 1, 2, 3], [10, 11, 12, 13],
-        ...   [20, 21, 22, 23], [30, 31, 32, 33]]
-        >>> choose([2, 3, 1, 0], choices)
-        array([20, 31, 12,  3])
-        >>> choose([2, 4, 1, 0], choices, mode='clip')
-        array([20, 31, 12,  3])
-        >>> choose([2, 4, 1, 0], choices, mode='wrap')
-        array([20,  1, 12,  3])
-
     """
     try:
         choose = a.choose
@@ -171,34 +174,35 @@
 def repeat(a, repeats, axis=None):
     """Repeat elements of an array.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Input array.
+    repeats : {integer, integer_array}
+        The number of repetitions for each element. If a plain integer, then
+        it is applied to all elements. If an array, it needs to be of the
+        same length as the chosen axis.
+    axis : {None, integer}, optional
+        The axis along which to repeat values. If None, then this function
+        will operated on the flattened array `a` and return a similarly flat
+        result.
 
-        a : {array_like}
-            Input array.
-        repeats : {integer, integer_array}
-            The number of repetitions for each element. If a plain integer, then
-            it is applied to all elements. If an array, it needs to be of the
-            same length as the chosen axis.
-        axis : {None, integer}, optional
-            The axis along which to repeat values. If None, then this function
-            will operated on the flattened array `a` and return a similarly flat
-            result.
+    Returns
+    -------
+    repeated_array : array
 
-    *Returns*:
+    See Also
+    --------
+    ndarray.repeat : equivalent method
 
-        repeated_array : array
+    Examples
+    --------
 
-    *See Also*:
+    >>> repeat([0, 1, 2], 2)
+    array([0, 0, 1, 1, 2, 2])
+    >>> repeat([0, 1, 2], [2, 3, 4])
+    array([0, 0, 1, 1, 1, 2, 2, 2, 2])
 
-        `ndarray.repeat` : equivalent method
-
-    *Examples*
-
-        >>> repeat([0, 1, 2], 2)
-        array([0, 0, 1, 1, 2, 2])
-        >>> repeat([0, 1, 2], [2, 3, 4])
-        array([0, 0, 1, 1, 1, 2, 2, 2, 2])
-
     """
     try:
         repeat = a.repeat
@@ -207,9 +211,20 @@
     return repeat(repeats, axis)
 
 
-def put (a, ind, v, mode='raise'):
+def put(a, ind, v, mode='raise'):
     """Set a[n] = v[n] for all n in ind.
 
+    Parameters
+    ----------
+    a : array_like (contiguous)
+        Target array.
+    ind : array_like
+        Target indices, interpreted as integers.
+    v : array_like
+        Values to place in `a` at target indices.
+
+    Notes
+    -----
     If v is shorter than mask it will be repeated as necessary.  In particular v
     can be a scalar or length 1 array.  The routine put is the equivalent of the
     following (although the loop is in C for speed):
@@ -218,8 +233,14 @@
         v = array(values, copy=False).astype(a.dtype)
         for i in ind: a.flat[i] = v[i]
 
-    a must be a contiguous numpy array.
+    Examples
+    --------
 
+    >>> x = np.arange(5)
+    >>> np.put(x,[0,2,4],[-1,-2,-3])
+    >>> print x
+    [-1  1 -2  3 -3]
+
     """
     return a.put(ind, v, mode)
 
@@ -227,6 +248,38 @@
 def swapaxes(a, axis1, axis2):
     """Return array a with axis1 and axis2 interchanged.
 
+    Parameters
+    ----------
+    a : array_like
+        Input array.
+    axis1 : int
+        First axis.
+    axis2 : int
+        Second axis.
+
+    Examples
+    --------
+
+    >>> x = np.array([[1,2,3]])
+    >>> np.swapaxes(x,0,1)
+    array([[1],
+           [2],
+           [3]])
+
+    >>> x = np.array([[[0,1],[2,3]],[[4,5],[6,7]]])
+    >>> x
+    array([[[0, 1],
+            [2, 3]],
+
+           [[4, 5],
+            [6, 7]]])
+    >>> np.swapaxes(x,0,2)
+    array([[[0, 4],
+            [2, 6]],
+
+           [[1, 5],
+            [3, 7]]])
+
     """
     try:
         swapaxes = a.swapaxes
@@ -238,9 +291,29 @@
 def transpose(a, axes=None):
     """Return a view of the array with dimensions permuted.
 
-    Permutes axis according to list axes.  If axes is None (default) returns
-    array with dimensions reversed.
+    Parameters
+    ----------
+    a : array_like
+        Input array.
+    axes : {None, list of int}, optional
+        If None (the default), reverse dimensions, otherwise permute
+        axes according to the values given.
 
+    Examples
+    --------
+    >>> x = np.arange(4).reshape((2,2))
+    >>> x
+    array([[0, 1],
+           [2, 3]])
+
+    >>> np.transpose(x)
+    array([[0, 2],
+           [1, 3]])
+
+    >>> np.transpose(x,(0,1)) # no change, axes are kept in current order
+    array([[0, 1],
+           [2, 3]])
+
     """
     try:
         transpose = a.transpose
@@ -255,55 +328,53 @@
     Perform an inplace sort along the given axis using the algorithm
     specified by the kind keyword.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : array
+        Array to be sorted.
+    axis : {None, int} optional
+        Axis along which to sort. None indicates that the flattened
+        array should be used.
+    kind : {'quicksort', 'mergesort', 'heapsort'}, optional
+        Sorting algorithm to use.
+    order : {None, list type}, optional
+        When a is an array with fields defined, this argument specifies
+        which fields to compare first, second, etc.  Not all fields need be
+        specified.
 
-        a : array
-            Array to be sorted.
-        axis : {None, int} optional
-            Axis along which to sort. None indicates that the flattened
-            array should be used.
-        kind : {'quicksort', 'mergesort', 'heapsort'}, optional
-            Sorting algorithm to use.
-        order : {None, list type}, optional
-            When a is an array with fields defined, this argument specifies
-            which fields to compare first, second, etc.  Not all fields need be
-            specified.
+    Returns
+    -------
+    sorted_array : array of same type as a
 
-    *Returns*:
+    See Also
+    --------
+    argsort : Indirect sort.
+    lexsort : Indirect stable sort on multiple keys.
+    searchsorted : Find keys in sorted array.
 
-        sorted_array : array of same type as a
+    Notes
+    -----
+    The various sorts are characterized by average speed, worst case
+    performance, need for work space, and whether they are stable. A
+    stable sort keeps items with the same key in the same relative
+    order. The three available algorithms have the following
+    properties:
 
-    *See Also*:
+    +-----------+-------+-------------+------------+-------+
+    |    kind   | speed |  worst case | work space | stable|
+    +===========+=======+=============+============+=======+
+    | quicksort |   1   | O(n^2)      |     0      |   no  |
+    +-----------+-------+-------------+------------+-------+
+    | mergesort |   2   | O(n*log(n)) |    ~n/2    |   yes |
+    +-----------+-------+-------------+------------+-------+
+    | heapsort  |   3   | O(n*log(n)) |     0      |   no  |
+    +-----------+-------+-------------+------------+-------+
 
-        `argsort` : Indirect sort.
+    All the sort algorithms make temporary copies of the data when
+    the sort is not along the last axis. Consequently, sorts along
+    the last axis are faster and use less space than sorts along
+    other axis.
 
-        `lexsort` : Indirect stable sort on multiple keys.
-
-        `searchsorted` : Find keys in sorted array.
-
-    *Notes*
-
-        The various sorts are characterized by average speed, worst case
-        performance, need for work space, and whether they are stable. A
-        stable sort keeps items with the same key in the same relative
-        order. The three available algorithms have the following
-        properties:
-
-        +-----------+-------+-------------+------------+-------+
-        |    kind   | speed |  worst case | work space | stable|
-        +===========+=======+=============+============+=======+
-        | quicksort |   1   | O(n^2)      |     0      |   no  |
-        +-----------+-------+-------------+------------+-------+
-        | mergesort |   2   | O(n*log(n)) |    ~n/2    |   yes |
-        +-----------+-------+-------------+------------+-------+
-        | heapsort  |   3   | O(n*log(n)) |     0      |   no  |
-        +-----------+-------+-------------+------------+-------+
-
-        All the sort algorithms make temporary copies of the data when
-        the sort is not along the last axis. Consequently, sorts along
-        the last axis are faster and use less space than sorts along
-        other axis.
-
     """
     if axis is None:
         a = asanyarray(a).flatten()
@@ -321,54 +392,53 @@
     by the kind keyword. It returns an array of indices of the same shape as a
     that index data along the given axis in sorted order.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : array
+        Array to be sorted.
+    axis : {None, int} optional
+        Axis along which to sort. None indicates that the flattened
+        array should be used.
+    kind : {'quicksort', 'mergesort', 'heapsort'}, optional
+        Sorting algorithm to use.
+    order : {None, list type}, optional
+        When a is an array with fields defined, this argument specifies
+        which fields to compare first, second, etc.  Not all fields need be
+        specified.
 
-        a : array
-            Array to be sorted.
-        axis : {None, int} optional
-            Axis along which to sort. None indicates that the flattened
-            array should be used.
-        kind : {'quicksort', 'mergesort', 'heapsort'}, optional
-            Sorting algorithm to use.
-        order : {None, list type}, optional
-            When a is an array with fields defined, this argument specifies
-            which fields to compare first, second, etc.  Not all fields need be
-            specified.
+    Returns
+    -------
+    index_array : {integer_array}
+        Array of indices that sort 'a' along the specified axis.
 
-    *Returns*:
+    See Also
+    --------
+    lexsort : Indirect stable sort with multiple keys.
+    sort : Inplace sort.
 
-        index_array : {integer_array}
-            Array of indices that sort 'a' along the specified axis.
+    Notes
+    -----
+    The various sorts are characterized by average speed, worst case
+    performance, need for work space, and whether they are stable. A
+    stable sort keeps items with the same key in the same relative
+    order. The three available algorithms have the following
+    properties:
 
-    *See Also*:
+    +-----------+-------+-------------+------------+-------+
+    |    kind   | speed |  worst case | work space | stable|
+    +===========+=======+=============+============+=======+
+    | quicksort |   1   | O(n^2)      |     0      |   no  |
+    +-----------+-------+-------------+------------+-------+
+    | mergesort |   2   | O(n*log(n)) |    ~n/2    |   yes |
+    +-----------+-------+-------------+------------+-------+
+    | heapsort  |   3   | O(n*log(n)) |     0      |   no  |
+    +-----------+-------+-------------+------------+-------+
 
-        `lexsort` : Indirect stable sort with multiple keys.
+    All the sort algorithms make temporary copies of the data when
+    the sort is not along the last axis. Consequently, sorts along
+    the last axis are faster and use less space than sorts along
+    other axis.
 
-        `sort` : Inplace sort.
-
-    *Notes*
-
-        The various sorts are characterized by average speed, worst case
-        performance, need for work space, and whether they are stable. A
-        stable sort keeps items with the same key in the same relative
-        order. The three available algorithms have the following
-        properties:
-
-        +-----------+-------+-------------+------------+-------+
-        |    kind   | speed |  worst case | work space | stable|
-        +===========+=======+=============+============+=======+
-        | quicksort |   1   | O(n^2)      |     0      |   no  |
-        +-----------+-------+-------------+------------+-------+
-        | mergesort |   2   | O(n*log(n)) |    ~n/2    |   yes |
-        +-----------+-------+-------------+------------+-------+
-        | heapsort  |   3   | O(n*log(n)) |     0      |   no  |
-        +-----------+-------+-------------+------------+-------+
-
-        All the sort algorithms make temporary copies of the data when
-        the sort is not along the last axis. Consequently, sorts along
-        the last axis are faster and use less space than sorts along
-        other axis.
-
     """
     try:
         argsort = a.argsort
@@ -380,28 +450,28 @@
 def argmax(a, axis=None):
     """Returns array of indices of the maximum values of along the given axis.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array to look in.
+    axis : {None, integer}
+        If None, the index is into the flattened array, otherwise along
+        the specified axis
 
-        a : {array_like}
-            Array to look in.
-        axis : {None, integer}
-            If None, the index is into the flattened array, otherwise along
-            the specified axis
+    Returns
+    -------
+    index_array : {integer_array}
 
-    *Returns*:
+    Examples
+    --------
+    >>> a = arange(6).reshape(2,3)
+    >>> argmax(a)
+    5
+    >>> argmax(a,0)
+    array([1, 1, 1])
+    >>> argmax(a,1)
+    array([2, 2])
 
-        index_array : {integer_array}
-
-    *Examples*
-
-        >>> a = arange(6).reshape(2,3)
-        >>> argmax(a)
-        5
-        >>> argmax(a,0)
-        array([1, 1, 1])
-        >>> argmax(a,1)
-        array([2, 2])
-
     """
     try:
         argmax = a.argmax
@@ -413,28 +483,28 @@
 def argmin(a, axis=None):
     """Return array of indices to the minimum values along the given axis.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array to look in.
+    axis : {None, integer}
+        If None, the index is into the flattened array, otherwise along
+        the specified axis
 
-        a : {array_like}
-            Array to look in.
-        axis : {None, integer}
-            If None, the index is into the flattened array, otherwise along
-            the specified axis
+    Returns
+    -------
+    index_array : {integer_array}
 
-    *Returns*:
+    Examples
+    --------
+    >>> a = arange(6).reshape(2,3)
+    >>> argmin(a)
+    0
+    >>> argmin(a,0)
+    array([0, 0, 0])
+    >>> argmin(a,1)
+    array([0, 0])
 
-        index_array : {integer_array}
-
-    *Examples*
-
-        >>> a = arange(6).reshape(2,3)
-        >>> argmin(a)
-        0
-        >>> argmin(a,0)
-        array([0, 0, 0])
-        >>> argmin(a,1)
-        array([0, 0])
-
     """
     try:
         argmin = a.argmin
@@ -453,40 +523,39 @@
     is out of bounds, then the length of a is returned, i.e., the key would need
     to be appended. The returned index array has the same shape as v.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : 1-d array
+        Array must be sorted in ascending order.
+    v : array or list type
+        Array of keys to be searched for in a.
+    side : {'left', 'right'}, optional
+        If 'left', the index of the first location where the key could be
+        inserted is found, if 'right', the index of the last such element is
+        returned. If the is no such element, then either 0 or N is returned,
+        where N is the size of the array.
 
-        a : 1-d array
-            Array must be sorted in ascending order.
-        v : array or list type
-            Array of keys to be searched for in a.
-        side : {'left', 'right'}, optional
-            If 'left', the index of the first location where the key could be
-            inserted is found, if 'right', the index of the last such element is
-            returned. If the is no such element, then either 0 or N is returned,
-            where N is the size of the array.
+    Returns
+    -------
+    indices : integer array
+        Array of insertion points with the same shape as v.
 
-    *Returns*:
+    See Also
+    --------
+    sort : Inplace sort.
+    histogram : Produce histogram from 1-d data.
 
-        indices : integer array
-            Array of insertion points with the same shape as v.
+    Notes
+    -----
+    The array a must be 1-d and is assumed to be sorted in ascending
+    order.  Searchsorted uses binary search to find the required
+    insertion points.
 
-    *See Also*:
+    Examples
+    --------
+    >>> searchsorted([1,2,3,4,5],[6,4,0])
+    array([5, 3, 0])
 
-        `sort` : Inplace sort.
-
-        `histogram` : Produce histogram from 1-d data.
-
-    *Notes*
-
-        The array a must be 1-d and is assumed to be sorted in ascending
-        order.  Searchsorted uses binary search to find the required
-        insertion points.
-
-    *Examples*
-
-        >>> searchsorted([1,2,3,4,5],[6,4,0])
-        array([5, 3, 0])
-
     """
     try:
         searchsorted = a.searchsorted
@@ -504,21 +573,21 @@
     Note that a.resize(new_shape) will fill the array with 0's beyond
     current definition of a.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array to be reshaped.
 
-        a : {array_like}
-            Array to be reshaped.
+    new_shape : {tuple}
+        Shape of reshaped array.
 
-        new_shape : {tuple}
-            Shape of reshaped array.
+    Returns
+    -------
+    reshaped_array : {array}
+        The new array is formed from the data in the old array, repeated if
+        necessary to fill out the required number of elements, with the new
+        shape.
 
-    *Returns*:
-
-        reshaped_array : {array}
-            The new array is formed from the data in the old array, repeated if
-            necessary to fill out the required number of elements, with the new
-            shape.
-
     """
     if isinstance(new_shape, (int, nt.integer)):
         new_shape = (new_shape,)
@@ -546,18 +615,18 @@
 def squeeze(a):
     """Remove single-dimensional entries from the shape of a.
 
-    *Examples*
+    Examples
+    --------
+    >>> x = array([[[1,1,1],[2,2,2],[3,3,3]]])
+    >>> x
+    array([[[1, 1, 1],
+          [2, 2, 2],
+          [3, 3, 3]]])
+    >>> x.shape
+    (1, 3, 3)
+    >>> squeeze(x).shape
+    (3, 3)
 
-        >>> x = array([[[1,1,1],[2,2,2],[3,3,3]]])
-        >>> x
-        array([[[1, 1, 1],
-              [2, 2, 2],
-              [3, 3, 3]]])
-        >>> x.shape
-        (1, 3, 3)
-        >>> squeeze(x).shape
-        (3, 3)
-
     """
     try:
         squeeze = a.squeeze
@@ -576,56 +645,54 @@
     array can be determined by removing axis1 and axis2 and appending an index
     to the right equal to the size of the resulting diagonals.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array from whis the diagonals are taken.
+    offset : {0, integer}, optional
+        Offset of the diagonal from the main diagonal. Can be both positive
+        and negative. Defaults to main diagonal.
+    axis1 : {0, integer}, optional
+        Axis to be used as the first axis of the 2-d subarrays from which
+        the diagonals should be taken. Defaults to first axis.
+    axis2 : {1, integer}, optional
+        Axis to be used as the second axis of the 2-d subarrays from which
+        the diagonals should be taken. Defaults to second axis.
 
-        a : {array_like}
-            Array from whis the diagonals are taken.
-        offset : {0, integer}, optional
-            Offset of the diagonal from the main diagonal. Can be both positive
-            and negative. Defaults to main diagonal.
-        axis1 : {0, integer}, optional
-            Axis to be used as the first axis of the 2-d subarrays from which
-            the diagonals should be taken. Defaults to first axis.
-        axis2 : {1, integer}, optional
-            Axis to be used as the second axis of the 2-d subarrays from which
-            the diagonals should be taken. Defaults to second axis.
+    Returns
+    -------
+    array_of_diagonals : array of same type as a
+        If a is 2-d, a 1-d array containing the diagonal is
+        returned.  If a has larger dimensions, then an array of
+        diagonals is returned.
 
-    *Returns*:
+    See Also
+    --------
+    diag : Matlab workalike for 1-d and 2-d arrays.
+    diagflat : Create diagonal arrays.
+    trace : Sum along diagonals.
 
-        array_of_diagonals : array of same type as a
-            If a is 2-d, a 1-d array containing the diagonal is
-            returned.  If a has larger dimensions, then an array of
-            diagonals is returned.
+    Examples
+    --------
+    >>> a = arange(4).reshape(2,2)
+    >>> a
+    array([[0, 1],
+           [2, 3]])
+    >>> a.diagonal()
+    array([0, 3])
+    >>> a.diagonal(1)
+    array([1])
 
-    *See Also*:
+    >>> a = arange(8).reshape(2,2,2)
+    >>> a
+    array([[[0, 1],
+            [2, 3]],
+           [[4, 5],
+            [6, 7]]])
+    >>> a.diagonal(0,-2,-1)
+    array([[0, 3],
+           [4, 7]])
 
-        `diag` : Matlab workalike for 1-d and 2-d arrays.
-
-        `diagflat` : Create diagonal arrays.
-
-        `trace` : Sum along diagonals.
-
-    *Examples*
-
-        >>> a = arange(4).reshape(2,2)
-        >>> a
-        array([[0, 1],
-               [2, 3]])
-        >>> a.diagonal()
-        array([0, 3])
-        >>> a.diagonal(1)
-        array([1])
-
-        >>> a = arange(8).reshape(2,2,2)
-        >>> a
-        array([[[0, 1],
-                [2, 3]],
-               [[4, 5],
-                [6, 7]]])
-        >>> a.diagonal(0,-2,-1)
-        array([[0, 3],
-               [4, 7]])
-
     """
     return asarray(a).diagonal(offset, axis1, axis2)
 
@@ -641,44 +708,44 @@
     to the right equal to the size of the resulting diagonals. Arrays of integer
     type are summed
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array from whis the diagonals are taken.
+    offset : {0, integer}, optional
+        Offset of the diagonal from the main diagonal. Can be both positive
+        and negative. Defaults to main diagonal.
+    axis1 : {0, integer}, optional
+        Axis to be used as the first axis of the 2-d subarrays from which
+        the diagonals should be taken. Defaults to first axis.
+    axis2 : {1, integer}, optional
+        Axis to be used as the second axis of the 2-d subarrays from which
+        the diagonals should be taken. Defaults to second axis.
+    dtype : {None, dtype}, optional
+        Determines the type of the returned array and of the accumulator
+        where the elements are summed. If dtype has the value None and a is
+        of integer type of precision less than the default 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 sum can be placed. It's type is preserved and
+        it must be of the right shape to hold the output.
 
-        a : {array_like}
-            Array from whis the diagonals are taken.
-        offset : {0, integer}, optional
-            Offset of the diagonal from the main diagonal. Can be both positive
-            and negative. Defaults to main diagonal.
-        axis1 : {0, integer}, optional
-            Axis to be used as the first axis of the 2-d subarrays from which
-            the diagonals should be taken. Defaults to first axis.
-        axis2 : {1, integer}, optional
-            Axis to be used as the second axis of the 2-d subarrays from which
-            the diagonals should be taken. Defaults to second axis.
-        dtype : {None, dtype}, optional
-            Determines the type of the returned array and of the accumulator
-            where the elements are summed. If dtype has the value None and a is
-            of integer type of precision less than the default 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 sum can be placed. It's type is preserved and
-            it must be of the right shape to hold the output.
+    Returns
+    -------
+    sum_along_diagonals : array
+        If a is 2-d, a 0-d array containing the diagonal is
+        returned.  If a has larger dimensions, then an array of
+        diagonals is returned.
 
-    *Returns*:
+    Examples
+    --------
+    >>> trace(eye(3))
+    3.0
+    >>> a = arange(8).reshape((2,2,2))
+    >>> trace(a)
+    array([6, 8])
 
-        sum_along_diagonals : array
-            If a is 2-d, a 0-d array containing the diagonal is
-            returned.  If a has larger dimensions, then an array of
-            diagonals is returned.
-
-    *Examples*
-
-        >>> trace(eye(3))
-        3.0
-        >>> a = arange(8).reshape((2,2,2))
-        >>> trace(a)
-        array([6, 8])
-
     """
     return asarray(a).trace(offset, axis1, axis2, dtype, out)
 
@@ -689,33 +756,32 @@
     are taken in the order specified by the order keyword. The new array is
     a view of a if possible, otherwise it is a copy.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
 
-        a : {array_like}
+    order : {'C','F'}, optional
+        If order is 'C' the elements are taken in row major order. If order
+        is 'F' they are taken in column major order.
 
-        order : {'C','F'}, optional
-            If order is 'C' the elements are taken in row major order. If order
-            is 'F' they are taken in column major order.
+    Returns
+    -------
+    1d_array : {array}
 
-    *Returns*:
+    See Also
+    --------
+    ndarray.flat : 1d iterator over the array.
+    ndarray.flatten : 1d array copy of the elements of a in C order.
 
-        1d_array : {array}
+    Examples
+    --------
+    >>> x = array([[1,2,3],[4,5,6]])
+    >>> x
+    array([[1, 2, 3],
+          [4, 5, 6]])
+    >>> ravel(x)
+    array([1, 2, 3, 4, 5, 6])
 
-    *See Also*:
-
-        `ndarray.flat` : 1d iterator over the array.
-
-        `ndarray.flatten` : 1d array copy of the elements of a in C order.
-
-    *Examples*
-
-        >>> x = array([[1,2,3],[4,5,6]])
-        >>> x
-        array([[1, 2, 3],
-              [4, 5, 6]])
-        >>> ravel(x)
-        array([1, 2, 3, 4, 5, 6])
-
     """
     return asarray(a).ravel(order)
 
@@ -723,23 +789,23 @@
 def nonzero(a):
     """Return the indices of the elements of a which are not zero.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
 
-        a : {array_like}
+    Returns
+    -------
+    tuple_of_arrays : {tuple}
 
-    *Returns*:
+    Examples
+    --------
+    >>> eye(3)[nonzero(eye(3))]
+    array([ 1.,  1.,  1.])
+    >>> nonzero(eye(3))
+    (array([0, 1, 2]), array([0, 1, 2]))
+    >>> eye(3)[nonzero(eye(3))]
+    array([ 1.,  1.,  1.])
 
-        tuple_of_arrays : {tuple}
-
-    *Examples*
-
-        >>> eye(3)[nonzero(eye(3))]
-        array([ 1.,  1.,  1.])
-        >>> nonzero(eye(3))
-        (array([0, 1, 2]), array([0, 1, 2]))
-        >>> eye(3)[nonzero(eye(3))]
-        array([ 1.,  1.,  1.])
-
     """
     try:
         nonzero = a.nonzero
@@ -753,25 +819,25 @@
 def shape(a):
     """Return the shape of a.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array whose shape is desired. If a is not an array, a conversion is
+        attempted.
 
-        a : {array_like}
-            Array whose shape is desired. If a is not an array, a conversion is
-            attempted.
+    Returns
+    -------
+    tuple_of_integers :
+        The elements of the tuple are the length of the corresponding array
+        dimension.
 
-    *Returns*:
+    Examples
+    --------
+    >>> shape(eye(3))
+    (3, 3)
+    >>> shape([[1,2]])
+    (1, 2)
 
-        tuple_of_integers :
-            The elements of the tuple are the length of the corresponding array
-            dimension.
-
-    *Examples*
-
-        >>> shape(eye(3))
-        (3, 3)
-        >>> shape([[1,2]])
-        (1, 2)
-
     """
     try:
         result = a.shape
@@ -810,46 +876,46 @@
 def sum(a, axis=None, dtype=None, out=None):
     """Sum the array over the given axis.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_type}
+        Array containing elements whose sum is desired. If a is not an array, a
+        conversion is attempted.
+    axis : {None, integer}
+        Axis over which the sum is taken. If None is used, then the sum 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 summed. If dtype has the value None and the
+        type of a is an integer type of precision less than the default
+        platform integer, then the default platform integer precision is
+        used.  Otherwise, the dtype is the same as that of a.
+    out : {None, array}, optional
+        Array into which the sum can be placed. It's type is preserved and
+        it must be of the right shape to hold the output.
 
-        a : {array_type}
-            Array containing elements whose sum is desired. If a is not an array, a
-            conversion is attempted.
-        axis : {None, integer}
-            Axis over which the sum is taken. If None is used, then the sum 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 summed. If dtype has the value None and the
-            type of a is an integer type of precision less than the default
-            platform integer, then the default platform integer precision is
-            used.  Otherwise, the dtype is the same as that of a.
-        out : {None, array}, optional
-            Array into which the sum can be placed. It's type is preserved and
-            it must be of the right shape to hold the output.
+    Returns
+    -------
+    sum_along_axis : {array, scalar}, see dtype parameter above.
+        Returns an array whose shape is the same as a with the specified
+        axis removed. Returns a 0d array when a is 1d or dtype=None.
+        Returns a reference to the specified output array if specified.
 
-    *Returns*:
+    See Also
+    --------
+    ndarray.sum : equivalent method
 
-        sum_along_axis : {array, scalar}, see dtype parameter above.
-            Returns an array whose shape is the same as a with the specified
-            axis removed. Returns a 0d array when a is 1d or dtype=None.
-            Returns a reference to the specified output array if specified.
+    Examples
+    --------
+    >>> sum([0.5, 1.5])
+    2.0
+    >>> sum([0.5, 1.5], dtype=N.int32)
+    1
+    >>> sum([[0, 1], [0, 5]])
+    6
+    >>> sum([[0, 1], [0, 5]], axis=1)
+    array([1, 5])
 
-    *See Also*:
-
-        `ndarray.sum` : equivalent method
-
-    *Examples*
-
-        >>> sum([0.5, 1.5])
-        2.0
-        >>> sum([0.5, 1.5], dtype=N.int32)
-        1
-        >>> sum([[0, 1], [0, 5]])
-        6
-        >>> sum([[0, 1], [0, 5]], axis=1)
-        array([1, 5])
-
     """
     if isinstance(a, _gentype):
         res = _sum_(a)
@@ -867,48 +933,48 @@
 def product (a, axis=None, dtype=None, out=None):
     """Product of the array elements over the given axis.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array containing elements whose product is desired. If a is not an array, a
+        conversion is attempted.
+    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
+        the type of a is an integer type of precision less than the default
+        platform integer, then the default platform integer precision is
+        used.  Otherwise, the dtype is the same as that of a.
+    out : {None, array}, 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.
 
-        a : {array_like}
-            Array containing elements whose product is desired. If a is not an array, a
-            conversion is attempted.
-        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
-            the type of a is an integer type of precision less than the default
-            platform integer, then the default platform integer precision is
-            used.  Otherwise, the dtype is the same as that of a.
-        out : {None, array}, 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
+    -------
+    product_along_axis : {array, scalar}, see dtype parameter above.
+        Returns an array whose shape is the same as a with the specified
+        axis removed. Returns a 0d array when a is 1d or dtype=None.
+        Returns a reference to the specified output array if specified.
 
-    *Returns*:
+    See Also
+    --------
+    ndarray.prod : equivalent method
 
-        product_along_axis : {array, scalar}, see dtype parameter above.
-            Returns an array whose shape is the same as a with the specified
-            axis removed. Returns a 0d array when a is 1d or dtype=None.
-            Returns a reference to the specified output array if specified.
+    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.])
 
-    *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
@@ -920,10 +986,10 @@
 def sometrue (a, axis=None, out=None):
     """Perform a logical_or over the given axis.
 
-    *See Also*:
+    See Also
+    --------
+    ndarray.any : equivalent method
 
-        `ndarray.any` : equivalent method
-
     """
     try:
         any = a.any
@@ -935,12 +1001,11 @@
 def alltrue (a, axis=None, out=None):
     """Perform a logical_and over the given axis.
 
-    *See Also*:
+    See Also
+    --------
+    ndarray.all : equivalent method
+    all : equivalent function
 
-        `ndarray.all` : equivalent method
-
-        `all` : equivalent function
-
     """
     try:
         all = a.all
@@ -952,10 +1017,10 @@
 def any(a,axis=None, out=None):
     """Return true if any elements of x are true.
 
-    *See Also*:
+    See Also
+    --------
+    ndarray.any : equivalent method
 
-        `ndarray.any` : equivalent method
-
     """
     try:
         any = a.any
@@ -967,12 +1032,11 @@
 def all(a,axis=None, out=None):
     """Return true if all elements of x are true:
 
-    *See Also*:
+    See Also
+    --------
+    ndarray.all : equivalent method
+    alltrue : equivalent function
 
-        `ndarray.all` : equivalent method
-
-        `alltrue` : equivalent function
-
     """
     try:
         all = a.all
@@ -982,8 +1046,36 @@
 
 
 def cumsum (a, axis=None, dtype=None, out=None):
-    """Sum the array over the given axis.
+    """Return the cumulative sum of the elements along the given axis.
 
+    The cumulative sum is calculated over the flattened array by
+    default, otherwise over the specified axis.
+
+    Parameters
+    ----------
+    a : array-like
+        Input array or object that can be converted to an array.
+    axis : {None, -1, int}, optional
+        Axis along which the product is computed. The default
+        (``axis``= None) is to compute over the flattened array.
+    dtype : type, optional
+        Type to use in computing the cumulative sum. For arrays of
+        integer type the default is int64 for signed ints and uint64
+        for unsigned. 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 and buffer length as the expected output
+        but the type will be cast if necessary.
+
+    Returns
+    -------
+    cumsum : ndarray.
+        A new array holding the result is returned unless ``out`` is
+        specified, in which case a reference to ``out`` is returned.
+        Return datatype is ``dtype`` if specified, otherwise int64 for
+        ints, uint64 for uints, or the input datatype otherwise.
+
     """
     try:
         cumsum = a.cumsum
@@ -992,9 +1084,13 @@
     return cumsum(axis, dtype, out)
 
 
-def cumproduct (a, axis=None, dtype=None, out=None):
+def cumproduct(a, axis=None, dtype=None, out=None):
     """Return the cumulative product over the given axis.
 
+    See Also
+    --------
+    cumprod
+
     """
     try:
         cumprod = a.cumprod
@@ -1004,8 +1100,38 @@
 
 
 def ptp(a, axis=None, out=None):
-    """Return maximum - minimum along the the given dimension.
+    """Return (maximum - minimum) along the the given dimension
+    (i.e. peak-to-peak value).
 
+    Parameters
+    ----------
+    a : array_like
+        Input values.
+    axis : {None, int}, optional
+        Axis along which to find the peaks.  If None (default) the
+        flattened array is used.
+    out : array_like
+        Alternative output array in which to place the result. It must
+        have the same shape and buffer length as the expected output
+        but the type will be cast if necessary.
+
+    Returns
+    -------
+    ptp : ndarray.
+        A new array holding the result, unless ``out`` was
+        specified, in which case a reference to ``out`` is returned.
+
+    Examples
+    --------
+    >>> x = np.arange(4).reshape((2,2))
+    >>> x
+    array([[0, 1],
+           [2, 3]])
+    >>> np.ptp(x,0)
+    array([2, 2])
+    >>> np.ptp(x,1)
+    array([1, 1])
+
     """
     try:
         ptp = a.ptp
@@ -1015,8 +1141,35 @@
 
 
 def amax(a, axis=None, out=None):
-    """Return the maximum of 'a' along dimension axis.
+    """Return the maximum along a given axis.
 
+    Parameters
+    ----------
+    a : array_like
+        Input data.
+    axis : {None, int}, optional
+        Axis along which to operate.  By default, ``axis`` is None and the
+        flattened input is used.
+    out : array_like, optional
+        Alternative output array in which to place the result.  Must
+        be of the same shape and buffer length as the expected output.
+
+    Results
+    -------
+    amax : array_like
+        New array holding the result, unless ``out`` was specified.
+
+    Examples
+    --------
+    >>> x = np.arange(4).reshape((2,2))
+    >>> x
+    array([[0, 1],
+           [2, 3]])
+    >>> np.amax(x,0)
+    array([2, 3])
+    >>> np.amax(x,1)
+    array([1, 3])
+
     """
     try:
         amax = a.max
@@ -1026,8 +1179,35 @@
 
 
 def amin(a, axis=None, out=None):
-    """Return the minimum of a along dimension axis.
+    """Return the minimum along a given axis.
 
+    Parameters
+    ----------
+    a : array_like
+        Input data.
+    axis : {None, int}, optional
+        Axis along which to operate.  By default, ``axis`` is None and the
+        flattened input is used.
+    out : array_like, optional
+        Alternative output array in which to place the result.  Must
+        be of the same shape and buffer length as the expected output.
+
+    Results
+    -------
+    amin : array_like
+        New array holding the result, unless ``out`` was specified.
+
+    Examples
+    --------
+    >>> x = np.arange(4).reshape((2,2))
+    >>> x
+    array([[0, 1],
+           [2, 3]])
+    >>> np.amin(x,0)
+    array([0, 1])
+    >>> np.amin(x,1)
+    array([0, 2])
+
     """
     try:
         amin = a.min
@@ -1040,6 +1220,23 @@
     """Return the length of a Python object interpreted as an array
     of at least 1 dimension.
 
+    Parameters
+    ----------
+    a : array_like
+
+    Returns
+    -------
+    alen : int
+       Length of the first dimension of a.
+
+    Examples
+    --------
+    >>> z = np.zeros((7,4,5))
+    >>> z.shape[0]
+    7
+    >>> np.alen(z)
+    7
+
     """
     try:
         return len(a)
@@ -1050,6 +1247,44 @@
 def prod(a, axis=None, dtype=None, out=None):
     """Return the product of the elements along the given axis.
 
+    Parameters
+    ----------
+    a : array-like
+        Input array.
+    axis : {None, int}, optional
+        Axis along which the product is computed. By default, ``axis``
+        is None and the flattened input is used.
+    dtype : type, optional
+        Type to use in computing the product. For arrays of
+        integer type the default is int64 for signed ints and uint64
+        for unsigned. 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 and buffer length as the expected output
+        but the type will be cast if necessary.
+
+    Returns
+    -------
+    prod : ndarray.
+        A new array holding the result is returned unless out is
+        specified, in which case a reference to out is returned.
+        Return datatype is ``dtype`` if specified, otherwise int64 for
+        ints, uint64 for uints, or the input datatype otherwise.
+
+    Examples
+    --------
+    >>> x = np.arange(4).reshape((2,2)) + 1
+    >>> x
+    array([[1, 2],
+           [3, 4]])
+    >>> np.prod(x)
+    24
+    >>> np.prod(x,0)
+    array([3, 8])
+    >>> np.prod(x,1)
+    array([ 2, 12])
+
     """
     try:
         prod = a.prod
@@ -1067,7 +1302,7 @@
     Parameters
     ----------
     a : array-like
-        Input array or object that can be converted to an array
+        Input array or object that can be converted to an array.
     axis : {None, -1, int}, optional
         Axis along which the product is computed. The default
         (``axis``= None) is to compute over the flattened array.
@@ -1075,7 +1310,7 @@
         Type to use in computing the cumulative product. For arrays of
         integer type the default is int64 for signed ints and uint64
         for unsigned. For arrays of float types it is the same as the
-        array type. 
+        array type.
     out : ndarray, optional
         Alternative output array in which to place the result. It must
         have the same shape and buffer length as the expected output
@@ -1088,6 +1323,7 @@
         specified, in which case a reference to out is returned.
         Return datatype is ``dtype`` if specified, otherwise int64 for
         ints, uint64 for uints, or the input datatype otherwise.
+
     """
     try:
         cumprod = a.cumprod
@@ -1102,36 +1338,33 @@
     If a is not already an array, a conversion is attempted. Scalars are zero
     dimensional.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array whose number of dimensions are desired. If a is not an
+        array, a conversion is attempted.
 
-        a : {array_like}
-            Array whose number of dimensions are desired. If a is not an array, a
-            conversion is attempted.
+    Returns
+    -------
+    number_of_dimensions : {integer}
+        Returns the number of dimensions.
 
-    *Returns*:
+    See Also
+    --------
+    rank : equivalent function.
+    ndarray.ndim : equivalent method
+    shape : dimensions of array
+    ndarray.shape : dimensions of array
 
-        number_of_dimensions : {integer}
-            Returns the number of dimensions.
+    Examples
+    --------
+    >>> ndim([[1,2,3],[4,5,6]])
+    2
+    >>> ndim(array([[1,2,3],[4,5,6]]))
+    2
+    >>> ndim(1)
+    0
 
-    *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
@@ -1146,36 +1379,33 @@
     not already an array, a conversion is attempted. Scalars are zero
     dimensional.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array whose number of dimensions is desired. If a is not an array, a
+        conversion is attempted.
 
-        a : {array_like}
-            Array whose number of dimensions is desired. If a is not an array, a
-            conversion is attempted.
+    Returns
+    -------
+    number_of_dimensions : {integer}
+        Returns the number of dimensions.
 
-    *Returns*:
+    See Also
+    --------
+    ndim : equivalent function
+    ndarray.ndim : equivalent method
+    shape : dimensions of array
+    ndarray.shape : dimensions of array
 
-        number_of_dimensions : {integer}
-            Returns the number of dimensions.
+    Examples
+    --------
+    >>> rank([[1,2,3],[4,5,6]])
+    2
+    >>> rank(array([[1,2,3],[4,5,6]]))
+    2
+    >>> rank(1)
+    0
 
-    *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
@@ -1186,38 +1416,36 @@
 def size(a, axis=None):
     """Return the number of elements along given axis.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array whose axis size is desired. If a is not an array, a
+        conversion is attempted.
+    axis : {None, integer}, optional
+        Axis along which the elements are counted. None means all
+        elements in the array.
 
-        a : {array_like}
-            Array whose axis size is desired. If a is not an array, a conversion
-            is attempted.
-        axis : {None, integer}, optional
-            Axis along which the elements are counted. None means all elements
-            in the array.
+    Returns
+    -------
+    element_count : {integer}
+        Count of elements along specified axis.
 
-    *Returns*:
+    See Also
+    --------
+    shape : dimensions of array
+    ndarray.shape : dimensions of array
+    ndarray.size : number of elements in array
 
-        element_count : {integer}
-            Count of elements along specified axis.
+    Examples
+    --------
+    >>> a = array([[1,2,3],[4,5,6]])
+    >>> size(a)
+    6
+    >>> size(a,1)
+    3
+    >>> size(a,0)
+    2
 
-    *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:
@@ -1239,48 +1467,47 @@
     are desired.  Nothing is done if the input is an integer array and the
     decimals parameter has a value >= 0.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array containing numbers whose rounded values are desired. If a is
+        not an array, a conversion is attempted.
+    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
+        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. Numpy rounds floats to floats by default.
 
-        a : {array_like}
-            Array containing numbers whose rounded values are desired. If a is
-            not an array, a conversion is attempted.
-        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
-            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. Numpy rounds floats to floats by default.
+    Returns
+    -------
+    rounded_array : {array}
+        If out=None, returns a new array of the same type as a containing
+        the rounded values, otherwise a reference to the output array is
+        returned.
 
-        *Returns*:
+    See Also
+    --------
+    round_ : equivalent function
+    ndarray.round : equivalent method
 
-        rounded_array : {array}
-            If out=None, returns a new array of the same type as a containing
-            the rounded values, otherwise a reference to the output array is
-            returned.
+    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 when scaling by powers of ten.
 
-    *See Also*:
+    Examples
+    --------
+    >>> around([.5, 1.5, 2.5, 3.5, 4.5])
+    array([ 0.,  2.,  2.,  4.,  4.])
+    >>> around([1,2,3,11], decimals=1)
+    array([ 1,  2,  3, 11])
+    >>> around([1,2,3,11], decimals=-1)
+    array([ 0,  0,  0, 10])
 
-        `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 when scaling by powers of ten.
-
-    *Examples*
-
-        >>> around([.5, 1.5, 2.5, 3.5, 4.5])
-        array([ 0.,  2.,  2.,  4.,  4.])
-        >>> around([1,2,3,11], decimals=1)
-        array([ 1,  2,  3, 11])
-        >>> around([1,2,3,11], decimals=-1)
-        array([ 0,  0,  0, 10])
-
     """
     try:
         round = a.round
@@ -1297,48 +1524,47 @@
     are desired.  Nothing is done if the input is an integer array and the
     decimals parameter has a value >= 0.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array containing numbers whose rounded values are desired. If a is
+        not an array, a conversion is attempted.
+    decimals : {0, integer}, 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
+        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.
 
-        a : {array_like}
-            Array containing numbers whose rounded values are desired. If a is
-            not an array, a conversion is attempted.
-        decimals : {0, integer}, 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
-            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
+    -------
+    rounded_array : {array}
+        If out=None, returns a new array of the same type as a containing
+        the rounded values, otherwise a reference to the output array is
+        returned.
 
-    *Returns*:
+    See Also
+    --------
+    around : equivalent function
+    ndarray.round : equivalent method
 
-        rounded_array : {array}
-            If out=None, returns a new array of the same type as a containing
-            the rounded values, otherwise a reference to the output array is
-            returned.
+    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 when scaling by powers of ten.
 
-    *See Also*:
+    Examples
+    --------
+    >>> round_([.5, 1.5, 2.5, 3.5, 4.5])
+    array([ 0.,  2.,  2.,  4.,  4.])
+    >>> round_([1,2,3,11], decimals=1)
+    array([ 1,  2,  3, 11])
+    >>> round_([1,2,3,11], decimals=-1)
+    array([ 0,  0,  0, 10])
 
-        `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
-        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 when scaling by powers of ten.
-
-    *Examples*
-
-        >>> round_([.5, 1.5, 2.5, 3.5, 4.5])
-        array([ 0.,  2.,  2.,  4.,  4.])
-        >>> round_([1,2,3,11], decimals=1)
-        array([ 1,  2,  3, 11])
-        >>> round_([1,2,3,11], decimals=-1)
-        array([ 0,  0,  0, 10])
-
     """
     try:
         round = a.round
@@ -1354,50 +1580,49 @@
     over the flattened array by default, otherwise over the specified
     axis. The dtype returned for integer type arrays is float
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array containing numbers whose mean is desired. If a is not an
+        array, a conversion is attempted.
+    axis : {None, integer}, optional
+        Axis along which the means are computed. The default is to compute
+        the standard deviation of the flattened array.
+    dtype : {None, dtype}, optional
+        Type to use in computing the means. For arrays of integer type the
+        default is float32, for arrays of float types it is the same as the
+        array type.
+    out : {None, array}, 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.
 
-        a : {array_like}
-            Array containing numbers whose mean is desired. If a is not an
-            array, a conversion is attempted.
-        axis : {None, integer}, optional
-            Axis along which the means are computed. The default is to compute
-            the standard deviation of the flattened array.
-        dtype : {None, dtype}, optional
-            Type to use in computing the means. For arrays of integer type the
-            default is float32, for arrays of float types it is the same as the
-            array type.
-        out : {None, array}, 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 : {array, scalar}, see dtype parameter above
+        If out=None, returns a new array containing the mean values,
+        otherwise a reference to the output array is returned.
 
-    *Returns*:
+    See Also
+    --------
+    var : Variance
+    std : Standard deviation
 
-        mean : {array, scalar}, see dtype parameter above
-            If out=None, returns a new array containing the mean values,
-            otherwise a reference to the output array is returned.
+    Notes
+    -----
+    The mean is the sum of the elements along the axis divided by the
+    number of elements.
 
-    *See Also*:
+    Examples
+    --------
+    >>> a = array([[1,2],[3,4]])
+    >>> mean(a)
+    2.5
+    >>> mean(a,0)
+    array([ 2.,  3.])
+    >>> mean(a,1)
+    array([ 1.5,  3.5])
 
-        `var` : Variance
-
-        `std` : Standard deviation
-
-    *Notes*
-
-        The mean is the sum of the elements along the axis divided by the number
-        of elements.
-
-    *Examples*
-
-        >>> a = array([[1,2],[3,4]])
-        >>> mean(a)
-        2.5
-        >>> mean(a,0)
-        array([ 2.,  3.])
-        >>> mean(a,1)
-        array([ 1.5,  3.5])
-
     """
     try:
         mean = a.mean
@@ -1413,52 +1638,51 @@
     spread of a distribution. The standard deviation is computed for the
     flattened array by default, otherwise over the specified axis.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array containing numbers whose standard deviation is desired. If a
+        is not an array, a conversion is attempted.
+    axis : {None, integer}, optional
+        Axis along which the standard deviation is computed. The default is
+        to compute the standard deviation of the flattened array.
+    dtype : {None, dtype}, optional
+        Type to use in computing the standard deviation. For arrays of
+        integer type the default is float32, for arrays of float types it is
+        the same as the array type.
+    out : {None, array}, 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.
 
-        a : {array_like}
-            Array containing numbers whose standard deviation is desired. If a
-            is not an array, a conversion is attempted.
-        axis : {None, integer}, optional
-            Axis along which the standard deviation is computed. The default is
-            to compute the standard deviation of the flattened array.
-        dtype : {None, dtype}, optional
-            Type to use in computing the standard deviation. For arrays of
-            integer type the default is float32, for arrays of float types it is
-            the same as the array type.
-        out : {None, array}, 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
+    -------
+    standard_deviation : {array, scalar}, see dtype parameter above.
+        If out=None, returns a new array containing the standard deviation,
+        otherwise a reference to the output array is returned.
 
-    *Returns*:
+    See Also
+    --------
+    var : Variance
+    mean : Average
 
-        standard_deviation : {array, scalar}, see dtype parameter above.
-            If out=None, returns a new array containing the standard deviation,
-            otherwise a reference to the output array is returned.
+    Notes
+    -----
+    The standard deviation is the square root of the average of the squared
+    deviations from the mean, i.e. var = sqrt(mean((x - x.mean())**2)).  The
+    computed standard deviation is biased, i.e., the mean is computed by
+    dividing by the number of elements, N, rather than by N-1.
 
-    *See Also*:
+    Examples
+    --------
+    >>> a = array([[1,2],[3,4]])
+    >>> std(a)
+    1.1180339887498949
+    >>> std(a,0)
+    array([ 1.,  1.])
+    >>> std(a,1)
+    array([ 0.5,  0.5])
 
-        `var` : Variance
-
-        `mean` : Average
-
-    *Notes*
-
-        The standard deviation is the square root of the average of the squared
-        deviations from the mean, i.e. var = sqrt(mean((x - x.mean())**2)).  The
-        computed standard deviation is biased, i.e., the mean is computed by
-        dividing by the number of elements, N, rather than by N-1.
-
-    *Examples*
-
-        >>> a = array([[1,2],[3,4]])
-        >>> std(a)
-        1.1180339887498949
-        >>> std(a,0)
-        array([ 1.,  1.])
-        >>> std(a,1)
-        array([ 0.5,  0.5])
-
     """
     try:
         std = a.std
@@ -1474,52 +1698,51 @@
     distribution. The variance is computed for the flattened array by default,
     otherwise over the specified axis.
 
-    *Parameters*:
+    Parameters
+    ----------
+    a : {array_like}
+        Array containing numbers whose variance is desired. If a is not an
+        array, a conversion is attempted.
+    axis : {None, integer}, optional
+        Axis along which the variance is computed. The default is to compute
+        the variance of the flattened array.
+    dtype : {None, 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 array type.
+    out : {None, array}, 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.
 
-        a : {array_like}
-            Array containing numbers whose variance is desired. If a is not an
-            array, a conversion is attempted.
-        axis : {None, integer}, optional
-            Axis along which the variance is computed. The default is to compute
-            the variance of the flattened array.
-        dtype : {None, 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 array type.
-        out : {None, array}, 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
+    -------
+    variance : {array, scalar}, see dtype parameter above
+        If out=None, returns a new array containing the variance, otherwise
+        a reference to the output array is returned.
 
-    *Returns*:
+    See Also
+    --------
+    std : Standard deviation
+    mean : Average
 
-        variance : {array, scalar}, see dtype parameter above
-            If out=None, returns a new array containing the variance, otherwise
-            a reference to the output array is returned.
+    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,
+    i.e., the mean is computed by dividing by the number of elements, N,
+    rather than by N-1.
 
-    *See Also*:
+    Examples
+    --------
+    >>> a = array([[1,2],[3,4]])
+    >>> var(a)
+    1.25
+    >>> var(a,0)
+    array([ 1.,  1.])
+    >>> var(a,1)
+    array([ 0.25,  0.25])
 
-        `std` : Standard deviation
-
-        `mean` : Average
-
-    *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,
-        i.e., the mean is computed by dividing by the number of elements, N,
-        rather than by N-1.
-
-    *Examples*
-
-        >>> a = array([[1,2],[3,4]])
-        >>> var(a)
-        1.25
-        >>> var(a,0)
-        array([ 1.,  1.])
-        >>> var(a,1)
-        array([ 0.25,  0.25])
-
     """
     try:
         var = a.var



More information about the Numpy-svn mailing list