[Numpysvn] r4029  trunk/numpy/core
numpysvn@scip...
numpysvn@scip...
Thu Sep 13 00:34:29 CDT 2007
Author: charris
Date: 20070913 00:34:26 0500 (Thu, 13 Sep 2007)
New Revision: 4029
Modified:
trunk/numpy/core/fromnumeric.py
Log:
Do more documentation formating.
Rename some variables for consistency.
Modified: trunk/numpy/core/fromnumeric.py
===================================================================
 trunk/numpy/core/fromnumeric.py 20070910 20:23:25 UTC (rev 4028)
+++ trunk/numpy/core/fromnumeric.py 20070913 05:34:26 UTC (rev 4029)
@@ 43,36 +43,42 @@
def take(a, indices, axis=None, out=None, mode='raise'):
 """Return an array with values pulled from the given array at the given
 indices.
+ """Return an array formed from the elements of a at the given indices.
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:
  `a` : array
 The source array
  `indices` : int array
 The indices of the values to extract.
  `axis` : None or int, optional (default=None)
 The axis over which to select values. None signifies that the
 operation should be performed over the flattened array.
  `out` : array, optional
 If provided, the result will be inserted into this array. It should
 be of the appropriate shape and dtype.
  `mode` : one of 'raise', 'wrap', or 'clip', optional
 (default='raise')
 Specifies how outofbounds indices will behave.
  'raise' : raise an error
  'wrap' : wrap around
  'clip' : clip to the range
+ *Parameters*:
 :Returns:
  `subarray` : array
+ a : array
+ The source array
 :See also:
  numpy.ndarray.take() : equivalent method
+ 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 outofbounds 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.
+
+ *See Also*:
+
+ `ndarray.take` : equivalent method
+
"""
try:
take = a.take
@@ 83,26 +89,31 @@
# not deprecated  copy if necessary, view otherwise
def reshape(a, newshape, order='C'):
 """Return an array that uses the data of the given array, but with a new
 shape.
+ """Returns an array containing the data of a, but with a new shape.
 :Parameters:
  `a` : array
  `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' or 'FORTRAN', optional (default='C')
 Whether the array data should be viewed as in C (rowmajor) order or
 FORTRAN (columnmajor) order.
+ *Parameters*:
 :Returns:
  `reshaped_array` : array
 This will be a new view object if possible; otherwise, it will
 return a copy.
+ a : array
+ Array to be reshaped.
 :SeeAlso:
  numpy.ndarray.reshape() : Equivalent method.
+ 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
+ (rowmajor) order or FORTRAN (columnmajor) order.
+
+ *Returns*:
+
+ reshaped_array : array
+ This will be a new view object if possible; otherwise, it will
+ return a copy.
+
+ *See Also*:
+
+ `numpy.ndarray.reshape` : Equivalent method.
+
"""
try:
reshape = a.reshape
@@ 114,45 +125,50 @@
def choose(a, choices, out=None, mode='raise'):
"""Use an index array to construct a new array from a set of choices.
 Given an array of integers in {0, 1, ..., n1} 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, ..., n1} 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:
  `a` : int array
 This array must contain integers in [0, n1], 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` : one of 'raise', 'wrap', or 'clip', optional (default='raise')
 Specifies how outofbounds indices will behave.
  'raise' : raise an error
  'wrap' : wrap around
  'clip' : clip to the range
+ *Parameters*:
 :Returns:
  `merged_array` : array
+ a : int array
+ This array must contain integers in [0, n1], where n is the number
+ of choices.
 :SeeAlso:
  numpy.ndarray.choose() : equivalent method
+ choices : sequence of arrays
+ Each of the choice arrays should have the same shape as the index
+ array.
 Examples
 
+ out : array, optional
+ If provided, the result will be inserted into this array. It should
+ be of the appropriate shape and dtype
 >>> 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])
+ mode : {'raise', 'wrap', 'clip'}, optional
+ Specifies how outofbounds indices will behave.
+ 'raise' : raise an error
+ 'wrap' : wrap around
+ 'clip' : clip to the range
+ *Returns*:
+
+ merged_array : array
+
+ *See Also*:
+
+ `numpy.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
@@ 164,31 +180,35 @@
def repeat(a, repeats, axis=None):
"""Repeat elements of an array.
 :Parameters:
  `a` : array
  `repeats` : int or int 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 or int, optional (default=None)
 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.
