diff options
| -rw-r--r-- | numpy/add_newdocs.py | 45 | ||||
| -rw-r--r-- | numpy/core/code_generators/ufunc_docstrings.py | 15 | ||||
| -rw-r--r-- | numpy/core/fromnumeric.py | 21 | ||||
| -rw-r--r-- | numpy/core/numeric.py | 20 | ||||
| -rw-r--r-- | numpy/lib/arraysetops.py | 39 | ||||
| -rw-r--r-- | numpy/lib/function_base.py | 3 | ||||
| -rw-r--r-- | numpy/lib/twodim_base.py | 123 | ||||
| -rw-r--r-- | numpy/lib/type_check.py | 33 | ||||
| -rw-r--r-- | numpy/linalg/linalg.py | 35 | ||||
| -rw-r--r-- | numpy/ma/core.py | 170 | ||||
| -rw-r--r-- | numpy/random/mtrand/mtrand.pyx | 88 |
11 files changed, 484 insertions, 108 deletions
diff --git a/numpy/add_newdocs.py b/numpy/add_newdocs.py index 86f8461e5..d63b99ee9 100644 --- a/numpy/add_newdocs.py +++ b/numpy/add_newdocs.py @@ -18,6 +18,45 @@ from lib import add_newdoc add_newdoc('numpy.core', 'flatiter', """ + Flat iterator object to iterate over arrays. + + A `flatiter` iterator is returned by ``x.flat`` for any array `x`. + It allows iterating over the array as if it were a 1-D array, + either in a for-loop or by calling its `next` method. + + Iteration is done in C-contiguous style, with the last index varying the + fastest. The iterator can also be indexed using basic slicing or + advanced indexing. + + See Also + -------- + ndarray.flat : Return a flat iterator over an array. + ndarray.flatten : Returns a flattened copy of an array. + + Notes + ----- + A `flatiter` iterator can not be constructed directly from Python code + by calling the `flatiter` constructor. + + Examples + -------- + >>> x = np.arange(6).reshape(2, 3) + >>> fl = x.flat + >>> type(fl) + <type 'numpy.flatiter'> + >>> for item in fl: + ... print item + ... + 0 + 1 + 2 + 3 + 4 + 5 + + >>> fl[2:4] + array([2, 3]) + """) # flatiter attributes @@ -228,11 +267,11 @@ add_newdoc('numpy.core.multiarray', 'empty', """ empty(shape, dtype=float, order='C') - Return a new array of given shape and type, without initialising entries. + Return a new array of given shape and type, without initializing entries. Parameters ---------- - shape : {tuple of int, int} + shape : int or tuple of int Shape of the empty array dtype : data-type, optional Desired output data-type. @@ -242,7 +281,7 @@ add_newdoc('numpy.core.multiarray', 'empty', See Also -------- - empty_like, zeros + empty_like, zeros, ones Notes ----- diff --git a/numpy/core/code_generators/ufunc_docstrings.py b/numpy/core/code_generators/ufunc_docstrings.py index 7744bb4bf..5df2df53d 100644 --- a/numpy/core/code_generators/ufunc_docstrings.py +++ b/numpy/core/code_generators/ufunc_docstrings.py @@ -157,12 +157,19 @@ add_newdoc('numpy.core.umath', 'arccosh', x : array_like Input array. out : ndarray, optional - Array of the same shape as `x`. + Array of the same shape as `x`, to store results in. + See `doc.ufuncs` (Section "Output arguments") for details. + Returns ------- - out : ndarray - Array of the same shape and dtype as `x`. + y : ndarray + Array of the same shape as `x`. + + See Also + -------- + + cosh, arcsinh, sinh, arctanh, tanh Notes ----- @@ -189,6 +196,8 @@ add_newdoc('numpy.core.umath', 'arccosh', -------- >>> np.arccosh([np.e, 10.0]) array([ 1.65745445, 2.99322285]) + >>> np.arccosh(1) + 0.0 """) diff --git a/numpy/core/fromnumeric.py b/numpy/core/fromnumeric.py index f7f584d3d..de8a27d08 100644 --- a/numpy/core/fromnumeric.py +++ b/numpy/core/fromnumeric.py @@ -1351,14 +1351,15 @@ def any(a,axis=None, out=None): a : array_like Input array or object that can be converted to an array. axis : int, optional - Axis along which an logical OR is performed. + Axis along which a logical OR is performed. The default (`axis` = `None`) is to perform a logical OR over a flattened input array. `axis` may be negative, in which case it counts from the last to the first axis. out : ndarray, optional Alternative output array in which to place the result. It must have the same shape as the expected output and - the type is preserved. + the type is preserved. See `doc.ufuncs` (Section + "Output arguments") for details. Returns ------- @@ -1370,6 +1371,9 @@ def any(a,axis=None, out=None): -------- ndarray.any : equivalent method + all : Test whether all array elements along a given axis evaluate + to True. + Notes ----- Not a Number (NaN), positive infinity and negative infinity @@ -1391,8 +1395,13 @@ def any(a,axis=None, out=None): >>> o=np.array([False]) >>> z=np.any([-1, 4, 5], out=o) - >>> id(z), id(o), z - (28224368, 28224368, array([ True], dtype=bool)) + >>> z, o + (array([ True], dtype=bool), array([ True], dtype=bool)) + >>> # Check now that z is a reference to o + >>> z is o + True + >>> id(z), id(o) # identity of z and o + (191614240, 191614240) """ try: @@ -1693,12 +1702,12 @@ def alen(a): Returns ------- - alen : int + l : int Length of the first dimension of `a`. See Also -------- - shape + shape, size Examples -------- diff --git a/numpy/core/numeric.py b/numpy/core/numeric.py index c961bcc0f..abe26aac3 100644 --- a/numpy/core/numeric.py +++ b/numpy/core/numeric.py @@ -48,14 +48,14 @@ ufunc = type(sin) # originally from Fernando Perez's IPython def zeros_like(a): """ - Returns an array of zeros with the same shape and type as a given array. + Return an array of zeros with the same shape and type as a given array. Equivalent to ``a.copy().fill(0)``. Parameters ---------- a : array_like - The shape and data-type of `a` defines the parameters of + The shape and data-type of `a` define the parameters of the returned array. Returns @@ -65,11 +65,11 @@ def zeros_like(a): See Also -------- - numpy.ones_like : Return an array of ones with shape and type of input. - numpy.empty_like : Return an empty array with shape and type of input. - numpy.zeros : Return a new array setting values to zero. - numpy.ones : Return a new array setting values to one. - numpy.empty : Return a new uninitialized array. + ones_like : Return an array of ones with shape and type of input. + empty_like : Return an empty array with shape and type of input. + zeros : Return a new array setting values to zero. + ones : Return a new array setting values to one. + empty : Return a new uninitialized array. Examples -------- @@ -82,6 +82,12 @@ def zeros_like(a): array([[0, 0, 0], [0, 0, 0]]) + >>> y = np.arange(3, dtype=np.float) + >>> y + array([ 0., 1., 2.]) + >>> np.zeros_like(y) + array([ 0., 0., 0.]) + """ if isinstance(a, ndarray): res = ndarray.__new__(type(a), a.shape, a.dtype, order=a.flags.fnc) diff --git a/numpy/lib/arraysetops.py b/numpy/lib/arraysetops.py index b8ae9a9f3..89f82a942 100644 --- a/numpy/lib/arraysetops.py +++ b/numpy/lib/arraysetops.py @@ -40,24 +40,41 @@ def ediff1d(ary, to_end=None, to_begin=None): Parameters ---------- - ary : array - This array will be flattened before the difference is taken. - to_end : number, optional - If provided, this number will be tacked onto the end of the returned - differences. - to_begin : number, optional - If provided, this number will be tacked onto the beginning of the - returned differences. + ary : array_like + If necessary, will be flattened before the differences are taken. + to_end : array_like, optional + Number(s) to append at the end of the returned differences. + to_begin : array_like, optional + Number(s) to prepend at the beginning of the returned differences. Returns ------- - ed : array - The differences. Loosely, this will be (ary[1:] - ary[:-1]). + ed : ndarray + The differences. Loosely, this is ``ary.flat[1:] - ary.flat[:-1]``. + + See Also + -------- + diff, gradient Notes ----- When applied to masked arrays, this function drops the mask information - if the `to_begin` and/or `to_end` parameters are used + if the `to_begin` and/or `to_end` parameters are used. + + Examples + -------- + >>> x = np.array([1, 2, 4, 7, 0]) + >>> np.ediff1d(x) + array([ 1, 2, 3, -7]) + + >>> np.ediff1d(x, to_begin=-99, to_end=np.array([88, 99])) + array([-99, 1, 2, 3, -7, 88, 99]) + + The returned array is always 1D. + + >>> y = [[1, 2, 4], [1, 6, 24]] + >>> np.ediff1d(y) + array([ 1, 2, -3, 5, 18]) """ ary = np.asanyarray(ary).flat diff --git a/numpy/lib/function_base.py b/numpy/lib/function_base.py index 73526a84c..6956bf366 100644 --- a/numpy/lib/function_base.py +++ b/numpy/lib/function_base.py @@ -1031,6 +1031,9 @@ def angle(z, deg=0): See Also -------- arctan2 + absolute + + Examples -------- diff --git a/numpy/lib/twodim_base.py b/numpy/lib/twodim_base.py index e794d4144..46294fbd9 100644 --- a/numpy/lib/twodim_base.py +++ b/numpy/lib/twodim_base.py @@ -632,15 +632,27 @@ def mask_indices(n,mask_func,k=0): def tril_indices(n,k=0): - """Return the indices for the lower-triangle of an (n,n) array. + """ + Return the indices for the lower-triangle of an (n, n) array. Parameters ---------- n : int Sets the size of the arrays for which the returned indices will be valid. - k : int, optional - Diagonal offset (see tril() for details). + Diagonal offset (see `tril` for details). + + Returns + ------- + inds : tuple of arrays + The indices for the triangle. The returned tuple contains two arrays, + each with the indices along one dimension of the array. + + See also + -------- + triu_indices : similar function, for upper-triangular. + mask_indices : generic function accepting an arbitrary mask function. + tril, triu Notes ----- @@ -648,45 +660,45 @@ def tril_indices(n,k=0): Examples -------- - Commpute two different sets of indices to access 4x4 arrays, one for the + Compute two different sets of indices to access 4x4 arrays, one for the lower triangular part starting at the main diagonal, and one starting two diagonals further right: - - >>> il1 = tril_indices(4) - >>> il2 = tril_indices(4,2) + + >>> il1 = np.tril_indices(4) + >>> il2 = np.tril_indices(4, 2) Here is how they can be used with a sample array: - >>> a = np.array([[1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,16]]) + + >>> a = np.arange(16).reshape(4, 4) >>> a - array([[ 1, 2, 3, 4], - [ 5, 6, 7, 8], - [ 9, 10, 11, 12], - [13, 14, 15, 16]]) + array([[ 0, 1, 2, 3], + [ 4, 5, 6, 7], + [ 8, 9, 10, 11], + [12, 13, 14, 15]]) Both for indexing: + >>> a[il1] - array([ 1, 5, 6, 9, 10, 11, 13, 14, 15, 16]) + array([ 0, 4, 5, 8, 9, 10, 12, 13, 14, 15]) And for assigning values: + >>> a[il1] = -1 >>> a - array([[-1, 2, 3, 4], - [-1, -1, 7, 8], - [-1, -1, -1, 12], + array([[-1, 1, 2, 3], + [-1, -1, 6, 7], + [-1, -1, -1, 11], [-1, -1, -1, -1]]) These cover almost the whole array (two diagonals right of the main one): - >>> a[il2] = -10 + + >>> a[il2] = -10 >>> a - array([[-10, -10, -10, 4], + array([[-10, -10, -10, 3], [-10, -10, -10, -10], [-10, -10, -10, -10], [-10, -10, -10, -10]]) - See also - -------- - - triu_indices : similar function, for upper-triangular. - - mask_indices : generic function accepting an arbitrary mask function. """ return mask_indices(n,tril,k) @@ -715,15 +727,27 @@ def tril_indices_from(arr,k=0): def triu_indices(n,k=0): - """Return the indices for the upper-triangle of an (n,n) array. + """ + Return the indices for the upper-triangle of an (n, n) array. Parameters ---------- n : int Sets the size of the arrays for which the returned indices will be valid. - k : int, optional - Diagonal offset (see triu() for details). + Diagonal offset (see `triu` for details). + + Returns + ------- + inds : tuple of arrays + The indices for the triangle. The returned tuple contains two arrays, + each with the indices along one dimension of the array. + + See also + -------- + tril_indices : similar function, for lower-triangular. + mask_indices : generic function accepting an arbitrary mask function. + triu, tril Notes ----- @@ -731,45 +755,46 @@ def triu_indices(n,k=0): Examples -------- - Commpute two different sets of indices to access 4x4 arrays, one for the - lower triangular part starting at the main diagonal, and one starting two + Compute two different sets of indices to access 4x4 arrays, one for the + upper triangular part starting at the main diagonal, and one starting two diagonals further right: - >>> iu1 = triu_indices(4) - >>> iu2 = triu_indices(4,2) + >>> iu1 = np.triu_indices(4) + >>> iu2 = np.triu_indices(4, 2) Here is how they can be used with a sample array: - >>> a = np.array([[1,2,3,4],[5,6,7,8],[9,10,11,12],[13,14,15,16]]) + + >>> a = np.arange(16).reshape(4, 4) >>> a - array([[ 1, 2, 3, 4], - [ 5, 6, 7, 8], - [ 9, 10, 11, 12], - [13, 14, 15, 16]]) + array([[ 0, 1, 2, 3], + [ 4, 5, 6, 7], + [ 8, 9, 10, 11], + [12, 13, 14, 15]]) Both for indexing: - >>> a[il1] - array([ 1, 5, 6, 9, 10, 11, 13, 14, 15, 16]) - And for assigning values: - >>> a[iu] = -1 + >>> a[iu1] + array([ 0, 1, 2, 3, 5, 6, 7, 10, 11, 15]) + + And for assigning values: + + >>> a[iu1] = -1 >>> a array([[-1, -1, -1, -1], - [ 5, -1, -1, -1], - [ 9, 10, -1, -1], - [13, 14, 15, -1]]) + [ 4, -1, -1, -1], + [ 8, 9, -1, -1], + [12, 13, 14, -1]]) + + These cover only a small part of the whole array (two diagonals right + of the main one): - These cover almost the whole array (two diagonals right of the main one): >>> a[iu2] = -10 >>> a array([[ -1, -1, -10, -10], - [ 5, -1, -1, -10], - [ 9, 10, -1, -1], - [ 13, 14, 15, -1]]) + [ 4, -1, -1, -10], + [ 8, 9, -1, -1], + [ 12, 13, 14, -1]]) - See also - -------- - - tril_indices : similar function, for lower-triangular. - - mask_indices : generic function accepting an arbitrary mask function. """ return mask_indices(n,triu,k) diff --git a/numpy/lib/type_check.py b/numpy/lib/type_check.py index 5dfe6330b..babad2d62 100644 --- a/numpy/lib/type_check.py +++ b/numpy/lib/type_check.py @@ -472,8 +472,37 @@ def typename(char): See Also -------- - typecodes - dtype + dtype, typecodes + + Examples + -------- + >>> typechars = ['S1', '?', 'B', 'D', 'G', 'F', 'I', 'H', 'L', 'O', 'Q', + ... 'S', 'U', 'V', 'b', 'd', 'g', 'f', 'i', 'h', 'l', 'q'] + >>> for typechar in typechars: + ... print typechar, ' : ', np.typename(typechar) + ... + S1 : character + ? : bool + B : unsigned char + D : complex double precision + G : complex long double precision + F : complex single precision + I : unsigned integer + H : unsigned short + L : unsigned long integer + O : object + Q : unsigned long long integer + S : string + U : unicode + V : void + b : signed char + d : double precision + g : long precision + f : single precision + i : integer + h : short + l : long integer + q : long long integer """ return _namefromtype[char] diff --git a/numpy/linalg/linalg.py b/numpy/linalg/linalg.py index 437db6d2b..f762cf72d 100644 --- a/numpy/linalg/linalg.py +++ b/numpy/linalg/linalg.py @@ -361,30 +361,36 @@ def cholesky(a): """ Cholesky decomposition. - Return the Cholesky decomposition, :math:`A = L L^*` of a Hermitian - positive-definite matrix :math:`A`. + Return the Cholesky decomposition, `L * L.H`, of the square matrix `a`, + where `L` is lower-triangular and .H is the conjugate transpose operator + (which is the ordinary transpose if `a` is real-valued). `a` must be + Hermitian (symmetric if real-valued) and positive-definite. Only `L` is + actually returned. Parameters ---------- a : array_like, shape (M, M) - Hermitian (symmetric, if it is real) and positive definite + Hermitian (symmetric if all elements are real), positive-definite input matrix. Returns ------- - L : array_like, shape (M, M) - Lower-triangular Cholesky factor of A. + L : ndarray, or matrix object if `a` is, shape (M, M) + Lower-triangular Cholesky factor of a. Raises ------ LinAlgError - If the decomposition fails. + If the decomposition fails, for example, if `a` is not + positive-definite. Notes ----- The Cholesky decomposition is often used as a fast way of solving - .. math:: A \\mathbf{x} = \\mathbf{b}. + .. math:: A \\mathbf{x} = \\mathbf{b} + + (when `A` is both Hermitian/symmetric and positive-definite). First, we solve for :math:`\\mathbf{y}` in @@ -392,18 +398,29 @@ def cholesky(a): and then for :math:`\\mathbf{x}` in - .. math:: L^* \\mathbf{x} = \\mathbf{y}. + .. math:: L.H \\mathbf{x} = \\mathbf{y}. Examples -------- >>> A = np.array([[1,-2j],[2j,5]]) + >>> A + array([[ 1.+0.j, 0.-2.j], + [ 0.+2.j, 5.+0.j]]) >>> L = np.linalg.cholesky(A) >>> L array([[ 1.+0.j, 0.+0.j], [ 0.+2.j, 1.+0.j]]) - >>> np.dot(L, L.T.conj()) + >>> np.dot(L, L.T.conj()) # verify that L * L.H = A array([[ 1.+0.j, 0.-2.j], [ 0.+2.j, 5.+0.j]]) + >>> A = [[1,-2j],[2j,5]] # what happens if A is only array_like? + >>> np.linalg.cholesky(A) # an ndarray object is returned + array([[ 1.+0.j, 0.+0.j], + [ 0.+2.j, 1.+0.j]]) + >>> # But a matrix object is returned if A is a matrix object + >>> LA.cholesky(np.matrix(A)) + matrix([[ 1.+0.j, 0.+0.j], + [ 0.+2.j, 1.+0.j]]) """ a, wrap = _makearray(a) diff --git a/numpy/ma/core.py b/numpy/ma/core.py index baf54b5b0..2045ee73b 100644 --- a/numpy/ma/core.py +++ b/numpy/ma/core.py @@ -154,7 +154,42 @@ if 'float128' in ntypes.typeDict: def default_fill_value(obj): """ - Calculate the default fill value for the argument object. + Return the default fill value for the argument object. + + The default filling value depends on the datatype of the input + array or the type of the input scalar: + + ======== ======== + datatype default + ======== ======== + bool True + int 999999 + float 1.e20 + complex 1.e20+0j + object '?' + string 'N/A' + ======== ======== + + + Parameters + ---------- + obj : ndarray, dtype or scalar + The array data-type or scalar for which the default fill value + is returned. + + Returns + ------- + fill_value : scalar + The default fill value. + + Examples + -------- + >>> np.ma.default_fill_value(1) + 999999 + >>> np.ma.default_fill_value(np.array([1.1, 2., np.pi])) + 1e+20 + >>> np.ma.default_fill_value(np.dtype(complex)) + (1e+20+0j) """ if hasattr(obj,'dtype'): @@ -2213,7 +2248,52 @@ class _arraymethod(object): #.......................................................... class MaskedIterator(object): - "Define an interator." + """ + Flat iterator object to iterate over masked arrays. + + A `MaskedIterator` iterator is returned by ``x.flat`` for any masked array + `x`. It allows iterating over the array as if it were a 1-D array, + either in a for-loop or by calling its `next` method. + + Iteration is done in C-contiguous style, with the last index varying the + fastest. The iterator can also be indexed using basic slicing or + advanced indexing. + + See Also + -------- + MaskedArray.flat : Return a flat iterator over an array. + MaskedArray.flatten : Returns a flattened copy of an array. + + Notes + ----- + `MaskedIterator` is not exported by the `ma` module. Instead of + instantiating a `MaskedIterator` directly, use `MaskedArray.flat`. + + Examples + -------- + >>> x = np.ma.array(arange(6).reshape(2, 3)) + >>> fl = x.flat + >>> type(fl) + <class 'numpy.ma.core.MaskedIterator'> + >>> for item in fl: + ... print item + ... + 0 + 1 + 2 + 3 + 4 + 5 + + Extracting more than a single element b indexing the `MaskedIterator` + returns a masked array: + + >>> fl[2:4] + masked_array(data = [2 3], + mask = False, + fill_value = 999999) + + """ def __init__(self, ma): self.ma = ma self.dataiter = ma._data.flat @@ -3952,12 +4032,51 @@ class MaskedArray(ndarray): def mean(self, axis=None, dtype=None, out=None): """ - Returns the average of the array elements along given axis. - Refer to `numpy.mean` for full documentation. + Returns the average of the array elements. + + Masked entries are ignored. + The average is taken over the flattened array by default, otherwise over + the specified axis. Refer to `numpy.mean` for the full documentation. + + Parameters + ---------- + a : array_like + Array containing numbers whose mean is desired. If `a` is not an + array, a conversion is attempted. + axis : int, optional + Axis along which the means are computed. The default is to compute + the mean of the flattened array. + dtype : dtype, optional + Type to use in computing the mean. For integer inputs, the default + is float64; for floating point, inputs it is the same as the input + dtype. + out : ndarray, optional + Alternative output array in which to place the result. It must have + the same shape as the expected output but the type will be cast if + necessary. + + Returns + ------- + mean : ndarray, see dtype parameter above + If `out=None`, returns a new array containing the mean values, + otherwise a reference to the output array is returned. + + See Also + -------- + numpy.ma.mean : Equivalent function. + numpy.mean : Equivalent function on non-masked arrays. + numpy.ma.average: Weighted average. + + Examples + -------- + >>> a = np.ma.array([1,2,3], mask=[False, False, True]) + >>> a + masked_array(data = [1 2 --], + mask = [False False True], + fill_value = 999999) + >>> a.mean() + 1.5 - See Also - -------- - numpy.mean : equivalent function' """ if self._mask is nomask: result = super(MaskedArray, self).mean(axis=axis, dtype=dtype) @@ -3977,18 +4096,35 @@ class MaskedArray(ndarray): def anom(self, axis=None, dtype=None): """ - Return the anomalies (deviations from the average) along the given axis. + Compute the anomalies (deviations from the arithmetic mean) + along the given axis. - Parameters - ---------- - axis : int, optional - Axis along which to perform the operation. - If None, applies to a flattened version of the array. - dtype : {dtype}, optional - Datatype for the intermediary computation. - If not given, the current dtype is used instead. + Returns an array of anomalies, with the same shape as the input and + where the arithmetic mean is computed along the given axis. - """ + Parameters + ---------- + axis : int, optional + Axis over which the anomalies are taken. + The default is to use the mean of the flattened array as reference. + dtype : dtype, optional + Type to use in computing the variance. For arrays of integer type + the default is float32; for arrays of float types it is the same as + the array type. + + See Also + -------- + mean : Compute the mean of the array. + + Examples + -------- + >>> a = np.ma.array([1,2,3]) + >>> a.anom() + masked_array(data = [-1. 0. 1.], + mask = False, + fill_value = 1e+20) + + """ m = self.mean(axis, dtype) if not axis: return (self - m) diff --git a/numpy/random/mtrand/mtrand.pyx b/numpy/random/mtrand/mtrand.pyx index d69c99703..3473c2a80 100644 --- a/numpy/random/mtrand/mtrand.pyx +++ b/numpy/random/mtrand/mtrand.pyx @@ -1889,7 +1889,93 @@ cdef class RandomState: """ power(a, size=None) - Power distribution. + Draws samples in [0, 1] from a power distribution with positive + exponent a - 1. + + Also known as the power function distribution. + + Parameters + ---------- + a : float + parameter, > 0 + size : tuple of ints + Output shape. If the given shape is, e.g., ``(m, n, k)``, then + ``m * n * k`` samples are drawn. + + Returns + ------- + samples : {ndarray, scalar} + The returned samples lie in [0, 1]. + + Raises + ------ + ValueError + If a<1. + + Notes + ----- + The probability density function is + + .. math:: P(x; a) = ax^{a-1}, 0 \\le x \\le 1, a>0. + + The power function distribution is just the inverse of the Pareto + distribution. It may also be seen as a special case of the Beta + distribution. + + It is used, for example, in modeling the over-reporting of insurance + claims. + + References + ---------- + .. [1] Christian Kleiber, Samuel Kotz, "Statistical size distributions + in economics and actuarial sciences", Wiley, 2003. + .. [2] Heckert, N. A. and Filliben, James J. (2003). NIST Handbook 148: + Dataplot Reference Manual, Volume 2: Let Subcommands and Library + Functions", National Institute of Standards and Technology Handbook + Series, June 2003. + http://www.itl.nist.gov/div898/software/dataplot/refman2/auxillar/powpdf.pdf + + Examples + -------- + Draw samples from the distribution: + + >>> a = 5. # shape + >>> samples = 1000 + >>> s = np.random.power(a, samples) + + Display the histogram of the samples, along with + the probability density function: + + >>> import matplotlib.pyplot as plt + >>> count, bins, ignored = plt.hist(s, bins=30) + >>> x = np.linspace(0, 1, 100) + >>> y = a*x**(a-1.) + >>> normed_y = samples*np.diff(bins)[0]*y + >>> plt.plot(x, normed_y) + >>> plt.show() + + Compare the power function distribution to the inverse of the Pareto. + + >>> from scipy import stats + >>> rvs = np.random.power(5, 1000000) + >>> rvsp = np.random.pareto(5, 1000000) + >>> xx = np.linspace(0,1,100) + >>> powpdf = stats.powerlaw.pdf(xx,5) + + >>> plt.figure() + >>> plt.hist(rvs, bins=50, normed=True) + >>> plt.plot(xx,powpdf,'r-') + >>> plt.title('np.random.power(5)') + + >>> plt.figure() + >>> plt.hist(1./(1.+rvsp), bins=50, normed=True) + >>> plt.plot(xx,powpdf,'r-') + >>> plt.title('inverse of 1 + np.random.pareto(5)') + + >>> plt.figure() + >>> plt.hist(1./(1.+rvsp), bins=50, normed=True) + >>> plt.plot(xx,powpdf,'r-') + >>> plt.title('inverse of stats.pareto(5)') """ cdef ndarray oa |