[Numpy-svn] r3752 - in trunk/numpy: . core
numpy-svn at scipy.org
numpy-svn at scipy.org
Sat May 12 20:35:12 EDT 2007
Author: charris
Date: 2007-05-12 19:35:09 -0500 (Sat, 12 May 2007)
New Revision: 3752
Modified:
trunk/numpy/add_newdocs.py
trunk/numpy/core/defmatrix.py
trunk/numpy/core/fromnumeric.py
Log:
Add documentation for diagonal.
Reformat documentation of sort, argsort, lexsort, and searchsorted.
Modified: trunk/numpy/add_newdocs.py
===================================================================
--- trunk/numpy/add_newdocs.py 2007-05-12 19:58:43 UTC (rev 3751)
+++ trunk/numpy/add_newdocs.py 2007-05-13 00:35:09 UTC (rev 3752)
@@ -356,18 +356,37 @@
add_newdoc('numpy.core.multiarray','lexsort',
- """lexsort(keys=, axis=-1) -> array of indices. argsort with list of keys.
+ """lexsort(keys=, axis=-1) -> array of indices. Argsort with list of keys.
- Return an array of indices similar to argsort, except the sorting is
- done using the provided sorting keys. First the sort is done using
- key[0], then the resulting list of indices is further manipulated by
- sorting on key[1], and so forth. The result is a sort on multiple
- keys. If the keys represented columns of a spreadsheet, for example,
- this would sort using multiple columns (the last key being used for the
- primary sort order, the second-to-last key for the secondary sort order,
- and so on). The keys argument must be a sequence of things that can be
- converted to arrays of the same shape.
+ Perform an indirect sort using a list of keys. The first key is sorted,
+ then the second, and so on through the list of keys. At each step the
+ previous order is preserved when equal keys are encountered. The result is
+ a sort on multiple keys. If the keys represented columns of a spreadsheet,
+ for example, this would sort using multiple columns (the last key being
+ used for the primary sort order, the second-to-last key for the secondary
+ sort order, and so on). The keys argument must be a sequence of things
+ that can be converted to arrays of the same shape.
+ :Parameters:
+
+ a : array type
+ Array containing 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.
+
+ :Returns:
+
+ indices : integer array
+ Array of indices that sort the keys along the specified axis. The
+ array has the same shape as the keys.
+
+ :SeeAlso:
+
+ - argsort : indirect sort
+ - sort : inplace sort
+
""")
add_newdoc('numpy.core.multiarray','can_cast',
@@ -650,24 +669,38 @@
add_newdoc('numpy.core.multiarray', 'ndarray', ('argsort',
"""a.argsort(axis=-1, kind='quicksort', order=None) -> indices
- Return array of indices that sort a along the given axis.
+ 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.
- Keyword arguments:
+ :Parameters:
- axis -- axis to be indirectly sorted (default -1)
- kind -- sorting algorithm (default 'quicksort')
- Possible values: 'quicksort', 'mergesort', or 'heapsort'
- order -- If a has fields defined, then the order keyword can be the
- field name to sort on or a list (or tuple) of field names
- to indicate the order that fields should be used to define
- the sort.
+ axis : integer
+ Axis to be indirectly sorted. None indicates that the flattened
+ array should be used. Default is -1.
- Returns: array of indices that sort a along the specified axis.
+ kind : string
+ Sorting algorithm to use. Possible values are 'quicksort',
+ 'mergesort', or 'heapsort'. Default is 'quicksort'.
- This method executes 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.
+ 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.
+ :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
+
+ :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
@@ -681,9 +714,9 @@
|'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.
+ 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.
"""))
@@ -771,8 +804,59 @@
add_newdoc('numpy.core.multiarray', 'ndarray', ('diagonal',
- """a.diagonal(offset=0, axis1=0, axis2=1)
+ """a.diagonal(offset=0, axis1=0, axis2=1) -> diagonals
+ If a is 2-d, return the diagonal of self with the given offset, i.e., the
+ collection of elements of the form a[i,i+offset]. If a is n-d with n > 2,
+ then the axes specified by axis1 and axis2 are used to determine the 2-d
+ 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 2-d subarrays from which
+ the diagonals should be taken. Defaults to first index.
+ axis2 : integer
+ Axis to be used as the second axis of the 2-d subarrays from which
+ the diagonals should be taken. Defaults to second index.
+
+ :Returns:
+ array_of_diagonals : same type as original array
+ If a is 2-d, then a 1-d array containing the diagonal is returned.
+ If a is n-d, n > 2, then an array of diagonals is returned.
+
+ :SeeAlso:
+ - diag : matlab workalike for 1-d and 2-d arrays.
+ - diagflat : creates 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]])
+
"""))
@@ -836,31 +920,37 @@
Returns the average of the array elements. The average is taken over the
flattened array by default, otherwise over the specified axis.
-
+
:Parameters:
+
axis : integer
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.
+
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.
:Returns:
+
mean : 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.
:SeeAlso:
+
- var : variance
- std : standard deviation
Notes
-----
+
The mean is the sum of the elements along the axis divided by the
number of elements.
@@ -943,7 +1033,7 @@
Return a new array from this one. The new array must have the same number
of elements as self. Also always returns a view or raises a ValueError if
- that is impossible.;
+ that is impossible.
"""))
@@ -988,46 +1078,38 @@
add_newdoc('numpy.core.multiarray', 'ndarray', ('searchsorted',
"""a.searchsorted(v, side='left') -> index array.
- Required arguments:
- v -- array of keys to be searched for in a.
+ 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.
- Keyword arguments:
- side -- {'left', 'right'}, (default 'left').
+ :Parameters:
- Returns:
- index array with the same shape as keys.
+ v : array or list type
+ Array of keys to be searched for in a.
- The array to be searched must be 1-D and is assumed to be sorted in
- ascending order.
+ side : string
+ Possible values are : 'left', 'right'. Default is 'left'. Return
+ the first or last index where the key could be inserted.
- The method call
+ :Returns:
- a.searchsorted(v, side='left')
+ indices : integer array
+ The returned array has the same shape as v.
- returns an index array with the same shape as v such that for each value i
- in the index and the corresponding key in v the following holds:
+ :SeeAlso:
- a[j] < key <= a[i] for all j < i,
+ - sort
+ - histogram
- If such an index does not exist, a.size() is used. Consequently, i is the
- index of the first item in 'a' that is >= key. If the key were to be
- inserted into a in the slot before the index i, then the order of a would
- be preserved and i would be the smallest index with that property.
+ :Notes:
+ -------
- The method call
+ 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.
- a.searchsorted(v, side='right')
-
- returns an index array with the same shape as v such that for each value i
- in the index and the corresponding key in v the following holds:
-
- a[j] <= key < a[i] for all j < i,
-
- If such an index does not exist, a.size() is used. Consequently, i is the
- index of the first item in 'a' that is > key. If the key were to be
- inserted into a in the slot before the index i, then the order of a would
- be preserved and i would be the largest index with that property.
-
"""))
@@ -1047,28 +1129,41 @@
add_newdoc('numpy.core.multiarray', 'ndarray', ('sort',
"""a.sort(axis=-1, kind='quicksort', order=None) -> None.
- Sort a along the given axis.
+ Perform an inplace sort along the given axis using the algorithm specified
+ by the kind keyword.
- Keyword arguments:
+ :Parameters:
- axis -- axis to be sorted (default -1)
- kind -- sorting algorithm (default 'quicksort')
- Possible values: 'quicksort', 'mergesort', or 'heapsort'.
- order -- If a has fields defined, then the order keyword can be the
- field name to sort on or a list (or tuple) of field names
- to indicate the order that fields should be used to define
- the sort.
+ axis : integer
+ Axis to be sorted along. None indicates that the flattened array
+ should be used. Default is -1.
- Returns: None.
+ kind : string
+ Sorting algorithm to use. Possible values are 'quicksort',
+ 'mergesort', or 'heapsort'. Default is 'quicksort'.
- This method sorts 'a' in place along the given axis using the algorithm
- specified by the kind keyword.
+ 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.
- The various sorts may characterized by average speed, worst case
+ :Returns:
+
+ None
+
+ :SeeAlso:
+
+ - argsort : indirect sort
+ - 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 and is most
- useful when used with argsort where the key might differ from the items
- being sorted. The three available algorithms have the following properties:
+ 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|
@@ -1078,9 +1173,9 @@
|'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.
+ 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.
"""))
@@ -1099,24 +1194,29 @@
flattened array by default, otherwise over the specified axis.
:Parameters:
+
axis : integer
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.
+
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.
: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.
:SeeAlso:
+
- var : variance
- mean : average
@@ -1277,24 +1377,29 @@
otherwise over the specified axis.
:Parameters:
+
axis : integer
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.
+
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.
:Returns:
+
variance : 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.
:SeeAlso:
+
- std : standard deviation
- mean: average
@@ -1315,4 +1420,3 @@
Type can be either a new sub-type object or a data-descriptor object
"""))
-
Modified: trunk/numpy/core/defmatrix.py
===================================================================
--- trunk/numpy/core/defmatrix.py 2007-05-12 19:58:43 UTC (rev 3751)
+++ trunk/numpy/core/defmatrix.py 2007-05-13 00:35:09 UTC (rev 3752)
@@ -247,29 +247,35 @@
the flattened array by default, otherwise over the specified axis.
:Parameters:
+
axis : integer
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.
+
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.
:Returns:
+
mean : 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.
:SeeAlso:
+
- var : variance
- std : standard deviation
Notes
-----
+
The mean is the sum of the elements along the axis divided by the
number of elements.
@@ -284,25 +290,30 @@
flattened array by default, otherwise over the specified axis.
:Parameters:
+
axis : integer
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.
+
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.
: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.
:SeeAlso:
+
- var : variance
- mean : average
@@ -326,24 +337,29 @@
default, otherwise over the specified axis.
:Parameters:
+
axis : integer
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.
+
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.
:Returns:
+
variance : depends, see above
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
Modified: trunk/numpy/core/fromnumeric.py
===================================================================
--- trunk/numpy/core/fromnumeric.py 2007-05-12 19:58:43 UTC (rev 3751)
+++ trunk/numpy/core/fromnumeric.py 2007-05-13 00:35:09 UTC (rev 3752)
@@ -40,6 +40,7 @@
result = wrap(result)
return result
+
def take(a, indices, axis=None, out=None, mode='raise'):
"""Return an array with values pulled from the given array at the given
indices.
@@ -54,7 +55,7 @@
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.
+ 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.
@@ -76,6 +77,7 @@
return _wrapit(a, 'take', indices, axis, out, mode)
return take(indices, axis, out, mode)
+
# 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
@@ -104,6 +106,7 @@
return _wrapit(a, 'reshape', newshape, order=order)
return reshape(newshape, order=order)
+
def choose(a, choices, out=None, mode='raise'):
"""Use an index array to construct a new array from a set of choices.
@@ -134,7 +137,7 @@
numpy.ndarray.choose() is the equivalent method.
:Example:
- >>> choices = [[0, 1, 2, 3], [10, 11, 12, 13],
+ >>> 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])
@@ -142,7 +145,7 @@
array([20, 31, 12, 3])
>>> choose([2, 4, 1, 0], choices, mode='wrap')
array([20, 1, 12, 3])
-
+
"""
try:
choose = a.choose
@@ -150,6 +153,7 @@
return _wrapit(a, 'choose', choices, out=out, mode=mode)
return choose(choices, out=out, mode=mode)
+
def repeat(a, repeats, axis=None):
"""Repeat elements of an array.
@@ -174,7 +178,7 @@
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
@@ -182,6 +186,7 @@
return _wrapit(a, 'repeat', repeats, axis)
return repeat(repeats, axis)
+
def put (a, ind, v, mode='raise'):
"""put(a, ind, v) results in a[n] = v[n] for all n in ind
If v is shorter than mask it will be repeated as necessary.
@@ -196,6 +201,7 @@
"""
return a.put(ind, v, mode)
+
def swapaxes(a, axis1, axis2):
"""swapaxes(a, axis1, axis2) returns array a with axis1 and axis2
interchanged.
@@ -206,6 +212,7 @@
return _wrapit(a, 'swapaxes', axis1, axis2)
return swapaxes(axis1, axis2)
+
def transpose(a, axes=None):
"""transpose(a, axes=None) returns a view of the array with
dimensions permuted according to axes. If axes is None
@@ -217,31 +224,48 @@
return _wrapit(a, 'transpose', axes)
return transpose(axes)
+
def sort(a, axis=-1, kind='quicksort', order=None):
- """Returns copy of 'a' sorted along the given axis.
+ """Return copy of 'a' sorted along the given axis.
- Keyword arguments:
+ Perform an inplace sort along the given axis using the algorithm specified
+ by the kind keyword.
- axis -- axis to be sorted (default -1). Can be None
- to indicate that a flattened and sorted array should
- be returned (the array method does not support this).
- kind -- sorting algorithm (default 'quicksort')
- Possible values: 'quicksort', 'mergesort', or 'heapsort'.
- order -- For an array with fields defined, this argument allows
- specification of which fields to compare first, second,
- etc. Not all fields need be specified.
+ :Parameters:
+ a : array type
+ Array to be sorted.
- Returns: None.
+ axis : integer
+ Axis to be sorted along. None indicates that the flattened array
+ should be used. Default is -1.
- This method sorts 'a' in place along the given axis using the algorithm
- specified by the kind keyword.
+ kind : string
+ Sorting algorithm to use. Possible values are 'quicksort',
+ 'mergesort', or 'heapsort'. Default is 'quicksort'.
- The various sorts may characterized by average speed, worst case
+ 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.
+
+ :Returns:
+
+ sorted array : type is unchanged.
+
+ :SeeAlso:
+
+ - argsort : indirect sort
+ - 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 and is most
- useful when used with argsort where the key might differ from the items
- being sorted. The three available algorithms have the following properties:
+ 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|
@@ -251,9 +275,9 @@
|'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.
+ 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:
@@ -264,26 +288,45 @@
a.sort(axis, kind, order)
return a
+
def argsort(a, axis=-1, kind='quicksort', order=None):
"""Returns array of indices that index 'a' in sorted order.
- Keyword arguments:
+ 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.
- axis -- axis to be indirectly sorted (default -1)
- Can be None to indicate return indices into the
- flattened array.
- kind -- sorting algorithm (default 'quicksort')
- Possible values: 'quicksort', 'mergesort', or 'heapsort'
- order -- For an array with fields defined, this argument allows
- specification of which fields to compare first, second,
- etc. Not all fields need be specified.
+ :Parameters:
- Returns: array of indices that sort 'a' along the specified axis.
+ a : array type
+ Array containing values that the returned indices should sort.
- This method executes 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.
+ 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.
+
+ :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
+
+ :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
@@ -308,6 +351,7 @@
return _wrapit(a, 'argsort', axis, kind, order)
return argsort(axis, kind, order)
+
def argmax(a, axis=None):
"""argmax(a,axis=None) returns the indices to the maximum value of the
1-D arrays along the given axis.
@@ -318,6 +362,7 @@
return _wrapit(a, 'argmax', axis)
return argmax(axis)
+
def argmin(a, axis=None):
"""argmin(a,axis=None) returns the indices to the minimum value of the
1-D arrays along the given axis.
@@ -328,50 +373,45 @@
return _wrapit(a, 'argmin', axis)
return argmin(axis)
+
def searchsorted(a, v, side='left'):
- """-> index array. Inserting v[i] before a[index[i]] maintains a in order.
+ """Returns indices where keys in v should be inserted to maintain order.
- Required arguments:
- a -- sorted 1-D array to be searched.
- v -- array of keys to be searched for in a.
+ 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.
- Keyword arguments:
- side -- {'left', 'right'}, default('left').
+ :Parameters:
- Returns:
- array of indices with the same shape as v.
+ a : array
+ 1-d array sorted in ascending order.
- The array to be searched must be 1-D and is assumed to be sorted in
- ascending order.
+ v : array or list type
+ Array of keys to be searched for in a.
- The function call
+ side : string
+ Possible values are : 'left', 'right'. Default is 'left'. Return
+ the first or last index where the key could be inserted.
- searchsorted(a, v, side='left')
+ :Returns:
- returns an index array with the same shape as v such that for each value i
- in the index and the corresponding key in v the following holds:
+ indices : integer array
+ Array of insertion points with the same shape as v.
- a[j] < key <= a[i] for all j < i,
+ :SeeAlso:
- If such an index does not exist, a.size() is used. Consequently, i is the
- index of the first item in 'a' that is >= key. If the key were to be
- inserted into a in the slot before the index i, then the order of a would
- be preserved and i would be the smallest index with that property.
+ - sort
+ - histogram
- The function call
+ :Notes:
+ -------
- searchsorted(a, v, side='right')
+ 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.
- returns an index array with the same shape as v such that for each value i
- in the index and the corresponding key in v the following holds:
-
- a[j] <= key < a[i] for all j < i,
-
- If such an index does not exist, a.size() is used. Consequently, i is the
- index of the first item in 'a' that is > key. If the key were to be
- inserted into a in the slot before the index i, then the order of a would
- be preserved and i would be the largest index with that property.
-
"""
try:
searchsorted = a.searchsorted
@@ -379,6 +419,7 @@
return _wrapit(a, 'searchsorted', v, side)
return searchsorted(v, side)
+
def resize(a, new_shape):
"""resize(a,new_shape) returns a new array with the specified shape.
The original array's total size can be any size. It
@@ -410,6 +451,7 @@
return reshape(a, new_shape)
+
def squeeze(a):
"Returns a with any ones from the shape of a removed"
try:
@@ -418,12 +460,65 @@
return _wrapit(a, 'squeeze')
return squeeze()
+
def diagonal(a, offset=0, axis1=0, axis2=1):
- """diagonal(a, offset=0, axis1=0, axis2=1) returns the given diagonals
- defined by the last two dimensions of the array.
+ """Return specified diagonals. Uses first two indices by default.
+
+ If a is 2-d, return the diagonal of self with the given offset, i.e., the
+ collection of elements of the form a[i,i+offset]. If a is n-d with n > 2,
+ then the axes specified by axis1 and axis2 are used to determine the 2-d
+ 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 2-d subarrays from which
+ the diagonals should be taken. Defaults to first axis.
+ axis2 : integer
+ 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 : same type as original array
+ If a is 2-d, then a 1-d array containing the diagonal is returned.
+ If a is n-d, n > 2, then an array of diagonals is returned.
+
+ :SeeAlso:
+ - diag : matlab workalike for 1-d and 2-d arrays
+ - diagflat : creates 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)
+
def trace(a, offset=0, axis1=0, axis2=1, dtype=None, out=None):
"""trace(a,offset=0, axis1=0, axis2=1) returns the sum along diagonals
(defined by the last two dimenions) of the array.
@@ -697,29 +792,35 @@
flattened array by default, otherwise over the specified axis.
:Parameters:
+
axis : integer
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.
+
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.
:Returns:
+
mean : 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.
:SeeAlso:
+
- var : variance
- std : standard deviation
Notes
-----
+
The mean is the sum of the elements along the axis divided by the
number of elements.
@@ -739,24 +840,29 @@
flattened array by default, otherwise over the specified axis.
:Parameters:
+
axis : integer
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.
+
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.
: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.
:SeeAlso:
+
- var : variance
- mean : average
@@ -784,24 +890,29 @@
otherwise over the specified axis.
:Parameters:
+
axis : integer
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.
+
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.
:Returns:
+
variance : depends, see above
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
More information about the Numpy-svn
mailing list