+ *Parameters*:
 :Returns:
  `repeated_array` : array
+ a : array
 :SeeAlso:
  numpy.ndarray.repeat() : equivalent method
+ repeats : int or int 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.
 Examples
 
+ axis : {None, int}, 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.
 >>> 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])
+ *Returns*:
+ repeated_array : array
+
+ *See Also*:
+
+ `numpy.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
@@ 198,9 +218,10 @@
def put (a, ind, v, mode='raise'):
 """Set a[n] = v[n] for all n in ind. 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
+ """Set a[n] = v[n] for all n in ind.
+
+ 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):
ind = array(indices, copy=False)
@@ 216,6 +237,8 @@
def swapaxes(a, axis1, axis2):
"""Return array a with axis1 and axis2 interchanged.
+ Blah, Blah.
+
"""
try:
swapaxes = a.swapaxes
@@ 225,10 +248,11 @@
def transpose(a, axes=None):
 """Return a view of the array with dimensions permuted according
 to axes. If axes is None (default) returns array with dimensions
 reversed.
+ """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.
+
"""
try:
transpose = a.transpose
@@ 240,57 +264,61 @@
def sort(a, axis=1, kind='quicksort', order=None):
"""Return copy of 'a' sorted along the given axis.
 :Description:

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 : integer
+
+ axis : {None, int} optional
Axis along which to sort. None indicates that the flattened
 array should be used. Default is 1.
 kind : string
 Sorting algorithm to use. Possible values are 'quicksort',
 'mergesort', or 'heapsort'. Default is 'quicksort'.
 order : list type or None
 When a is an array with fields defined, this argument
 specifies which fields to compare first, second, etc. Not
 all fields need be specified.
+ array should be used.
 :Returns:
+ 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
 :SeeAlso:
  argsort : Indirect sort.
  lexsort : Indirect stable sort on multiple keys.
  searchsorted : Find keys in sorted array.
+ *See Also*:
 Notes
 
+ `argsort` : Indirect sort.
 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:
+ `lexsort` : Indirect stable sort on multiple keys.
 ++++++
  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 
 ++++++
+ `searchsorted` : Find keys in sorted array.
 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.
+ *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()
@@ 304,56 +332,61 @@
def argsort(a, axis=1, kind='quicksort', order=None):
"""Returns array of indices that index 'a' in sorted order.
 Perform an indirect sort along the given axis using the algorithm
 specified 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.
+ Perform an indirect sort along the given axis using the algorithm specified
+ 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
 Values that the returned indices should sort.
 axis : integer
 Axis to be indirectly sorted. None indicates that the
 flattened array should be used. Default is 1.
 kind : string
 Sorting algorithm to use. Possible values are 'quicksort',
 'mergesort', or 'heapsort'. Default is 'quicksort'.
 order : list type or None
 When a is an array with fields defined, this argument
 specifies which fields to compare first, second, etc. Not
 all fields need be specified.
+ Array to be sorted.
 :Returns:
+ 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*:
+
indices : integer array
Array of indices that sort 'a' along the specified axis.
 :SeeAlso:
  lexsort : Indirect stable sort with multiple keys.
  sort : Inplace sort.
+ *See Also*:
 Notes
 
+ `lexsort` : Indirect stable sort with multiple keys.
 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:
+ `sort` : Inplace sort.
 ++++++
  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 
 ++++++
+ *Notes*
 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.
+ 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
@@ 363,9 +396,31 @@
def argmax(a, axis=None):
 """Return the indices to the maximum value of the 1D arrays along
 the given axis.
+ """Returns array of indices of the maximum values of along the given axis.
+ *Parameters*:
+
+ a : array
+ Array to look in.
+
+ axis : {None, integer}
+ If None, the index is into the flattened array, otherwise along
+ the specified axis
+
+ *Returns*:
+
+ Array of indices
+
+ *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
@@ 375,9 +430,31 @@
def argmin(a, axis=None):
 """Return the indices to the minimum value of the 1D arrays along
 the given axis.
+ """Return array of indices to the minimum values along the given axis.
+ *Parameters*:
+
+ a : array
+ Array to look in.
+
+ axis : {None, integer}
+ If None, the index is into the flattened array, otherwise along
+ the specified axis
+
+ *Returns*:
+
+ Array of indices
+
+ *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
@@ 387,49 +464,51 @@
def searchsorted(a, v, side='left'):
 """Return indices where keys in v should be inserted to maintain
 order.
+ """Return indices where keys in v should be inserted to maintain order.
 Find the indices into a sorted array such that if the
 corresponding keys in v were inserted before the indices the
 order of a would be preserved. If side='left', then the first
 such index is returned. If side='right', then the last such index
 is returned. If there is no such index because the key 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.
+ Find the indices into a sorted array such that if the corresponding keys in
+ v were inserted before the indices the order of a would be preserved. If
+ side='left', then the first such index is returned. If side='right', then
+ the last such index is returned. If there is no such index because the key
+ 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 : 1d array
 Array sorted in ascending order.
+ Array must be sorted in ascending order.
+
v : array or list type
Array of keys to be searched for in a.
 side : string
 Possible values are : 'left', 'right'. Default is 'left'.
 Return the first or last index where the key could be
 inserted.
 :Returns:
+ 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.
 :SeeAlso:
  sort : Inplace sort.
  histogram : Produce histogram from 1d data.
+ *See Also*:
 Notes
 
+ `sort` : Inplace sort.
 The array a must be 1d and is assumed to be sorted in ascending
 order. Searchsorted uses binary search to find the required
 insertion points.
+ `histogram` : Produce histogram from 1d data.
 Examples
 
+ *Notes*
 >>> searchsorted([1,2,3,4,5],[6,4,0])
 array([5, 3, 0])
+ The array a must be 1d 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
@@ 447,6 +526,21 @@
Note that a.resize(new_shape) will fill the array with 0's beyond
current definition of a.
+ *Parameters*:
+
+ a : array_like
+ Array to be reshaped.
+
+ new_shape : tuple
+ Shape of the new array.
+
+ *Returns*:
+
+ new_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)):
@@ 475,21 +569,19 @@
def squeeze(a):
"""Remove singledimensional 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
except AttributeError:
@@ 500,58 +592,66 @@
def diagonal(a, offset=0, axis1=0, axis2=1):
"""Return specified diagonals.
 If a is 2d, returns the diagonal of self with the given offset,
 i.e., the collection of elements of the form a[i,i+offset]. If a
 has more than two dimensions, then the axes specified by axis1 and
 axis2 are used to determine the 2d subarray whose diagonal is
 returned. The shape of the resulting array can be determined by
 removing axis1 and axis2 and appending an index to the right equal
 to the size of the resulting diagonals.
+ If a is 2d, returns the diagonal of self with the given offset, i.e., the
+ collection of elements of the form a[i,i+offset]. If a has more than two
+ dimensions, then the axes specified by axis1 and axis2 are used to determine
+ the 2d subarray whose diagonal is returned. The shape of the resulting
+ 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:
 offset : integer
 Offset of the diagonal from the main diagonal. Can be both
 positive and negative. Defaults to main diagonal.
 axis1 : integer
 Axis to be used as the first axis of the 2d subarrays from
 which the diagonals should be taken. Defaults to first axis.
 axis2 : integer
 Axis to be used as the second axis of the 2d subarrays from
 which the diagonals should be taken. Defaults to second axis.
+ *Parameters*:
 :Returns:
+ 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 2d 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 2d 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 2d, a 1d array containing the diagonal is
returned. If a has larger dimensions, then an array of
diagonals is returned.
 :SeeAlso:
  diag : Matlab workalike for 1d and 2d arrays.
  diagflat : Create diagonal arrays.
  trace : Sum along diagonals.
+ *See Also*:
 Examples
 
+ `diag` : Matlab workalike for 1d and 2d arrays.
 >>> a = arange(4).reshape(2,2)
 >>> a
 array([[0, 1],
 [2, 3]])
 >>> a.diagonal()
 array([0, 3])
 >>> a.diagonal(1)
 array([1])
+ `diagflat` : Create diagonal arrays.
 >>> 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]])
+ `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)
@@ 559,30 +659,118 @@
def trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None):
"""Return the sum along diagonals of the array.
+ If a is 2d, returns the sum along the diagonal of self with the given offset, i.e., the
+ collection of elements of the form a[i,i+offset]. If a has more than two
+ dimensions, then the axes specified by axis1 and axis2 are used to determine
+ the 2d subarray whose trace is returned. The shape of the resulting
+ array can be determined by removing axis1 and axis2 and appending an index
+ to the right equal to the size of the resulting diagonals. Arrays of integer
+ type are summed
+
+ *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 2d 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 2d 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 2d, a 0d 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)
def ravel(m,order='C'):
 """Return a 1d array with all the elements of m. The new array is
 a view of m if possible, otherwise it is a copy.
