diff options
| -rw-r--r-- | numpy/add_newdocs.py | 49 | ||||
| -rw-r--r-- | numpy/core/fromnumeric.py | 166 | ||||
| -rw-r--r-- | numpy/lib/arraysetops.py | 174 | ||||
| -rw-r--r-- | numpy/lib/financial.py | 8 | ||||
| -rw-r--r-- | numpy/lib/function_base.py | 98 | ||||
| -rw-r--r-- | numpy/lib/index_tricks.py | 82 |
6 files changed, 388 insertions, 189 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 85577836b..c44ba9094 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -569,27 +569,32 @@ add_newdoc('numpy.core.multiarray','getbuffer', add_newdoc('numpy.core.multiarray', 'ndarray', - """An array object represents a multidimensional, homogeneous array + """ + An array object represents a multidimensional, homogeneous array of fixed-size items. An associated data-type-descriptor object details the data-type in an array (including byteorder and any - fields). An array can be constructed using the numpy.array + fields). An array can be constructed using the `numpy.array` command. Arrays are sequence, mapping and numeric objects. More information is available in the numpy module and by looking at the methods and attributes of an array. - ndarray.__new__(subtype, shape=, dtype=float, buffer=None, - offset=0, strides=None, order=None) + :: + + ndarray.__new__(subtype, shape=, dtype=float, buffer=None, + offset=0, strides=None, order=None) + + There are two modes of creating an array using __new__: + + 1. If buffer is None, then only shape, dtype, and order + are used + 2. If buffer is an object exporting the buffer interface, then + all keywords are interpreted. - There are two modes of creating an array using __new__: - 1) If buffer is None, then only shape, dtype, and order - are used - 2) If buffer is an object exporting the buffer interface, then - all keywords are interpreted. - The dtype parameter can be any object that can be interpreted - as a numpy.dtype object. + The dtype parameter can be any object that can be interpreted as + a numpy.dtype object. - No __init__ method is needed because the array is fully - initialized after the __new__ method. + No __init__ method is needed because the array is fully initialized + after the __new__ method. """) @@ -1109,7 +1114,8 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('copy', add_newdoc('numpy.core.multiarray', 'ndarray', ('cumprod', - """a.cumprod(axis=None, dtype=None, out=None) + """ + a.cumprod(axis=None, dtype=None, out=None) Return the cumulative product of the elements along the given axis. @@ -1120,7 +1126,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('cumprod', ---------- axis : {None, -1, int}, optional Axis along which the product is computed. The default - (``axis``= None) is to compute over the flattened array. + (`axis` = None) is to compute over the flattened array. 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 @@ -1158,7 +1164,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('cumsum', ---------- axis : {None, -1, int}, optional Axis along which the sum is computed. The default - (``axis``= None) is to compute over the flattened array. + (`axis` = None) is to compute over the flattened array. 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 @@ -1185,7 +1191,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('cumsum', add_newdoc('numpy.core.multiarray', 'ndarray', ('diagonal', - """a.diagonal(offset=0, axis1=0, axis2=1) -> diagonals + """a.diagonal(offset=0, axis1=0, axis2=1) 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, @@ -1233,7 +1239,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('diagonal', >>> a array([[[0, 1], [2, 3]], - + <BLANKLINE> [[4, 5], [6, 7]]]) >>> a.diagonal(0,-2,-1) @@ -1410,7 +1416,7 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('nonzero', the indices of the non-zero elements in that dimension. The corresponding non-zero values can be obtained with:: - a[a.nonzero()]. + a[a.nonzero()] To group the indices by element, rather than dimension, use:: @@ -1647,7 +1653,6 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('repeat', add_newdoc('numpy.core.multiarray', 'ndarray', ('reshape', """a.reshape(shape, order='C') - a.reshape(*shape, order='C') Returns an array containing the data of a, but with a new shape. @@ -1967,13 +1972,13 @@ add_newdoc('numpy.core.multiarray', 'ndarray', ('swapaxes', >>> x array([[[0, 1], [2, 3]], - + <BLANKLINE> [[4, 5], [6, 7]]]) >>> x.swapaxes(0,2) array([[[0, 4], [2, 6]], - + <BLANKLINE> [[1, 5], [3, 7]]]) diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py index 7cde300d9..9f433d17b 100644 --- a/numpy/core/fromnumeric.py +++ b/numpy/core/fromnumeric.py @@ -257,7 +257,7 @@ def put(a, ind, v, mode='raise'): def swapaxes(a, axis1, axis2): """Return a view of array a with axis1 and axis2 interchanged. - + Parameters ---------- a : array_like @@ -369,13 +369,13 @@ def sort(a, axis=-1, kind='quicksort', order=None): 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 - =========== ======= ============= ============ ======= + =========== ======= ============= ============ ======= + '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 @@ -880,7 +880,7 @@ def compress(condition, a, axis=None, out=None): [3]]) >>> np.compress([0,1,1], a) array([2, 3]) - + """ try: compress = a.compress @@ -1051,22 +1051,59 @@ def product (a, axis=None, dtype=None, out=None): return prod(axis, dtype, out) -def sometrue (a, axis=None, out=None): - """Check if any of the elements of `a` are true. +def sometrue(a, axis=None, out=None): + """ + Assert whether some values are true. - Performs a logical_or over the given axis and returns the result + `sometrue` performs a logical_or over the given axis. Parameters ---------- - a : {array_like} - Array on which to operate + a : array_like + Array on which to operate. + axis : {None, integer} + Axis to perform the operation over. + If `None` (default), perform over flattened array. + out : {None, array}, optional + Array into which the product can be placed. Its type is preserved + and it must be of the right shape to hold the output. + + See Also + -------- + ndarray.any : equivalent method + + Examples + -------- + >>> b = numpy.array([True, False, True, True]) + >>> numpy.sometrue(b) + True + >>> a = numpy.array([1, 5, 2, 7]) + >>> numpy.sometrue(a >= 5) + True + + """ + try: + any = a.any + except AttributeError: + return _wrapit(a, 'any', axis, out) + return any(axis, out) + + +def alltrue (a, axis=None, out=None): + """Check if all of the elements of `a` are true. + + Performs a logical_and over the given axis and returns the result + + Parameters + ---------- + a : array_like axis : {None, integer} Axis to perform the operation over. If None, perform over flattened array. out : {None, array}, optional Array into which the product can be placed. Its type is preserved and it must be of the right shape to hold the output. - + See Also -------- ndarray.any : equivalent method @@ -1086,14 +1123,14 @@ def alltrue (a, axis=None, out=None): Parameters ---------- - a : {array_like} + a : array_like axis : {None, integer} Axis to perform the operation over. If None, perform over flattened array. out : {None, array}, optional Array into which the product can be placed. Its type is preserved and it must be of the right shape to hold the output. - + See Also -------- ndarray.all : equivalent method @@ -1108,19 +1145,19 @@ def alltrue (a, axis=None, out=None): def any(a,axis=None, out=None): """Check if any of the elements of `a` are true. - + Performs a logical_or over the given axis and returns the result Parameters ---------- - a : {array_like} + a : array_like axis : {None, integer} Axis to perform the operation over. If None, perform over flattened array and return a scalar. out : {None, array}, optional Array into which the product can be placed. Its type is preserved and it must be of the right shape to hold the output. - + See Also -------- ndarray.any : equivalent method @@ -1135,19 +1172,19 @@ def any(a,axis=None, out=None): def all(a,axis=None, out=None): """Check if all of the elements of `a` are true. - + Performs a logical_and over the given axis and returns the result Parameters ---------- - a : {array_like} + a : array_like axis : {None, integer} Axis to perform the operation over. If None, perform over flattened array and return a scalar. out : {None, array}, optional Array into which the product can be placed. Its type is preserved and it must be of the right shape to hold the output. - + See Also -------- ndarray.all : equivalent method @@ -1161,10 +1198,8 @@ def all(a,axis=None, out=None): def cumsum (a, axis=None, dtype=None, out=None): - """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. + """ + Return the cumulative sum of the elements along a given axis. Parameters ---------- @@ -1172,13 +1207,13 @@ def cumsum (a, axis=None, dtype=None, out=None): Input array or object that can be converted to an array. axis : {None, -1, int}, optional Axis along which the sum is computed. The default - (``axis``= None) is to compute over the flattened array. + (`axis` = `None`) is to compute over the flattened array. 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. + Type of the returned array and of the accumulator in which the + elements are summed. If `dtype` is not specified, it defaults + to the dtype of `a`, unless `a` has an integer dtype with a + precision less than that of the default platform integer. In + that case, the default platform integer is used. 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 @@ -1187,14 +1222,30 @@ def cumsum (a, axis=None, dtype=None, out=None): Returns ------- cumsum : ndarray. - 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. Notes ----- Arithmetic is modular when using integer types, and no error is raised on overflow. + + Examples + -------- + >>> import numpy + >>> a=numpy.array([[1,2,3],[4,5,6]]) + >>> numpy.cumsum(a) # cumulative sum = intermediate summing results & total sum. Default axis=None results in raveling the array first. + array([ 1, 3, 6, 10, 15, 21]) + >>> numpy.cumsum(a,dtype=float) # specifies type of output value(s) + array([ 1., 3., 6., 10., 15., 21.]) + >>> numpy.cumsum(a,axis=0) # sum over rows for each of the 3 columns + array([[1, 2, 3], + [5, 7, 9]]) + >>> numpy.cumsum(a,axis=1) # sum over columns for each of the 2 rows + array([[ 1, 3, 6], + [ 4, 9, 15]]) + """ try: cumsum = a.cumsum @@ -1273,7 +1324,7 @@ def amax(a, axis=None, out=None): Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. - Results + Returns ------- amax : array_like New array holding the result, unless ``out`` was specified. @@ -1311,7 +1362,7 @@ def amin(a, axis=None, out=None): Alternative output array in which to place the result. Must be of the same shape and buffer length as the expected output. - Results + Returns ------- amin : array_like New array holding the result, unless ``out`` was specified. @@ -1336,7 +1387,8 @@ def amin(a, axis=None, out=None): def alen(a): - """Return the length of a Python object interpreted as an array + """ + Return the length of a Python object interpreted as an array of at least 1 dimension. Parameters @@ -1346,14 +1398,14 @@ def alen(a): Returns ------- alen : int - Length of the first dimension of a. + Length of the first dimension of `a`. Examples -------- - >>> z = np.zeros((7,4,5)) + >>> z = numpy.zeros((7,4,5)) >>> z.shape[0] 7 - >>> np.alen(z) + >>> numpy.alen(z) 7 """ @@ -1421,7 +1473,8 @@ def prod(a, axis=None, dtype=None, out=None): def cumprod(a, axis=None, dtype=None, out=None): - """Return the cumulative product of the elements along the given axis. + """ + Return the cumulative product of the elements along the given axis. The cumulative product is taken over the flattened array by default, otherwise over the specified axis. @@ -1432,13 +1485,13 @@ def cumprod(a, axis=None, dtype=None, out=None): 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. + (`axis` = `None`) is to compute over the flattened array. 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 + 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. + used. Otherwise, the `dtype` is the same as that of `a`. 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 @@ -1447,7 +1500,7 @@ def cumprod(a, axis=None, dtype=None, out=None): Returns ------- cumprod : ndarray. - A new array holding the result is returned unless out is + A new array holding the result is returned unless `out` is specified, in which case a reference to out is returned. Notes @@ -1455,6 +1508,25 @@ def cumprod(a, axis=None, dtype=None, out=None): Arithmetic is modular when using integer types, and no error is raised on overflow. + Examples + -------- + >>> a=numpy.array([[1,2,3],[4,5,6]]) + >>> a=numpy.array([1,2,3]) + >>> numpy.cumprod(a) # intermediate results 1, 1*2 + ... # total product 1*2*3 = 6 + array([1, 2, 6]) + >>> a=numpy.array([[1,2,3],[4,5,6]]) + >>> numpy.cumprod(a,dtype=float) # specify type of output + array([ 1., 2., 6., 24., 120., 720.]) + >>> numpy.cumprod(a,axis=0) # for each of the 3 columns: + ... # product and intermediate results + array([[ 1, 2, 3], + [ 4, 10, 18]]) + >>> numpy.cumprod(a,axis=1) # for each of the two rows: + ... # product and intermediate results + array([[ 1, 2, 6], + [ 4, 20, 120]]) + """ try: cumprod = a.cumprod diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py index f8304cced..ad8d2d645 100644 --- a/numpy/lib/arraysetops.py +++ b/numpy/lib/arraysetops.py @@ -38,23 +38,26 @@ __all__ = ['ediff1d', 'unique1d', 'intersect1d', 'intersect1d_nu', 'setxor1d', import time import numpy as nm -def ediff1d(ary, to_end = None, to_begin = None): +def ediff1d(ary, to_end=None, to_begin=None): """The differences between consecutive elements of an array, possibly with prefixed and/or appended values. - :Parameters: - - `ary` : array + Parameters + ---------- + ary : array This array will be flattened before the difference is taken. - - `to_end` : number, optional + to_end : number, optional If provided, this number will be tacked onto the end of the returned differences. - - `to_begin` : number, optional + to_begin : number, optional If provided, this number will be taked onto the beginning of the returned differences. - :Returns: - - `ed` : array + Returns + ------- + ed : array The differences. Loosely, this will be (ary[1:] - ary[:-1]). + """ ary = nm.asarray(ary).flat ed = ary[1:] - ary[:-1] @@ -77,22 +80,26 @@ def unique1d(ar1, return_index=False): Most of the other array set operations operate on the unique arrays generated by this function. - :Parameters: - - `ar1` : array + Parameters + ---------- + ar1 : array This array will be flattened if it is not already 1D. - - `return_index` : bool, optional + return_index : bool, optional If True, also return the indices against ar1 that result in the unique array. - :Returns: - - `unique` : array + Returns + ------- + unique : array The unique values. - - `unique_indices` : int array, optional + unique_indices : int array, optional The indices of the unique values. Only provided if return_index is True. - :See also: - numpy.lib.arraysetops has a number of other functions for performing set - operations on arrays. + See Also + -------- + numpy.lib.arraysetops : Module with a number of other functions + for performing set operations on arrays. + """ ar = nm.asarray(ar1).flatten() if ar.size == 0: @@ -110,66 +117,78 @@ def unique1d(ar1, return_index=False): flag = nm.concatenate( ([True], ar[1:] != ar[:-1]) ) return ar[flag] -def intersect1d( ar1, ar2 ): +def intersect1d(ar1, ar2): """Intersection of 1D arrays with unique elements. Use unique1d() to generate arrays with only unique elements to use as inputs to this function. Alternatively, use intersect1d_nu() which will find the unique values for you. - :Parameters: - - `ar1` : array - - `ar2` : array + Parameters + ---------- + ar1 : array + ar2 : array + + Returns + ------- + intersection : array - :Returns: - - `intersection` : array + See Also + -------- + numpy.lib.arraysetops : Module with a number of other functions for + performing set operations on arrays. - :See also: - numpy.lib.arraysetops has a number of other functions for performing set - operations on arrays. """ aux = nm.concatenate((ar1,ar2)) aux.sort() return aux[aux[1:] == aux[:-1]] -def intersect1d_nu( ar1, ar2 ): +def intersect1d_nu(ar1, ar2): """Intersection of 1D arrays with any elements. The input arrays do not have unique elements like intersect1d() requires. - :Parameters: - - `ar1` : array - - `ar2` : array + Parameters + ---------- + ar1 : array + ar2 : array - :Returns: - - `intersection` : array + Returns + ------- + intersection : array + + See Also + -------- + numpy.lib.arraysetops : Module with a number of other functions for + performing set operations on arrays. - :See also: - numpy.lib.arraysetops has a number of other functions for performing set - operations on arrays. """ # Might be faster than unique1d( intersect1d( ar1, ar2 ) )? aux = nm.concatenate((unique1d(ar1), unique1d(ar2))) aux.sort() return aux[aux[1:] == aux[:-1]] -def setxor1d( ar1, ar2 ): +def setxor1d(ar1, ar2): """Set exclusive-or of 1D arrays with unique elements. Use unique1d() to generate arrays with only unique elements to use as inputs to this function. - :Parameters: - - `ar1` : array - - `ar2` : array + Parameters + ---------- + ar1 : array + ar2 : array - :Returns: - - `xor` : array + Returns + ------- + xor : array The values that are only in one, but not both, of the input arrays. - :See also: - numpy.lib.arraysetops has a number of other functions for performing set - operations on arrays. + See Also + -------- + numpy.lib.arraysetops : Module with a number of other functions for + performing set operations on arrays. + """ aux = nm.concatenate((ar1, ar2)) if aux.size == 0: @@ -182,24 +201,28 @@ def setxor1d( ar1, ar2 ): flag2 = flag[1:] == flag[:-1] return aux[flag2] -def setmember1d( ar1, ar2 ): +def setmember1d(ar1, ar2): """Return a boolean array of shape of ar1 containing True where the elements of ar1 are in ar2 and False otherwise. Use unique1d() to generate arrays with only unique elements to use as inputs to this function. - :Parameters: - - `ar1` : array - - `ar2` : array + Parameters + ---------- + ar1 : array + ar2 : array - :Returns: - - `mask` : bool array + Returns + ------- + mask : bool array The values ar1[mask] are in ar2. - :See also: - numpy.lib.arraysetops has a number of other functions for performing set - operations on arrays. + See Also + -------- + numpy.lib.arraysetops : Module with a number of other functions for + performing set operations on arrays. + """ ar1 = nm.asarray( ar1 ) ar2 = nm.asarray( ar2 ) @@ -225,42 +248,51 @@ def setmember1d( ar1, ar2 ): return flag[indx] -def union1d( ar1, ar2 ): - """Union of 1D arrays with unique elements. +def union1d(ar1, ar2): + """ + Union of 1D arrays with unique elements. Use unique1d() to generate arrays with only unique elements to use as inputs to this function. - :Parameters: - - `ar1` : array - - `ar2` : array + Parameters + ---------- + ar1 : array + ar2 : array - :Returns: - - `union` : array + Returns + ------- + union : array + + See also + -------- + numpy.lib.arraysetops : Module with a number of other functions for + performing set operations on arrays. - :See also: - numpy.lib.arraysetops has a number of other functions for performing set - operations on arrays. """ return unique1d( nm.concatenate( (ar1, ar2) ) ) -def setdiff1d( ar1, ar2 ): +def setdiff1d(ar1, ar2): """Set difference of 1D arrays with unique elements. Use unique1d() to generate arrays with only unique elements to use as inputs to this function. - :Parameters: - - `ar1` : array - - `ar2` : array + Parameters + ---------- + ar1 : array + ar2 : array - :Returns: - - `difference` : array + Returns + ------- + difference : array The values in ar1 that are not in ar2. - :See also: - numpy.lib.arraysetops has a number of other functions for performing set - operations on arrays. + See Also + -------- + numpy.lib.arraysetops : Module with a number of other functions for + performing set operations on arrays. + """ aux = setmember1d(ar1,ar2) if aux.size == 0: diff --git a/numpy/lib/financial.py b/numpy/lib/financial.py index 2a751281f..a3552ebc0 100644 --- a/numpy/lib/financial.py +++ b/numpy/lib/financial.py @@ -88,8 +88,8 @@ def pmt(rate, nper, pv, fv=0, when='end'): fact = np.where(rate==zer, nper+zer, (1+rate*when)*(temp-1)/rate+zer) return -(fv + pv*temp) / fact pmt.__doc__ += eqstr + """ -Example -------- +Examples +-------- What would the monthly payment need to be to pay off a $200,000 loan in 15 years at an annual interest rate of 7.5%? @@ -116,8 +116,8 @@ def nper(rate, pmt, pv, fv=0, when='end'): zer = np.zeros(miter.shape) return np.where(rate==zer, A+zer, B+zer) + 0.0 nper.__doc__ += eqstr + """ -Example -------- +Examples +-------- If you only had $150 to spend as payment, how long would it take to pay-off a loan of $8,000 at 7% annual interest? diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py index 8aed772d1..4236ca1bb 100644 --- a/numpy/lib/function_base.py +++ b/numpy/lib/function_base.py @@ -809,7 +809,16 @@ def interp(x, xp, fp, left=None, right=None): def angle(z, deg=0): - """Return the angle of the complex argument z. + """ + Return the angle of the complex argument z. + + Examples + -------- + >>> numpy.angle(1+1j) # in radians + 0.78539816339744828 + >>> numpy.angle(1+1j,deg=True) # in degrees + 45.0 + """ if deg: fact = 180/pi @@ -889,11 +898,12 @@ if sys.hexversion < 0x2040000: from sets import Set as set def unique(x): - """Return sorted unique items from an array or sequence. + """ + Return sorted unique items from an array or sequence. Examples -------- - >>> unique([5,2,4,0,4,4,2,2,1]) + >>> numpy.unique([5,2,4,0,4,4,2,2,1]) array([0, 1, 2, 4, 5]) """ @@ -1187,7 +1197,87 @@ def blackman(M): return 0.42-0.5*cos(2.0*pi*n/(M-1)) + 0.08*cos(4.0*pi*n/(M-1)) def bartlett(M): - """bartlett(M) returns the M-point Bartlett window. + """ + Return the Bartlett window. + + The Bartlett window is very similar to a triangular window, except + that the end points are at zero. It is often used in signal + processing for tapering a signal, without generating too much + ripple in the frequency domain. + + Parameters + ---------- + M : int + Number of points in the output window. If zero or less, an + empty array is returned. + + Returns + ------- + out : array + The triangular window, normalized to one (the value one + appears only if the number of samples is odd), with the first + and last samples equal to zero. + + See Also + -------- + blackman, hamming, hanning, kaiser + + Notes + ----- + The Bartlett window is defined as + + .. math:: w(n) = \frac{2}{M-1} (\frac{M-1}{2} - |n - \frac{M-1}{2}|) + + Most references to the Bartlett window come from the signal + processing literature, where it is used as one of many windowing + functions for smoothing values. Note that convolution with this + window produces linear interpolation. It is also known as an + apodization (which means"removing the foot", i.e. smoothing + discontinuities at the beginning and end of the sampled signal) or + tapering function. + + References + ---------- + .. [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra", + Biometrika 37, 1-16, 1950. + .. [2] A.V. Oppenheim and R.W. Schafer, "Discrete-Time Signal + Processing", Prentice-Hall, 1999, pp. 468-471. + .. [3] Wikipedia, "Window function", + http://en.wikipedia.org/wiki/Window_function + .. [4] W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling, + "Numerical Recipes", Cambridge University Press, 1986, page 429. + + Examples + -------- + >>> from numpy import bartlett + >>> bartlett(12) + array([ 0. , 0.18181818, 0.36363636, 0.54545455, 0.72727273, + 0.90909091, 0.90909091, 0.72727273, 0.54545455, 0.36363636, + 0.18181818, 0. ]) + + # Plot the window and the frequency response of it. + >>> from numpy import clip, log10, array, bartlett + >>> from scipy.fftpack import fft + >>> from matplotlib import pyplot as plt + + >>> window = bartlett(51) + >>> plt.plot(window) + >>> plt.title("Bartlett window") + >>> plt.ylabel("Amplitude") + >>> plt.xlabel("Sample") + >>> plt.show() + + >>> A = fft(window, 2048) / 25.5 + >>> mag = abs(fftshift(A)) + >>> freq = linspace(-0.5,0.5,len(A)) + >>> response = 20*log10(mag) + >>> response = clip(response,-100,100) + >>> plt.plot(freq, response) + >>> plt.title("Frequency response of Bartlett window") + >>> plt.ylabel("Magnitude [dB]") + >>> plt.xlabel("Normalized frequency [cycles per sample]") + >>> plt.axis('tight'); plt.show() + """ if M < 1: return array([]) diff --git a/numpy/lib/index_tricks.py b/numpy/lib/index_tricks.py index 2039d5b5e..4d82161bd 100644 --- a/numpy/lib/index_tricks.py +++ b/numpy/lib/index_tricks.py @@ -83,47 +83,47 @@ def ix_(*args): return tuple(out) class nd_grid(object): - """ Construct a "meshgrid" in N-dimensions. - - grid = nd_grid() creates an instance which will return a mesh-grid - when indexed. The dimension and number of the output arrays are equal - to the number of indexing dimensions. If the step length is not a - complex number, then the stop is not inclusive. - - However, if the step length is a COMPLEX NUMBER (e.g. 5j), then the - integer part of it's magnitude is interpreted as specifying the - number of points to create between the start and stop values, where - the stop value IS INCLUSIVE. - - If instantiated with an argument of sparse=True, the mesh-grid is - open (or not fleshed out) so that only one-dimension of each returned - argument is greater than 1 - - Example: - - >>> mgrid = nd_grid() - >>> mgrid[0:5,0:5] - array([[[0, 0, 0, 0, 0], - [1, 1, 1, 1, 1], - [2, 2, 2, 2, 2], - [3, 3, 3, 3, 3], - [4, 4, 4, 4, 4]], - <BLANKLINE> - [[0, 1, 2, 3, 4], - [0, 1, 2, 3, 4], - [0, 1, 2, 3, 4], - [0, 1, 2, 3, 4], - [0, 1, 2, 3, 4]]]) - >>> mgrid[-1:1:5j] - array([-1. , -0.5, 0. , 0.5, 1. ]) - - >>> ogrid = nd_grid(sparse=True) - >>> ogrid[0:5,0:5] - [array([[0], - [1], - [2], - [3], - [4]]), array([[0, 1, 2, 3, 4]])] + """ + Construct a multi-dimensional "meshgrid". + + grid = nd_grid() creates an instance which will return a mesh-grid + when indexed. The dimension and number of the output arrays are equal + to the number of indexing dimensions. If the step length is not a + complex number, then the stop is not inclusive. + + However, if the step length is a **complex number** (e.g. 5j), then the + integer part of it's magnitude is interpreted as specifying the + number of points to create between the start and stop values, where + the stop value **is inclusive**. + + If instantiated with an argument of sparse=True, the mesh-grid is + open (or not fleshed out) so that only one-dimension of each returned + argument is greater than 1 + + Examples + -------- + >>> mgrid = nd_grid() + >>> mgrid[0:5,0:5] + array([[[0, 0, 0, 0, 0], + [1, 1, 1, 1, 1], + [2, 2, 2, 2, 2], + [3, 3, 3, 3, 3], + [4, 4, 4, 4, 4]], + <BLANKLINE> + [[0, 1, 2, 3, 4], + [0, 1, 2, 3, 4], + [0, 1, 2, 3, 4], + [0, 1, 2, 3, 4], + [0, 1, 2, 3, 4]]]) + >>> mgrid[-1:1:5j] + array([-1. , -0.5, 0. , 0.5, 1. ]) + >>> ogrid = nd_grid(sparse=True) + >>> ogrid[0:5,0:5] + [array([[0], + [1], + [2], + [3], + [4]]), array([[0, 1, 2, 3, 4]])] """ def __init__(self, sparse=False): |