+def ravel(a, order='C'):
+ """Return a 1d array containing the elements of a.
 Examples
 
+ Returns the elements of a as a 1d array. The elements in the new array
+ 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.
 >>> 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])
+ *Parameters*:
+ 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.
+
+ *Returns*:
+
+ 1d array of the elements of a.
+
+ *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])
+
"""
 a = asarray(m)
 return a.ravel(order)
+ return asarray(a).ravel(order)
+
def nonzero(a):
"""Return the indices of the elements of a which are not zero.
+ *Parameters*:
+
+ a : array_like
+
+ *Returns*:
+
+ Tuple of arrays of indices.
+
+ *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
@@ 592,17 +780,27 @@
res = nonzero()
return res
+
def shape(a):
 """Return the shape of a. This function can also be called on
 nested sequences, e.g.
+ """Return the shape of a.
 Examples
 
+ *Parameters*:
 >>> x = array([1,2,3])
 >>> shape((x,x,x))
 (3, 3)
+ a : array type
+ *Returns*:
+
+ 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
@@ 610,140 +808,184 @@
result = asarray(a).shape
return result
def compress(condition, m, axis=None, out=None):
 """Return m where condition is true.
 Equivalent to m[condition].
+def compress(condition, a, axis=None, out=None):
+ """Return a where condition is true.
+ Equivalent to a[condition].
+
"""
try:
 compress = m.compress
+ compress = a.compress
except AttributeError:
 return _wrapit(m, 'compress', condition, axis, out)
+ return _wrapit(a, 'compress', condition, axis, out)
return compress(condition, axis, out)
def clip(m, m_min, m_max):
 """Limit the values of m to [m_min, m_max]. Equivalent to
 m[m < m_min] = m_min
 m[m > m_max] = m_max
+def clip(a, a_min, a_max):
+ """Limit the values of a to [a_min, a_max]. Equivalent to
+ a[a < a_min] = a_min
+ a[a > a_max] = a_max
+
"""
try:
 clip = m.clip
+ clip = a.clip
except AttributeError:
 return _wrapit(m, 'clip', m_min, m_max)
 return clip(m_min, m_max)
+ return _wrapit(a, 'clip', a_min, a_max)
+ return clip(a_min, a_max)
def sum(x, axis=None, dtype=None, out=None):
 """Sum the array over the given axis. The optional dtype argument
 is the data type for intermediate calculations.
 The default is to upcast (promote) smaller integer types to the
 platformdependent Int. For example, on 32bit platforms:
+def sum(a, axis=None, dtype=None, out=None):
+ """Sum the array over the given axis.
 x.dtype default sum() dtype
 
 bool, int8, int16, int32 int32
+ *Parameters*:
 Examples
 
+ a : array_type
 >>> N.sum([0.5, 1.5])
 2.0
 >>> N.sum([0.5, 1.5], dtype=N.int32)
 1
 >>> N.sum([[0, 1], [0, 5]])
 6
 >>> N.sum([[0, 1], [0, 5]], axis=1)
 array([1, 5])
+ axis : {None, integer}
+ Axis over which the sums are 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 a is
+ of integer type of precision less than the default platform 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 specified axis : {array, scalar}, type as explained above.
+ If the sum is along an axis, then an array is returned whose shape
+ is the same as a with the specified axis removed. For 1d arrays or
+ dtype=None, the result is a 0d array.
+
+ *Examples*
+
+ >>> N.sum([0.5, 1.5])
+ 2.0
+ >>> N.sum([0.5, 1.5], dtype=N.int32)
+ 1
+ >>> N.sum([[0, 1], [0, 5]])
+ 6
+ >>> N.sum([[0, 1], [0, 5]], axis=1)
+ array([1, 5])
+
"""
 if isinstance(x, _gentype):
 res = _sum_(x)
+ if isinstance(a, _gentype):
+ res = _sum_(a)
if out is not None:
out[...] = res
return out
return res
try:
 sum = x.sum
+ sum = a.sum
except AttributeError:
 return _wrapit(x, 'sum', axis, dtype, out)
+ return _wrapit(a, 'sum', axis, dtype, out)
return sum(axis, dtype, out)
def product (x, axis=None, dtype=None, out=None):
+
+def product (a, axis=None, dtype=None, out=None):
"""Product of the array elements over the given axis.
+ Blah, Blah.
+
"""
try:
 prod = x.prod
+ prod = a.prod
except AttributeError:
 return _wrapit(x, 'prod', axis, dtype, out)
+ return _wrapit(a, 'prod', axis, dtype, out)
return prod(axis, dtype, out)
def sometrue (x, axis=None, out=None):
+
+def sometrue (a, axis=None, out=None):
"""Perform a logical_or over the given axis.
+ Blah, Blah.
+
"""
try:
 any = x.any
+ any = a.any
except AttributeError:
 return _wrapit(x, 'any', axis, out)
+ return _wrapit(a, 'any', axis, out)
return any(axis, out)
def alltrue (x, axis=None, out=None):
+
+def alltrue (a, axis=None, out=None):
"""Perform a logical_and over the given axis.
+ Blah, Blah.
+
"""
try:
 all = x.all
+ all = a.all
except AttributeError:
 return _wrapit(x, 'all', axis, out)
+ return _wrapit(a, 'all', axis, out)
return all(axis, out)
def any(x,axis=None, out=None):
+
+def any(a,axis=None, out=None):
"""Return true if any elements of x are true.
+ Blah, Blah.
+
"""
try:
 any = x.any
+ any = a.any
except AttributeError:
 return _wrapit(x, 'any', axis, out)
+ return _wrapit(a, 'any', axis, out)
return any(axis, out)
def all(x,axis=None, out=None):
+
+def all(a,axis=None, out=None):
"""Return true if all elements of x are true:
+ Blah, Blah.
+
"""
try:
 all = x.all
+ all = a.all
except AttributeError:
 return _wrapit(x, 'all', axis, out)
+ return _wrapit(a, 'all', axis, out)
return all(axis, out)
def cumsum (x, axis=None, dtype=None, out=None):
+
+def cumsum (a, axis=None, dtype=None, out=None):
"""Sum the array over the given axis.
+ Blah, Blah.
+
"""
try:
 cumsum = x.cumsum
+ cumsum = a.cumsum
except AttributeError:
 return _wrapit(x, 'cumsum', axis, dtype, out)
+ return _wrapit(a, 'cumsum', axis, dtype, out)
return cumsum(axis, dtype, out)
def cumproduct (x, axis=None, dtype=None, out=None):
+
+def cumproduct (a, axis=None, dtype=None, out=None):
"""Return the cumulative product over the given axis.
+ Blah, Blah.
+
"""
try:
 cumprod = x.cumprod
+ cumprod = a.cumprod
except AttributeError:
 return _wrapit(x, 'cumprod', axis, dtype, out)
+ return _wrapit(a, 'cumprod', axis, dtype, out)
return cumprod(axis, dtype, out)
+
def ptp(a, axis=None, out=None):
"""Return maximum  minimum along the the given dimension.
+ Blah, Blah.
+
"""
try:
ptp = a.ptp
@@ 751,9 +993,12 @@
return _wrapit(a, 'ptp', axis, out)
return ptp(axis, out)
+
def amax(a, axis=None, out=None):
"""Return the maximum of 'a' along dimension axis.
+ Blah, Blah.
+
"""
try:
amax = a.max
@@ 761,8 +1006,12 @@
return _wrapit(a, 'max', axis, out)
return amax(axis, out)
+
def amin(a, axis=None, out=None):
"""Return the minimum of a along dimension axis.
+
+ Blah, Blah.
+
"""
try:
amin = a.min
@@ 770,19 +1019,25 @@
return _wrapit(a, 'min', axis, out)
return amin(axis, out)
+
def alen(a):
"""Return the length of a Python object interpreted as an array
of at least 1 dimension.
+ Blah, Blah.
+
"""
try:
return len(a)
except TypeError:
return len(array(a,ndmin=1))
+
def prod(a, axis=None, dtype=None, out=None):
"""Return the product of the elements along the given axis.
+ Blah, Blah.
+
"""
try:
prod = a.prod
@@ 790,9 +1045,12 @@
return _wrapit(a, 'prod', axis, dtype, out)
return prod(axis, dtype, out)
+
def cumprod(a, axis=None, dtype=None, out=None):
"""Return the cumulative product of the elements along the given axis.
+ Blah, Blah.
+
"""
try:
cumprod = a.cumprod
@@ 800,28 +1058,37 @@
return _wrapit(a, 'cumprod', axis, dtype, out)
return cumprod(axis, dtype, out)
+
def ndim(a):
"""Return the number of dimensions of a.
+ Blah, Blah.
+
"""
try:
return a.ndim
except AttributeError:
return asarray(a).ndim
+
def rank(a):
"""Return the rank of sequence a (the number of dimensions, not
the matrix rank). The rank of a scalar is zero.
+ Blah, Blah.
+
"""
try:
return a.ndim
except AttributeError:
return asarray(a).ndim
+
def size(a, axis=None):
"""Return the number of elements in sequence a, or along a given axis.
+ Blah, Blah.
+
"""
if axis is None:
@@ 835,41 +1102,42 @@
except AttributeError:
return asarray(a).shape[axis]
+
def round_(a, decimals=0, out=None):
"""Round a to the given number of decimals.
 The real and imaginary parts of complex numbers are rounded
 separately. Nothing is done if the input is an integer array with
 decimals >= 0.
+ The real and imaginary parts of complex numbers are rounded separately.
+ Nothing is done if the input is an integer array with decimals >= 0.
 :Parameters:
 decimals : integer
 Number of decimal places to round to (default 0). When
 'decimals' is negative it specifies the number of
 positions to the left of the decimal point.
 out : array
 Existing array to use for output (by default, make a
 copy of a).
+ *Parameters*:
 :Returns:
+ 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
+ Existing array to use for output (by default, make a copy of a).
+
+ *Returns*:
+
out : array
 May be used to specify a different array to hold the
 result rather than the default 'a'. If the type of the
 array specified by 'out' differs from that of 'a', the
 result is cast to the new type, otherwise the original
 type is kept. Floats round to floats by default.
+ May be used to specify a different array to hold the result rather
+ than the default a. If the type of the array specified by 'out'
+ differs from that of a, the result is cast to the new type,
+ otherwise the original type is kept. Floats round to floats by
+ default.
 Notes
 
+ *See Also*:
 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 in scaling the numbers when 'decimals' is something
 other than 0.
+ `around` : alias of this function
 The function around is an alias for round_.
+ *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 in scaling the numbers when decimals is something
+ other than 0.
+
"""
try:
round = a.round
@@ 877,7 +1145,6 @@
return _wrapit(a, 'round', decimals, out)
return round(decimals, out)
around = round_
def mean(a, axis=None, dtype=None, out=None):
"""Compute the mean along the specified axis.
@@ 886,34 +1153,37 @@
over the flattened array by default, otherwise over the specified
axis.
 :Parameters:
+ *Parameters*:
+
axis : integer
 Axis along which the means are computed. The default is
 to compute the standard deviation of the flattened array.
+ Axis along which the means are computed. The default is to compute
+ the standard deviation of the flattened array.
dtype : type
 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.
+ 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 : ndarray
 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.
+ 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:
+ *Returns*:
+
mean : array (see dtype parameter above)
 A new array holding the result is returned unless out is
 specified, in which case a reference to out is returned.
+ A new array holding the result is returned unless out is specified,
+ in which case a reference to out is returned.
 :SeeAlso:
  var : Variance
  std : Standard deviation
+ *See Also*:
 Notes
 
+ `var` : Variance
 The mean is the sum of the elements along the axis divided by the
 number of elements.
+ `std` : Standard deviation
+ *Notes*
+
+ The mean is the sum of the elements along the axis divided by the number
+ of elements.
+
"""
try:
mean = a.mean
@@ 925,43 +1195,43 @@
def std(a, axis=None, dtype=None, out=None):
"""Compute the standard deviation along the specified axis.
 Returns the standard deviation of the array elements, a measure
 of the spread of a distribution. The standard deviation is
 computed for the flattened array by default, otherwise over the
 specified axis.
+ Returns the standard deviation of the array elements, a measure of the
+ spread of a distribution. The standard deviation is computed for the
+ flattened array by default, otherwise over the specified axis.
 :Parameters:
+ *Parameters*:
+
axis : integer
 Axis along which the standard deviation is computed. The
 default is to compute the standard deviation of the flattened
 array.
+ Axis along which the standard deviation is computed. The default is
+ to compute the standard deviation of the flattened array.
dtype : type
 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.
+ 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 : ndarray
 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.
+ 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:
+ *Returns*:
+
standard_deviation : The return type varies, see above.
 A new array holding the result is returned unless out is
 specified, in which case a reference to out is returned.
+ A new array holding the result is returned unless out is specified,
+ in which case a reference to out is returned.
 :SeeAlso:
  var : Variance
  mean : Average
+ *See Also*:
 Notes
 
+ `var` : Variance
 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 N1.
+ `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 N1.
+
"""
try:
std = a.std
@@ 973,43 +1243,51 @@
def var(a, axis=None, dtype=None, out=None):
"""Compute the variance along the specified axis.
 Returns the variance of the array elements, a measure of the
 spread of a distribution. The variance is computed for the
 flattened array by default, otherwise over the specified axis.
+ Returns the variance of the array elements, a measure of the spread of a
+ distribution. The variance is computed for the flattened array by default,
+ otherwise over the specified axis.
 :Parameters:
+ *Parameters*:
+
axis : integer
 Axis along which the variance is computed. The default is to
 compute the variance of the flattened array.
+ Axis along which the variance is computed. The default is to compute
+ the variance of the flattened array.
dtype : type
 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.
+ 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 : ndarray
 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.
+ 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:
+ *Returns*:
+
variance : array (see dtype parameter above)
 A new array holding the result is returned unless out is
 specified, in which case a reference to out is returned.
+ A new array holding the result is returned unless out is specified,
+ in which case a reference to out is returned.
 :SeeAlso:
  std : Standard deviation
  mean : Average
+ *See Also*:
 Notes
 
+ `std` : Standard deviation
 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 N1.
+ `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 N1.
+
"""
try:
var = a.var
except AttributeError:
return _wrapit(a, 'var', axis, dtype, out)
return var(axis, dtype, out)
+
+# functions that are now aliases
+
+around = round_
+
More information about the Numpysvn
mailing list