This is an auto-generated version of Numpy Example List with added documentation from doc strings and arguments specification for methods and functions of Numpy 1.2.1.

### ...

>>> from numpy import *
>>> a = arange(12)
>>> a = a.reshape(3,2,2)
>>> print a
[[[ 0  1]
[ 2  3]]
[[ 4  5]
[ 6  7]]
[[ 8  9]
[10 11]]]
>>> a[...,0]                               # same as a[:,:,0]
array([[ 0,  2],
[ 4,  6],
[ 8, 10]])
>>> a[1:,...]                              # same as a[1:,:,:] or just a[1:]
array([[[ 4,  5],
[ 6,  7]],
[[ 8,  9],
[10, 11]]])


### []

>>> from numpy import *
>>> a = array([ [ 0, 1, 2, 3, 4],
...             [10,11,12,13,14],
...             [20,21,22,23,24],
...             [30,31,32,33,34] ])
>>>
>>> a[0,0]                                       # indices start by zero
0
>>> a[-1]                                        # last row
array([30, 31, 32, 33, 34])
>>> a[1:3,1:4]                                   # subarray
array([[11, 12, 13],
[21, 22, 23]])
>>>
>>> i = array([0,1,2,1])                         # array of indices for the first axis
>>> j = array([1,2,3,4])                         # array of indices for the second axis
>>> a[i,j]
array([ 1, 12, 23, 14])
>>>
>>> a[a<13]                                      # boolean indexing
array([ 0,  1,  2,  3,  4, 10, 11, 12])
>>>
>>> b1 = array( [True,False,True,False] )        # boolean row selector
>>> a[b1,:]
array([[ 0,  1,  2,  3,  4],
[20, 21, 22, 23, 24]])
>>>
>>> b2 = array( [False,True,True,False,True] )   # boolean column selector
>>> a[:,b2]
array([[ 1,  2,  4],
[11, 12, 14],
[21, 22, 24],
[31, 32, 34]])


### T

ndarray.T

Same as self.transpose() except self is returned for self.ndim < 2.

Examples
--------
>>> x = np.array([[1.,2.],[3.,4.]])
>>> x.T
array([[ 1.,  3.],
[ 2.,  4.]])


>>> from numpy import *
>>> x = array([[1.,2.],[3.,4.]])
>>> x
array([[ 1.,  2.],
[ 3.,  4.]])
>>> x.T                                           # shortcut for transpose()
array([[ 1.,  3.],
[ 2.,  4.]])


### abs()

numpy.abs(...)

y = absolute(x)

Calculate the absolute value element-wise.

Parameters
----------
x : array_like
Input array.

Returns
-------
res : ndarray
An ndarray containing the absolute value of
each element in x.  For complex input, a + ib, the
absolute value is :math:\sqrt{ a^2 + b^2 }.

Examples
--------
>>> x = np.array([-1.2, 1.2])
>>> np.absolute(x)
array([ 1.2,  1.2])
>>> np.absolute(1.2 + 1j)
1.5620499351813308

Plot the function over [-10, 10]:

>>> import matplotlib.pyplot as plt

>>> x = np.linspace(-10, 10, 101)
>>> plt.plot(x, np.absolute(x))
>>> plt.show()

Plot the function over the complex plane:

>>> xx = x + 1j * x[:, np.newaxis]
>>> plt.imshow(np.abs(xx), extent=[-10, 10, -10, 10])
>>> plt.show()


>>> from numpy import *
>>> abs(-1)
1
>>> abs(array([-1.2, 1.2]))
array([ 1.2,  1.2])
>>> abs(1.2+1j)
1.5620499351813308


### absolute()

numpy.absolute(...)

y = absolute(x)

Calculate the absolute value element-wise.

Parameters
----------
x : array_like
Input array.

Returns
-------
res : ndarray
An ndarray containing the absolute value of
each element in x.  For complex input, a + ib, the
absolute value is :math:\sqrt{ a^2 + b^2 }.

Examples
--------
>>> x = np.array([-1.2, 1.2])
>>> np.absolute(x)
array([ 1.2,  1.2])
>>> np.absolute(1.2 + 1j)
1.5620499351813308

Plot the function over [-10, 10]:

>>> import matplotlib.pyplot as plt

>>> x = np.linspace(-10, 10, 101)
>>> plt.plot(x, np.absolute(x))
>>> plt.show()

Plot the function over the complex plane:

>>> xx = x + 1j * x[:, np.newaxis]
>>> plt.imshow(np.abs(xx), extent=[-10, 10, -10, 10])
>>> plt.show()


Synonym for abs()

See abs

### accumulate

>>> from numpy import *
>>> add.accumulate(array([1.,2.,3.,4.]))                   # like reduce() but also gives intermediate results
array([  1.,   3.,   6.,  10.])
>>> array([1., 1.+2., (1.+2.)+3., ((1.+2.)+3.)+4.])        # this is what it computed
array([  1.,   3.,   6.,  10.])
>>> multiply.accumulate(array([1.,2.,3.,4.]))              # works also with other operands
array([  1.,   2.,   6.,  24.])
>>> array([1., 1.*2., (1.*2.)*3., ((1.*2.)*3.)*4.])        # this is what it computed
array([  1.,   2.,   6.,  24.])
>>> add.accumulate(array([[1,2,3],[4,5,6]]), axis = 0)     # accumulate every column separately
array([[1, 2, 3],
[5, 7, 9]])
>>> add.accumulate(array([[1,2,3],[4,5,6]]), axis = 1)     # accumulate every row separately
array([[ 1,  3,  6],
[ 4,  9, 15]])


y = add(x1,x2)

Parameters
----------
x1, x2 : array_like

Returns
-------
y : {ndarray, scalar}
The sum of x1 and x2, element-wise.  Returns scalar if
both  x1 and x2 are scalars.

Notes
-----
Equivalent to x1 + x2 in terms of array broadcasting.

Examples
--------
5.0
>>> x1 = np.arange(9.0).reshape((3, 3))
>>> x2 = np.arange(3.0)
array([[  0.,   2.,   4.],
[  3.,   5.,   7.],
[  6.,   8.,  10.]])


>>> from numpy import *
array([-0.2,  4.2])
>>> array([-1.2, 1.2]) + array([1,3])
array([-0.2,  4.2])


### alen()

numpy.alen(a)

Return the length of the first dimension of the input array.

Parameters
----------
a : array_like
Input array.

Returns
-------
alen : int
Length of the first dimension of a.

--------
shape

Examples
--------
>>> a = np.zeros((7,4,5))
>>> a.shape[0]
7
>>> np.alen(a)
7


### all()

numpy.all(a, axis=None, out=None)

Returns True if all elements evaluate to True.

Parameters
----------
a : array_like
Input array.
axis : int, optional
Axis over which to perform the operation.
If None, use a flattened input array and return a bool.
out : ndarray, optional
Array into which the result is placed. Its type is preserved
and it must be of the right shape to hold the output.

Returns
-------
out : ndarray, bool
A logical AND is performed along axis, and the result placed
in out.  If out was not specified, a new output array is created.

--------
ndarray.all : equivalent method

Notes
-----
Since NaN is not equal to zero, NaN evaluates to True.

Examples
--------
>>> np.all([[True,False],[True,True]])
False

>>> np.all([[True,False],[True,True]], axis=0)
array([ True, False], dtype=bool)

>>> np.all([-1, 4, 5])
True

>>> np.all([1.0, np.nan])
True


ndarray.all(...)

a.all(axis=None, out=None)

Returns True if all elements evaluate to True.

Refer to numpy.all for full documentation.

--------
numpy.all : equivalent function


>>> from numpy import *
>>> a = array([True, False, True])
>>> a.all()                              # if all elements of a are True: return True; otherwise False
False
>>> all(a)                              # this form also exists
False
>>> a = array([1,2,3])
>>> all(a > 0)                         # equivalent to (a > 0).all()
True


### allclose()

numpy.allclose(a, b, rtol=1.0000000000000001e-005, atol=1e-008)

Returns True if two arrays are element-wise equal within a tolerance.

The tolerance values are positive, typically very small numbers.  The
relative difference (rtol * b) and the absolute difference (atol)
are added together to compare against the absolute difference between a
and b.

Parameters
----------
a, b : array_like
Input arrays to compare.
rtol : Relative tolerance
The relative difference is equal to rtol * b.
atol : Absolute tolerance
The absolute difference is equal to atol.

Returns
-------
y : bool
Returns True if the two arrays are equal within the given
tolerance; False otherwise. If either array contains NaN, then
False is returned.

--------
all, any, alltrue, sometrue

Notes
-----
If the following equation is element-wise True, then allclose returns
True.

absolute(a - b) <= (atol + rtol * absolute(b))

Examples
--------
>>> np.allclose([1e10,1e-7], [1.00001e10,1e-8])
False
>>> np.allclose([1e10,1e-8], [1.00001e10,1e-9])
True
>>> np.allclose([1e10,1e-8], [1.0001e10,1e-9])
False
>>> np.allclose([1.0, np.nan], [1.0, np.nan])
False


>>> allclose(array([1e10,1e-7]), array([1.00001e10,1e-8]))
False
>>> allclose(array([1e10,1e-8]), array([1.00001e10,1e-9]))
True
>>> allclose(array([1e10,1e-8]), array([1.0001e10,1e-9]))
False


### alltrue()

numpy.alltrue(a, axis=None, out=None)

Check if all elements of input array are true.

--------
numpy.all : Equivalent function; see for details.


>>> from numpy import *
>>> b = array([True, False, True, True])
>>> alltrue(b)
False
>>> a = array([1, 5, 2, 7])
>>> alltrue(a >= 5)
False


### alterdot()

numpy.alterdot(...)

alterdot() changes all dot functions to use blas.


### amax()

numpy.amax(a, axis=None, out=None)

Return the maximum along an axis.

Parameters
----------
a : array_like
Input data.
axis : int, optional
Axis along which to operate.  By default flattened input is used.
out : ndarray, optional
Alternative output array in which to place the result.  Must
be of the same shape and buffer length as the expected output.

Returns
-------
amax : ndarray
A new array or a scalar with the result, or a reference to out
if it was specified.

Examples
--------
>>> a = np.arange(4).reshape((2,2))
>>> a
array([[0, 1],
[2, 3]])
>>> np.amax(a, axis=0)
array([2, 3])
>>> np.amax(a, axis=1)
array([1, 3])


### amin()

numpy.amin(a, axis=None, out=None)

Return the minimum along an axis.

Parameters
----------
a : array_like
Input data.
axis : int, optional
Axis along which to operate.  By default a flattened input is used.
out : ndarray, optional
Alternative output array in which to place the result.  Must
be of the same shape and buffer length as the expected output.

Returns
-------
amin : ndarray
A new array or a scalar with the result, or a reference to out if it
was specified.

Examples
--------
>>> a = np.arange(4).reshape((2,2))
>>> a
array([[0, 1],
[2, 3]])
>>> np.amin(a)           # Minimum of the flattened array
0
>>> np.amin(a, axis=0)         # Minima along the first axis
array([0, 1])
>>> np.amin(a, axis=1)         # Minima along the second axis
array([0, 2])


### angle()

numpy.angle(z, deg=0)

Return the angle of the complex argument.

Parameters
----------
z : array_like
A complex number or sequence of complex numbers.
deg : bool, optional
Return angle in degrees if True, radians if False (default).

Returns
-------
angle : {ndarray, scalar}
The counterclockwise angle from the positive real axis on
the complex plane, with dtype as numpy.float64.

--------
arctan2

Examples
--------
>>> np.angle([1.0, 1.0j, 1+1j])               # in radians
array([ 0.        ,  1.57079633,  0.78539816])
>>> np.angle(1+1j, deg=True)                  # in degrees
45.0


>>> from numpy import *
0.78539816339744828
>>> angle(1+1j,deg=True)                          # in degrees
45.0


### any()

numpy.any(a, axis=None, out=None)

Test whether any elements of an array evaluate to True along an axis.

Parameters
----------
a : array_like
Input array.
axis : int, optional
Axis over which to perform the operation.
If None, use a flattened input array and return a bool.
out : ndarray, optional
Array into which the result is placed. Its type is preserved
and it must be of the right shape to hold the output.

Returns
-------
out : ndarray
A logical OR is performed along axis, and the result placed
in out.  If out was not specified, a new output array is created.

--------
ndarray.any : equivalent method

Notes
-----
Since NaN is not equal to zero, NaN evaluates to True.

Examples
--------
>>> np.any([[True, False], [True, True]])
True

>>> np.any([[True, False], [False, False]], axis=0)
array([ True, False], dtype=bool)

>>> np.any([-1, 0, 5])
True

>>> np.any(np.nan)
True


ndarray.any(...)

a.any(axis=None, out=None)

Check if any of the elements of a are true.

Refer to numpy.any for full documentation.

--------
numpy.any : equivalent function


>>> from numpy import *
>>> a = array([True, False, True])
>>> a.any()                                 # gives True if at least 1 element of a is True, otherwise False
True
>>> any(a)                                  # this form also exists
True
>>> a = array([1,2,3])
>>> (a >= 1).any()                          # equivalent to any(a >= 1)
True


### append()

numpy.append(arr, values, axis=None)

Append values to the end of an array.

Parameters
----------
arr : array_like
Values are appended to a copy of this array.
values : array_like
These values are appended to a copy of arr.  It must be of the
correct shape (the same shape as arr, excluding axis).  If axis
is not specified, values can be any shape and will be flattened
before use.
axis : int, optional
The axis along which values are appended.  If axis is not given,
both arr and values are flattened before use.

Returns
-------
out : ndarray
A copy of arr with values appended to axis.  Note that append
does not occur in-place: a new array is allocated and filled.

Examples
--------
>>> np.append([1, 2, 3], [[4, 5, 6], [7, 8, 9]])
array([1, 2, 3, 4, 5, 6, 7, 8, 9])

>>> np.append([[1, 2, 3], [4, 5, 6]], [[7, 8, 9]], axis=0)
array([[1, 2, 3],
[4, 5, 6],
[7, 8, 9]])


>>> from numpy import *
>>> a = array([10,20,30,40])
>>> append(a,50)
array([10, 20, 30, 40, 50])
>>> append(a,[50,60])
array([10, 20, 30, 40, 50, 60])
>>> a = array([[10,20,30],[40,50,60],[70,80,90]])
>>> append(a,[[15,15,15]],axis=0)
array([[10, 20, 30],
[40, 50, 60],
[70, 80, 90],
[15, 15, 15]])
>>> append(a,[[15],[15],[15]],axis=1)
array([[10, 20, 30, 15],
[40, 50, 60, 15],
[70, 80, 90, 15]])


### apply_along_axis()

numpy.apply_along_axis(func1d, axis, arr, *args)

Apply function to 1-D slices along the given axis.

Execute func1d(a[i],*args) where func1d takes 1-D arrays, a is
the input array, and i is an integer that varies in order to apply the
function along the given axis for each 1-D subarray in a.

Parameters
----------
func1d : function
This function should be able to take 1-D arrays. It is applied to 1-D
slices of a along the specified axis.
axis : integer
Axis along which func1d is applied.
a : ndarray
Input array.
args : any
Additional arguments to func1d.

Returns
-------
out : ndarray
The output array. The shape of out is identical to the shape of a,
except along the axis dimension, whose length is equal to the size
of the return value of func1d.

--------
apply_over_axes : Apply a function repeatedly over multiple axes.

Examples
--------
>>> def my_func(a):
...     """Average first and last element of a 1-D array"""
...     return (a[0] + a[-1]) * 0.5
>>> b = np.array([[1,2,3], [4,5,6], [7,8,9]])
>>> np.apply_along_axis(my_func, 0, b)
array([4., 5., 6.])
>>> np.apply_along_axis(my_func, 1, b)
array([2., 5., 8.])


>>> from numpy import *
>>> def myfunc(a):                                # function works on a 1d arrays, takes the average of the 1st an last element
...   return (a[0]+a[-1])/2
...
>>> b = array([[1,2,3],[4,5,6],[7,8,9]])
>>> apply_along_axis(myfunc,0,b)                 # apply myfunc to each column (axis=0) of b
array([4, 5, 6])
>>> apply_along_axis(myfunc,1,b)                # apply myfunc to each row (axis=1) of b
array([2, 5, 8])


### apply_over_axes()

numpy.apply_over_axes(func, a, axes)

Apply a function repeatedly over multiple axes.

func is called as res = func(a, axis), where axis is the first
element of axes.  The result res of the function call must have
either the same dimensions as a or one less dimension. If res has one
less dimension than a, a dimension is inserted before axis.
The call to func is then repeated for each axis in  axes,
with res as the first argument.

Parameters
----------
func : function
This function must take two arguments, func(a, axis).
a : ndarray
Input array.
axes : array_like
Axes over which func is applied, the elements must be
integers.

Returns
-------
val : ndarray
The output array. The number of dimensions is the same as a, but
the shape can be different. This depends on whether func changes
the shape of its output with respect to its input.

--------
apply_along_axis :
Apply a function to 1-D slices of an array along the given axis.

Examples
--------
>>> a = np.arange(24).reshape(2,3,4)
>>> a
array([[[ 0,  1,  2,  3],
[ 4,  5,  6,  7],
[ 8,  9, 10, 11]],
<BLANKLINE>
[[12, 13, 14, 15],
[16, 17, 18, 19],
[20, 21, 22, 23]]])

Sum over axes 0 and 2. The result has same number of dimensions
as the original array:

>>> np.apply_over_axes(np.sum, a, [0,2])
array([[[ 60],
[ 92],
[124]]])


>>> from numpy import *
>>> a = arange(24).reshape(2,3,4)         # a has 3 axes: 0,1 and 2
>>> a
array([[[ 0,  1,  2,  3],
[ 4,  5,  6,  7],
[ 8,  9, 10, 11]],
[[12, 13, 14, 15],
[16, 17, 18, 19],
[20, 21, 22, 23]]])
>>> apply_over_axes(sum, a, [0,2])        # sum over all axes except axis=1, result has same shape as original
array([[[ 60],
[ 92],
[124]]])


### arange()

numpy.arange(...)

arange([start,] stop[, step,], dtype=None)

Return evenly spaced values within a given interval.

Values are generated within the half-open interval [start, stop)
(in other words, the interval including start but excluding stop).
For integer arguments the function is equivalent to the Python built-in
range <http://docs.python.org/lib/built-in-funcs.html>_ function,
but returns a ndarray rather than a list.

Parameters
----------
start : number, optional
Start of interval.  The interval includes this value.  The default
start value is 0.
stop : number
End of interval.  The interval does not include this value.
step : number, optional
Spacing between values.  For any output out, this is the distance
between two adjacent values, out[i+1] - out[i].  The default
step size is 1.  If step is specified, start must also be given.
dtype : dtype
The type of the output array.  If dtype is not given, infer the data
type from the other input arguments.

Returns
-------
out : ndarray
Array of evenly spaced values.

For floating point arguments, the length of the result is
ceil((stop - start)/step).  Because of floating point overflow,
this rule may result in the last element of out being greater
than stop.

--------
linspace : Evenly spaced numbers with careful handling of endpoints.
ogrid: Arrays of evenly spaced numbers in N-dimensions
mgrid: Grid-shaped arrays of evenly spaced numbers in N-dimensions

Examples
--------
>>> np.arange(3)
array([0, 1, 2])
>>> np.arange(3.0)
array([ 0.,  1.,  2.])
>>> np.arange(3,7)
array([3, 4, 5, 6])
>>> np.arange(3,7,2)
array([3, 5])


>>> from numpy import *
>>> arange(3)
array([0, 1, 2])
>>> arange(3.0)
array([ 0.,  1.,  2.])
>>> arange(3, dtype=float)
array([ 0.,  1.,  2.])
>>> arange(3,10)                                 # start,stop
array([3, 4, 5, 6, 7, 8, 9])
>>> arange(3,10,2)                              # start,stop,step
array([3, 5, 7, 9])


### arccos()

numpy.arccos(...)

y = arccos(x)

Trigonometric inverse cosine, element-wise.

The inverse of cos so that, if y = cos(x), then x = arccos(y).

Parameters
----------
x : array_like
x-coordinate on the unit circle.
For real arguments, the domain is [-1, 1].

Returns
-------
angle : ndarray
The angle of the ray intersecting the unit circle at the given
x-coordinate in radians [0, pi]. If x is a scalar then a
scalar is returned, otherwise an array of the same shape as x
is returned.

--------
cos, arctan, arcsin

Notes
-----
arccos is a multivalued function: for each x there are infinitely
many numbers z such that cos(z) = x. The convention is to return the
angle z whose real part lies in [0, pi].

For real-valued input data types, arccos always returns real output.
For each value that cannot be expressed as a real number or infinity, it
yields nan and sets the invalid floating point error flag.

For complex-valued input, arccos is a complex analytical function that
has branch cuts [-inf, -1] and [1, inf] and is continuous from above
on the former and from below on the latter.

The inverse cos is also known as acos or cos^-1.

References
----------
.. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions",
10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/
.. [2] Wikipedia, "Inverse trigonometric function",
http://en.wikipedia.org/wiki/Arccos

Examples
--------
We expect the arccos of 1 to be 0, and of -1 to be pi:

>>> np.arccos([1, -1])
array([ 0.        ,  3.14159265])

Plot arccos:

>>> import matplotlib.pyplot as plt
>>> x = np.linspace(-1, 1, num=100)
>>> plt.plot(x, np.arccos(x))
>>> plt.axis('tight')
>>> plt.show()


>>> from numpy import *
>>> arccos(array([0, 1]))
array([ 1.57079633,  0.        ])


### arccosh()

numpy.arccosh(...)

y = arccosh(x)

Inverse hyperbolic cosine, elementwise.

Parameters
----------
x : array_like
Input array.

Returns
-------
out : ndarray
Array of the same shape and dtype as x.

Notes
-----
arccosh is a multivalued function: for each x there are infinitely
many numbers z such that cosh(z) = x. The convention is to return the
z whose imaginary part lies in [-pi, pi] and the real part in
[0, inf].

For real-valued input data types, arccosh always returns real output.
For each value that cannot be expressed as a real number or infinity, it
yields nan and sets the invalid floating point error flag.

For complex-valued input, arccosh is a complex analytical function that
has a branch cut [-inf, 1] and is continuous from above on it.

References
----------
.. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions",
10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/
.. [2] Wikipedia, "Inverse hyperbolic function",
http://en.wikipedia.org/wiki/Arccosh

Examples
--------
>>> np.arccosh([np.e, 10.0])
array([ 1.65745445,  2.99322285])


>>> from numpy import *
>>> arccosh(array([e, 10.0]))
array([ 1.65745445,  2.99322285])


### arcsin()

numpy.arcsin(...)

y = arcsin(x)

Inverse sine elementwise.

Parameters
----------
x : array_like
y-coordinate on the unit circle.

Returns
-------
angle : ndarray
The angle of the ray intersecting the unit circle at the given
y-coordinate in radians [-pi, pi]. If x is a scalar then
a scalar is returned, otherwise an array is returned.

--------
sin, arctan, arctan2

Notes
-----
arcsin is a multivalued function: for each x there are infinitely
many numbers z such that sin(z) = x. The convention is to return the
angle z whose real part lies in [-pi/2, pi/2].

For real-valued input data types, arcsin always returns real output.
For each value that cannot be expressed as a real number or infinity, it
yields nan and sets the invalid floating point error flag.

For complex-valued input, arcsin is a complex analytical function that
has branch cuts [-inf, -1] and [1, inf] and is continuous from above
on the former and from below on the latter.

The inverse sine is also known as asin or sin^-1.

References
----------
.. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions",
10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/
.. [2] Wikipedia, "Inverse trigonometric function",
http://en.wikipedia.org/wiki/Arcsin

Examples
--------
>>> np.arcsin(1)     # pi/2
1.5707963267948966
>>> np.arcsin(-1)    # -pi/2
-1.5707963267948966
>>> np.arcsin(0)
0.0


>>> from numpy import *
>>> arcsin(array([0, 1]))
array([ 0.        ,  1.57079633])


### arcsinh()

numpy.arcsinh(...)

y = arcsinh(x)

Inverse hyperbolic sine elementwise.

Parameters
----------
x : array_like
Input array.

Returns
-------
out : ndarray
Array of of the same shape as x.

Notes
-----
arcsinh is a multivalued function: for each x there are infinitely
many numbers z such that sinh(z) = x. The convention is to return the
z whose imaginary part lies in [-pi/2, pi/2].

For real-valued input data types, arcsinh always returns real output.
For each value that cannot be expressed as a real number or infinity, it
returns nan and sets the invalid floating point error flag.

For complex-valued input, arccos is a complex analytical function that
has branch cuts [1j, infj] and [-1j, -infj] and is continuous from
the right on the former and from the left on the latter.

The inverse hyperbolic sine is also known as asinh or sinh^-1.

References
----------
.. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions",
10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/
.. [2] Wikipedia, "Inverse hyperbolic function",
http://en.wikipedia.org/wiki/Arcsinh

Examples
--------
>>> np.arcsinh(np.array([np.e, 10.0]))
array([ 1.72538256,  2.99822295])


>>> from numpy import *
>>> arcsinh(array([e, 10.0]))
array([ 1.72538256,  2.99822295])


### arctan()

numpy.arctan(...)

y = arctan(x)

Trigonometric inverse tangent, element-wise.

The inverse of tan, so that if y = tan(x) then
x = arctan(y).

Parameters
----------
x : array_like
Input values.  arctan is applied to each element of x.

Returns
-------
out : ndarray
Out has the same shape as x.  Its real part is
in [-pi/2, pi/2]. It is a scalar if x is a scalar.

--------
arctan2 : Calculate the arctan of y/x.

Notes
-----
arctan is a multivalued function: for each x there are infinitely
many numbers z such that tan(z) = x. The convention is to return the
angle z whose real part lies in [-pi/2, pi/2].

For real-valued input data types, arctan always returns real output.
For each value that cannot be expressed as a real number or infinity, it
yields nan and sets the invalid floating point error flag.

For complex-valued input, arctan is a complex analytical function that
has branch cuts [1j, infj] and [-1j, -infj] and is continuous from the
left on the former and from the right on the latter.

The inverse tangent is also known as atan or tan^-1.

References
----------
.. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions",
10th printing, 1964, pp. 79. http://www.math.sfu.ca/~cbm/aands/
.. [2] Wikipedia, "Inverse trigonometric function",
http://en.wikipedia.org/wiki/Arctan

Examples
--------
We expect the arctan of 0 to be 0, and of 1 to be :math:\pi/4:

>>> np.arctan([0, 1])
array([ 0.        ,  0.78539816])

>>> np.pi/4
0.78539816339744828

Plot arctan:

>>> import matplotlib.pyplot as plt
>>> x = np.linspace(-10, 10)
>>> plt.plot(x, np.arctan(x))
>>> plt.axis('tight')
>>> plt.show()


>>> from numpy import *
>>> arctan(array([0, 1]))
array([ 0.        ,  0.78539816])


### arctan2()

numpy.arctan2(...)

y = arctan2(x1,x2)

Elementwise arc tangent of x1/x2 choosing the quadrant correctly.

The quadrant (ie. branch) is chosen so that arctan2(x1, x2)
is the signed angle in radians between the line segments
(0,0) - (1,0) and (0,0) - (x2,x1). This function is defined
also for x2 = 0.

arctan2 is not defined for complex-valued arguments.

Parameters
----------
x1 : array_like, real-valued
y-coordinates.
x2 : array_like, real-valued
x-coordinates. x2 must be broadcastable to match the shape of x1,
or vice versa.

Returns
-------
angle : ndarray
Array of angles in radians, in the range [-pi, pi].

--------
arctan, tan

Notes
-----
arctan2 is identical to the atan2 function of the underlying
C library. The following special values are defined in the C standard [2]:

====== ====== ================
x1   x2   arctan2(x1,x2)
====== ====== ================
+/- 0  +0     +/- 0
+/- 0  -0     +/- pi
> 0   +/-inf +0 / +pi
< 0   +/-inf -0 / -pi
+/-inf +inf   +/- (pi/4)
+/-inf -inf   +/- (3*pi/4)
====== ====== ================

Note that +0 and -0 are distinct floating point numbers.

References
----------
.. [1] Wikipedia, "atan2",
http://en.wikipedia.org/wiki/Atan2
.. [2] ISO/IEC standard 9899:1999, "Programming language C", 1999.

Examples
--------
Consider four points in different quadrants:

>>> x = np.array([-1, +1, +1, -1])
>>> y = np.array([-1, -1, +1, +1])
>>> np.arctan2(y, x) * 180 / np.pi
array([-135.,  -45.,   45.,  135.])

Note the order of the parameters. arctan2 is defined also when x2 = 0
and at several other special points, obtaining values in
the range [-pi, pi]:

>>> np.arctan2([1., -1.], [0., 0.])
array([ 1.57079633, -1.57079633])
>>> np.arctan2([0., 0., np.inf], [+0., -0., np.inf])
array([ 0.        ,  3.14159265,  0.78539816])


>>> from numpy import *
>>> arctan2(array([0, 1]), array([1, 0]))
array([ 0.        ,  1.57079633])


### arctanh()

numpy.arctanh(...)

y = arctanh(x)

Inverse hyperbolic tangent elementwise.

Parameters
----------
x : array_like
Input array.

Returns
-------
out : ndarray
Array of the same shape as x.

Notes
-----
arctanh is a multivalued function: for each x there are infinitely
many numbers z such that tanh(z) = x. The convention is to return the
z whose imaginary part lies in [-pi/2, pi/2].

For real-valued input data types, arctanh always returns real output.
For each value that cannot be expressed as a real number or infinity, it
yields nan and sets the invalid floating point error flag.

For complex-valued input, arctanh is a complex analytical function that
has branch cuts [-1, -inf] and [1, inf] and is continuous from
above on the former and from below on the latter.

The inverse hyperbolic tangent is also known as atanh or tanh^-1.

References
----------
.. [1] M. Abramowitz and I.A. Stegun, "Handbook of Mathematical Functions",
10th printing, 1964, pp. 86. http://www.math.sfu.ca/~cbm/aands/
.. [2] Wikipedia, "Inverse hyperbolic function",
http://en.wikipedia.org/wiki/Arctanh

Examples
--------
>>> np.arctanh([0, -0.5])
array([ 0.        , -0.54930614])


>>> from numpy import *
>>> arctanh(array([0, -0.5]))
array([ 0.        , -0.54930614])


### argmax()

numpy.argmax(a, axis=None)

Indices of the maximum values along an axis.

Parameters
----------
a : array_like
Input array.
axis : int, optional
By default, the index is into the flattened array, otherwise
along the specified axis.

Returns
-------
index_array : ndarray, int
Array of indices into the array.  It has the same shape as a,
except with axis removed.

--------
argmin : Indices of the minimum values along an axis.
amax : The maximum value along a given axis.
unravel_index : Convert a flat index into an index tuple.

Examples
--------
>>> a = np.arange(6).reshape(2,3)
>>> np.argmax(a)
5
>>> np.argmax(a, axis=0)
array([1, 1, 1])
>>> np.argmax(a, axis=1)
array([2, 2])


ndarray.argmax(...)

a.argmax(axis=None, out=None)

Return indices of the maximum values along the given axis of a.

Parameters
----------
axis : int, optional
Axis along which to operate.  By default flattened input is used.
out : ndarray, optional
Alternative output array in which to place the result.  Must
be of the same shape and buffer length as the expected output.

Returns
-------
index_array : ndarray
An array of indices or single index value, or a reference to out
if it was specified.

Examples
--------
>>> a = np.arange(6).reshape(2,3)
>>> a.argmax()
5
>>> a.argmax(0)
array([1, 1, 1])
>>> a.argmax(1)
array([2, 2])


>>> from numpy import *
>>> a = array([10,20,30])
>>> maxindex = a.argmax()
>>> a[maxindex]
30
>>> a = array([[10,50,30],[60,20,40]])
>>> maxindex = a.argmax()
>>> maxindex
3
>>> a.ravel()[maxindex]
60
>>> a.argmax(axis=0)                        # for each column: the row index of the maximum value
array([1, 0, 1])
>>> a.argmax(axis=1)                       # for each row: the column index of the maximum value
array([1, 0])
>>> argmax(a)                              # also exists, slower, default is axis=-1
array([1, 0])


### argmin()

numpy.argmin(a, axis=None)

Return the indices of the minimum values along an axis.

--------
argmax : Similar function.  Please refer to numpy.argmax for detailed
documentation.


ndarray.argmin(...)

a.argmin(axis=None, out=None)

Return indices of the minimum values along the given axis of a.

Refer to numpy.ndarray.argmax for detailed documentation.


>>> from numpy import *
>>> a = array([10,20,30])
>>> minindex = a.argmin()
>>> a[minindex]
10
>>> a = array([[10,50,30],[60,20,40]])
>>> minindex = a.argmin()
>>> minindex
0
>>> a.ravel()[minindex]
10
>>> a.argmin(axis=0)                           # for each column: the row index of the minimum value
array([0, 1, 0])
>>> a.argmin(axis=1)                           # for each row: the column index of the minimum value
array([0, 1])
>>> argmin(a)                                  #  also exists, slower, default is axis=-1
array([0, 1])


### argsort()

numpy.argsort(a, axis=-1, kind='quicksort', order=None)

Returns the indices that would sort an array.

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
----------
a : array_like
Array to sort.
axis : int, optional
Axis along which to sort.  If not given, the flattened array is used.
kind : {'quicksort', 'mergesort', 'heapsort'}, optional
Sorting algorithm.
order : list, optional
When a is an array with fields defined, this argument specifies
which fields to compare first, second, etc.  Not all fields need be
specified.

Returns
-------
index_array : ndarray, int
Array of indices that sort a along the specified axis.
In other words, a[index_array] yields a sorted a.

--------
sort : Describes sorting algorithms used.
lexsort : Indirect stable sort with multiple keys.
ndarray.sort : Inplace sort.

Notes
-----
See sort for notes on the different sorting algorithms.

Examples
--------
One dimensional array:

>>> x = np.array([3, 1, 2])
>>> np.argsort(x)
array([1, 2, 0])

Two-dimensional array:

>>> x = np.array([[0, 3], [2, 2]])
>>> x
array([[0, 3],
[2, 2]])

>>> np.argsort(x, axis=0)
array([[0, 1],
[1, 0]])

>>> np.argsort(x, axis=1)
array([[0, 1],
[0, 1]])

Sorting with keys:

>>> x = np.array([(1, 0), (0, 1)], dtype=[('x', '<i4'), ('y', '<i4')])
>>> x
array([(1, 0), (0, 1)],
dtype=[('x', '<i4'), ('y', '<i4')])

>>> np.argsort(x, order=('x','y'))
array([1, 0])

>>> np.argsort(x, order=('y','x'))
array([0, 1])


ndarray.argsort(...)

a.argsort(axis=-1, kind='quicksort', order=None)

Returns the indices that would sort this array.

Refer to numpy.argsort for full documentation.

--------
numpy.argsort : equivalent function


argsort(axis=-1, kind="quicksort")

>>> from numpy import *
>>> a = array([2,0,8,4,1])
>>> ind = a.argsort()               # indices of sorted array using quicksort (default)
>>> ind
array([1, 4, 0, 3, 2])
>>> a[ind]                          # same effect as a.sort()
array([0, 1, 2, 4, 8])
>>> ind = a.argsort(kind='merge')   # algorithm options are 'quicksort', 'mergesort' and 'heapsort'
>>> a = array([[8,4,1],[2,0,9]])
>>> ind = a.argsort(axis=0)         # sorts on columns. NOT the same as a.sort(axis=1)
>>> ind
array([[1, 1, 0],
[0, 0, 1]])
>>> a[ind,[[0,1,2],[0,1,2]]]        # 2-D arrays need fancy indexing if you want to sort them.
array([[2, 0, 1],
[8, 4, 9]])
>>> ind = a.argsort(axis=1)         # sort along rows. Can use a.argsort(axis=-1) for last axis.
>>> ind
array([[2, 1, 0],
[1, 0, 2]])
>>> a = ones(17)
>>> a.argsort()                     # quicksort doesn't preserve original order.
array([ 0, 14, 13, 12, 11, 10,  9, 15,  8,  6,  5,  4,  3,  2,  1,  7, 16])
>>> a.argsort(kind="mergesort")     # mergesort preserves order when possible. It is a stable sort.
array([ 0,  1,  2,  3,  4,  5,  6,  7,  8,  9, 10, 11, 12, 13, 14, 15, 16])
>>> ind = argsort(a)                # there is a functional form


### argwhere()

numpy.argwhere(a)

Find the indices of array elements that are non-zero, grouped by element.

Parameters
----------
a : array_like
Input data.

Returns
-------
index_array : ndarray
Indices of elements that are non-zero. Indices are grouped by element.

--------
where, nonzero

Notes
-----
np.argwhere(a) is the same as np.transpose(np.nonzero(a)).

The output of argwhere is not suitable for indexing arrays.
For this purpose use where(a) instead.

Examples
--------
>>> x = np.arange(6).reshape(2,3)
>>> x
array([[0, 1, 2],
[3, 4, 5]])
>>> np.argwhere(x>1)
array([[0, 2],
[1, 0],
[1, 1],
[1, 2]])


### around()

numpy.around(a, decimals=0, out=None)

Evenly round to the given number of decimals.

Parameters
----------
a : array_like
Input data.
decimals : int, optional
Number of decimal places to round to (default: 0).  If
decimals is negative, it specifies the number of positions to
the left of the decimal point.
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 of the output
values will be cast if necessary.

Returns
-------
rounded_array : ndarray
An array of the same type as a, containing the rounded values.
Unless out was specified, a new array is created.  A reference to
the result is returned.

The real and imaginary parts of complex numbers are rounded
separately.  The result of rounding a float is a float.

--------
ndarray.round : equivalent method

Notes
-----
For values exactly halfway between rounded decimal values, Numpy
rounds to the nearest even value. 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 the IEEE
floating point standard [1]_ and errors introduced when scaling
by powers of ten.

References
----------
.. [1] "Lecture Notes on the Status of  IEEE 754", William Kahan,
http://www.cs.berkeley.edu/~wkahan/ieee754status/IEEE754.PDF
.. [2] "How Futile are Mindless Assessments of
Roundoff in Floating-Point Computation?", William Kahan,
http://www.cs.berkeley.edu/~wkahan/Mindless.pdf

Examples
--------
>>> np.around([.5, 1.5, 2.5, 3.5, 4.5])
array([ 0.,  2.,  2.,  4.,  4.])
>>> np.around([1,2,3,11], decimals=1)
array([ 1,  2,  3, 11])
>>> np.around([1,2,3,11], decimals=-1)
array([ 0,  0,  0, 10])


### array()

numpy.array(...)

array(object, dtype=None, copy=True, order=None, subok=True, ndmin=True)

Create an array.

Parameters
----------
object : array_like
An array, any object exposing the array interface, an
object whose __array__ method returns an array, or any
(nested) sequence.
dtype : data-type, optional
The desired data-type for the array.  If not given, then
the type will be determined as the minimum type required
to hold the objects in the sequence.  This argument can only
be used to 'upcast' the array.  For downcasting, use the
.astype(t) method.
copy : bool, optional
If true (default), then the object is copied.  Otherwise, a copy
will only be made if __array__ returns a copy, if obj is a
nested sequence, or if a copy is needed to satisfy any of the other
requirements (dtype, order, etc.).
order : {'C', 'F', 'A'}, optional
Specify the order of the array.  If order is 'C' (default), then the
array will be in C-contiguous order (last-index varies the
fastest).  If order is 'F', then the returned array
will be in Fortran-contiguous order (first-index varies the
fastest).  If order is 'A', then the returned array may
be in any order (either C-, Fortran-contiguous, or even
discontiguous).
subok : bool, optional
If True, then sub-classes will be passed-through, otherwise
the returned array will be forced to be a base-class array.
ndmin : int, optional
Specifies the minimum number of dimensions that the resulting
array should have.  Ones will be pre-pended to the shape as
needed to meet this requirement.

Examples
--------
>>> np.array([1, 2, 3])
array([1, 2, 3])

Upcasting:

>>> np.array([1, 2, 3.0])
array([ 1.,  2.,  3.])

More than one dimension:

>>> np.array([[1, 2], [3, 4]])
array([[1, 2],
[3, 4]])

Minimum dimensions 2:

>>> np.array([1, 2, 3], ndmin=2)
array([[1, 2, 3]])

Type provided:

>>> np.array([1, 2, 3], dtype=complex)
array([ 1.+0.j,  2.+0.j,  3.+0.j])

Data-type consisting of more than one element:

>>> x = np.array([(1,2),(3,4)],dtype=[('a','<i4'),('b','<i4')])
>>> x['a']
array([1, 3])

Creating an array from sub-classes:

>>> np.array(np.mat('1 2; 3 4'))
array([[1, 2],
[3, 4]])

>>> np.array(np.mat('1 2; 3 4'), subok=True)
matrix([[1, 2],
[3, 4]])


numpy.core.records.array(obj, dtype=None, shape=None, offset=0, strides=None, formats=None, names=None, titles=None, aligned=False, byteorder=None, copy=True)

Construct a record array from a wide-variety of objects.


>>> from numpy import *
>>> array([1,2,3])                                                                         # conversion from a list to an array
array([1, 2, 3])
>>> array([1,2,3], dtype=complex)                                                          # output type is specified
array([ 1.+0.j,  2.+0.j,  3.+0.j])
>>> array(1, copy=0, subok=1, ndmin=1)                                                     # basically equivalent to atleast_1d
array([1])
>>> array(1, copy=0, subok=1, ndmin=2)                                                     # basically equivalent to atleast_2d
array([[1]])
>>> array(1, subok=1, ndmin=2)                                                             # like atleast_2d but always makes a copy
array([[1]])
>>> mydescriptor = {'names': ('gender','age','weight'), 'formats': ('S1', 'f4', 'f4')}     # one way of specifying the data type
>>> a = array([('M',64.0,75.0),('F',25.0,60.0)], dtype=mydescriptor)                       # recarray
>>> print a
[('M', 64.0, 75.0) ('F', 25.0, 60.0)]
>>> a['weight']
array([ 75.,  60.], dtype=float32)
('gender','age','weight')
>>> mydescriptor = [('age',int16),('Nchildren',int8),('weight',float32)]                   # another way of specifying the data type
>>> a = array([(64,2,75.0),(25,0,60.0)], dtype=mydescriptor)
>>> a['Nchildren']
array([2, 0], dtype=int8)
>>> mydescriptor = dtype([('x', 'f4'),('y', 'f4'),                                         # nested recarray
...     ('nested', [('i', 'i2'),('j','i2')])])
>>> array([(1.0, 2.0, (1,2))], dtype=mydescriptor)                                         # input one row
array([(1.0, 2.0, (1, 2))],
dtype=[('x', '<f4'), ('y', '<f4'), ('nested', [('i', '<i2'), ('j', '<i2')])])
>>> array([(1.0, 2.0, (1,2)), (2.1, 3.2, (3,2))], dtype=mydescriptor)                      # input two rows
array([(1.0, 2.0, (1, 2)), (2.0999999046325684, 3.2000000476837158, (3, 2))],
dtype=[('x', '<f4'), ('y', '<f4'), ('nested', [('i', '<i2'), ('j', '<i2')])])
>>> a=array([(1.0, 2.0, (1,2)), (2.1, 3.2, (3,2))], dtype=mydescriptor)                    # getting some columns
>>> a['x']                                                                                 # a plain column
array([ 1.       ,  2.0999999], dtype=float32)
>>> a['nested']                                                                            # a nested column
array([(1, 2), (3, 2)],
dtype=[('i', '<i2'), ('j', '<i2')])
>>> a['nested']['i']                                                                       # a plain column inside a nested column
>>> mydescriptor = dtype([('x', 'f4'),('y', 'f4'),                                         # nested recarray
...     ('nested', [('i', 'i2'),('j','i2')])])
>>> array([(1.0, 2.0, (1,2))], dtype=mydescriptor)                                         # input one row
array([(1.0, 2.0, (1, 2))],
dtype=[('x', '<f4'), ('y', '<f4'), ('nested', [('i', '<i2'), ('j', '<i2')])])
>>> array([(1.0, 2.0, (1,2)), (2.1, 3.2, (3,2))], dtype=mydescriptor)                      # input two rows
array([(1.0, 2.0, (1, 2)), (2.0999999046325684, 3.2000000476837158, (3, 2))],
dtype=[('x', '<f4'), ('y', '<f4'), ('nested', [('i', '<i2'), ('j', '<i2')])])
>>> a=array([(1.0, 2.0, (1,2)), (2.1, 3.2, (3,2))], dtype=mydescriptor)                    # getting some columns
>>> a['x']                                                                                 # a plain column
array([ 1.       ,  2.0999999], dtype=float32)
>>> a['nested']                                                                            # a nested column
array([(1, 2), (3, 2)],
dtype=[('i', '<i2'), ('j', '<i2')])
>>> a['nested']['i']                                                                       # a plain column inside a nested column
array([1, 3], dtype=int16)


### array2string()

numpy.array2string(a, max_line_width=None, precision=None, suppress_small=None, separator=' ', prefix="", style=<built-in function repr>)

Return a string representation of an array.

Parameters
----------
a : ndarray
Input array.
max_line_width : int, optional
The maximum number of columns the string should span. Newline
characters splits the string appropriately after array elements.
precision : int, optional
Floating point precision. Default is the current printing
precision (usually 8), which can be altered using set_printoptions.
suppress_small : bool, optional
Represent very small numbers as zero.
separator : string, optional
Inserted between elements.
prefix : string, optional
An array is typically printed as::

'prefix(' + array2string(a) + ')'

The length of the prefix string is used to align the
output correctly.
style : function, optional
Callable.

--------
array_str, array_repr, set_printoptions

Examples
--------
>>> x = np.array([1e-16,1,2,3])
>>> print np.array2string(x, precision=2, separator=',',
...                       suppress_small=True)
[ 0., 1., 2., 3.]


### array_equal()

numpy.array_equal(a1, a2)

True if two arrays have the same shape and elements, False otherwise.

Parameters
----------
a1 : array_like
First input array.
a2 : array_like
Second input array.

Returns
-------
b : {True, False}
Returns True if the arrays are equal.

Examples
--------
>>> np.array_equal([1,2],[1,2])
True
>>> np.array_equal(np.array([1,2]),np.array([1,2]))
True
>>> np.array_equal([1,2],[1,2,3])
False
>>> np.array_equal([1,2],[1,4])
False


### array_equiv()

numpy.array_equiv(a1, a2)

Returns True if input arrays are shape consistent and all elements equal.

Parameters
----------
a1 : array_like
Input array.
a2 : array_like
Input array.

Returns
-------
out : bool
True if equivalent, False otherwise.

Examples
--------
>>> np.array_equiv([1,2],[1,2])
>>> True
>>> np.array_equiv([1,2],[1,3])
>>> False
>>> np.array_equiv([1,2], [[1,2],[1,2]])
>>> True
>>> np.array_equiv([1,2], [[1,2],[1,3]])
>>> False


### array_repr()

numpy.array_repr(arr, max_line_width=None, precision=None, suppress_small=None)

Return the string representation of an array.

Parameters
----------
arr : ndarray
Input array.
max_line_width : int
The maximum number of columns the string should span. Newline
characters splits the string appropriately after array elements.
precision : int
Floating point precision.
suppress_small : bool
Represent very small numbers as zero.

Returns
-------
string : str
The string representation of an array.

Examples
--------
>>> np.array_repr(np.array([1,2]))
'array([1, 2])'
>>> np.array_repr(np.ma.array([0.]))
>>> np.array_repr(np.array([], np.int32))
'array([], dtype=int32)'


### array_split()

numpy.array_split(ary, indices_or_sections, axis=0)

Split an array into multiple sub-arrays of equal or near-equal size.

Please refer to the numpy.split documentation.  The only difference
between these functions is that array_split allows indices_or_sections
to be an integer that does *not* equally divide the axis.

--------
numpy.split : Split array into multiple sub-arrays.

Examples
--------
>>> x = np.arange(8.0)
>>> np.array_split(x, 3)
[array([ 0.,  1.,  2.]), array([ 3.,  4.,  5.]), array([ 6.,  7.])]


>>> from numpy import *
>>> a = array([[1,2,3,4],[5,6,7,8]])
>>> array_split(a,2,axis=0)                            # split a in 2 parts. row-wise
[array([[1, 2, 3, 4]]), array([[5, 6, 7, 8]])]
>>> array_split(a,4,axis=1)                            # split a in 4 parts, column-wise
[array([[1],
[5]]), array([[2],
[6]]), array([[3],
[7]]), array([[4],
[8]])]
>>> array_split(a,3,axis=1)                          # impossible to split in 3 equal parts -> first part(s) are bigger
[array([[1, 2],
[5, 6]]), array([[3],
[7]]), array([[4],
[8]])]
>>> array_split(a,[2,3],axis=1)                      # make a split before the 2nd and the 3rd column
[array([[1, 2],
[5, 6]]), array([[3],
[7]]), array([[4],
[8]])]


### array_str()

numpy.array_str(a, max_line_width=None, precision=None, suppress_small=None)

Return a string representation of an array.

Parameters
----------
a : ndarray
Input array.
max_line_width : int, optional
Inserts newlines if text is longer than max_line_width.
precision : int, optional
If a is float, precision sets loating point precision.
suppress_small : boolean, optional
Represent very small numbers as zero.

--------
array2string, array_repr

Examples
--------
>>> np.array_str(np.arange(3))
>>> '[0 1 2]'


### arrayrange

Synonym for arange()

See arange

### asanyarray()

numpy.asanyarray(a, dtype=None, order=None)

Convert the input to a ndarray, but pass ndarray subclasses through.

Parameters
----------
a : array_like
Input data, in any form that can be converted to an array.  This
includes scalars, lists, lists of tuples, tuples, tuples of tuples,
tuples of lists and ndarrays.
dtype : data-type, optional
By default, the data-type is inferred from the input data.
order : {'C', 'F'}, optional
Whether to use row-major ('C') or column-major ('F') memory
representation.  Defaults to 'C'.

Returns
-------
out : ndarray or an ndarray subclass
Array interpretation of a.  If a is an ndarray or a subclass
of ndarray, it is returned as-is and no copy is performed.

--------
asarray : Similar function which always returns ndarrays.
ascontiguousarray : Convert input to a contiguous array.
asfarray : Convert input to a floating point ndarray.
asfortranarray : Convert input to an ndarray with column-major
memory order.
asarray_chkfinite : Similar function which checks input for NaNs and Infs.
fromiter : Create an array from an iterator.
fromfunction : Construct an array by executing a function on grid
positions.

Examples
--------
Convert a list into an array:

>>> a = [1, 2]
>>> np.asanyarray(a)
array([1, 2])

Instances of ndarray subclasses are passed through as-is:

>>> a = np.matrix([1, 2])
>>> np.asanyarray(a) is a
True


>>> from numpy import *
>>> a = array([[1,2],[5,8]])
>>> a
array([[1, 2],
[5, 8]])
>>> m = matrix('1 2; 5 8')
>>> m
matrix([[1, 2],
[5, 8]])
>>> asanyarray(a)         # the array a is returned unmodified
array([[1, 2],
[5, 8]])
>>> asanyarray(m)         # the matrix m is returned unmodified
matrix([[1, 2],
[5, 8]])
>>> asanyarray([1,2,3])   # a new array is constructed from the list
array([1, 2, 3])


### asarray()

numpy.asarray(a, dtype=None, order=None)

Convert the input to an array.

Parameters
----------
a : array_like
Input data, in any form that can be converted to an array.  This
includes lists, lists of tuples, tuples, tuples of tuples, tuples
of lists and ndarrays.
dtype : data-type, optional
By default, the data-type is inferred from the input data.
order : {'C', 'F'}, optional
Whether to use row-major ('C') or column-major ('FORTRAN') memory
representation.  Defaults to 'C'.

Returns
-------
out : ndarray
Array interpretation of a.  No copy is performed if the input
is already an ndarray.  If a is a subclass of ndarray, a base
class ndarray is returned.

--------
asanyarray : Similar function which passes through subclasses.
ascontiguousarray : Convert input to a contiguous array.
asfarray : Convert input to a floating point ndarray.
asfortranarray : Convert input to an ndarray with column-major
memory order.
asarray_chkfinite : Similar function which checks input for NaNs and Infs.
fromiter : Create an array from an iterator.
fromfunction : Construct an array by executing a function on grid
positions.

Examples
--------
Convert a list into an array:

>>> a = [1, 2]
>>> np.asarray(a)
array([1, 2])

Existing arrays are not copied:

>>> a = np.array([1, 2])
>>> np.asarray(a) is a
True


>>> from numpy import *
>>> m = matrix('1 2; 5 8')
>>> m
matrix([[1, 2],
[5, 8]])
>>> a = asarray(m)           # a is array type with same contents as m -- data is not copied
>>> a
array([[1, 2],
[5, 8]])
>>> m[0,0] = -99
>>> m
matrix([[-99,   2],
[  5,   8]])
>>> a                        # no copy was made, so modifying m modifies a, and vice versa
array([[-99,   2],
[  5,   8]])


### asarray_chkfinite()

numpy.asarray_chkfinite(a)

Convert the input to an array, checking for NaNs or Infs.

Parameters
----------
a : array_like
Input data, in any form that can be converted to an array.  This
includes lists, lists of tuples, tuples, tuples of tuples, tuples
of lists and ndarrays.  Success requires no NaNs or Infs.
dtype : data-type, optional
By default, the data-type is inferred from the input data.
order : {'C', 'F'}, optional
Whether to use row-major ('C') or column-major ('FORTRAN') memory
representation.  Defaults to 'C'.

Returns
-------
out : ndarray
Array interpretation of a.  No copy is performed if the input
is already an ndarray.  If a is a subclass of ndarray, a base
class ndarray is returned.

Raises
------
ValueError
Raises ValueError if a contains NaN (Not a Number) or Inf (Infinity).

--------
asarray : Create and array.
asanyarray : Similar function which passes through subclasses.
ascontiguousarray : Convert input to a contiguous array.
asfarray : Convert input to a floating point ndarray.
asfortranarray : Convert input to an ndarray with column-major
memory order.
fromiter : Create an array from an iterator.
fromfunction : Construct an array by executing a function on grid
positions.

Examples
--------
Convert a list into an array.  If all elements are finite
asarray_chkfinite is identical to asarray.

>>> a = [1, 2]
>>> np.asarray_chkfinite(a)
array([1, 2])

Raises ValueError if array_like contains Nans or Infs.

>>> a = [1, 2, np.inf]
>>> try:
...     np.asarray_chkfinite(a)
... except ValueError:
...     print 'ValueError'
...
ValueError


### ascontiguousarray()

numpy.ascontiguousarray(a, dtype=None)

Return a contiguous array in memory (C order).

Parameters
----------
a : array_like
Input array.
dtype : string
Type code of returned array.

Returns
-------
out : ndarray
Contiguous array of same shape and content as a with type dtype.


### asfarray()

numpy.asfarray(a, dtype=<type 'numpy.float64'>)

Return an array converted to float type.

Parameters
----------
a : array_like
Input array.
dtype : string or dtype object, optional
Float type code to coerce input array a.  If one of the 'int' dtype,
it is replaced with float64.

Returns
-------
out : ndarray, float
Input a as a float ndarray.

Examples
--------
>>> np.asfarray([2, 3])
array([ 2.,  3.])
>>> np.asfarray([2, 3], dtype='float')
array([ 2.,  3.])
>>> np.asfarray([2, 3], dtype='int8')
array([ 2.,  3.])


### asfortranarray()

numpy.asfortranarray(a, dtype=None)

Return an array laid out in Fortran-order in memory.

Parameters
----------
a : array_like
Input array.
dtype : data-type, optional
By default, the data-type is inferred from the input data.

Returns
-------
out : ndarray
Array interpretation of a in Fortran (column-order).

--------
asarray : Similar function which always returns ndarrays.
ascontiguousarray : Convert input to a contiguous array.
asfarray : Convert input to a floating point ndarray.
asanyarray : Convert input to an ndarray with either row or
column-major memory order.
asarray_chkfinite : Similar function which checks input for NaNs and Infs.
fromiter : Create an array from an iterator.
fromfunction : Construct an array by executing a function on grid
positions.


### asmatrix()

numpy.asmatrix(data, dtype=None)

Interpret the input as a matrix.

Unlike matrix, asmatrix does not make a copy if the input is already
a matrix or an ndarray.  Equivalent to matrix(data, copy=False).

Parameters
----------
data : array_like
Input data.

Returns
-------
mat : matrix
data interpreted as a matrix.

Examples
--------
>>> x = np.array([[1, 2], [3, 4]])

>>> m = np.asmatrix(x)

>>> x[0,0] = 5

>>> m
matrix([[5, 2],
[3, 4]])


>>> from numpy import *
>>> a = array([[1,2],[5,8]])
>>> a
array([[1, 2],
[5, 8]])
>>> m = asmatrix(a)        # m is matrix type with same contents as a -- data is not copied
>>> m
matrix([[1, 2],
[5, 8]])
>>> a[0,0] = -99
>>> a
array([[-99,   2],
[  5,   8]])
>>> m                      # no copy was made so modifying a modifies m, and vice versa
matrix([[-99,   2],
[  5,   8]])


### asscalar()

numpy.asscalar(a)

Convert an array of size 1 to its scalar equivalent.

Parameters
----------
a : ndarray
Input array.

Returns
-------
out : scalar
Scalar of size 1 array.

Examples
--------
>>> np.asscalar(np.array([24]))
>>> 24


### astype()

ndarray.astype(...)

a.astype(t)

Copy of the array, cast to a specified type.

Parameters
----------
t : string or dtype
Typecode or data-type to which the array is cast.

Examples
--------
>>> x = np.array([1, 2, 2.5])
>>> x
array([ 1. ,  2. ,  2.5])

>>> x.astype(int)
array([1, 2, 2])


>>> from numpy import *
>>> x = array([1,2,3])
>>> y = x.astype(float64)                  # convert from int32 to float64
>>> type(y[0])
<type 'numpy.float64'>
>>> x.astype(None)                         # None implies converting to the default (float64)
array([1., 2., 3.])


### atleast_1d()

numpy.atleast_1d(*arys)

Convert inputs to arrays with at least one dimension.

Scalar inputs are converted to 1-dimensional arrays, whilst
higher-dimensional inputs are preserved.

Parameters
----------
array1, array2, ... : array_like
One or more input arrays.

Returns
-------
ret : ndarray
An array, or sequence of arrays, each with a.ndim >= 1.
Copies are made only if necessary.

--------
atleast_2d, atleast_3d

Examples
--------
>>> np.atleast_1d(1.0)
array([ 1.])

>>> x = np.arange(9.0).reshape(3,3)
>>> np.atleast_1d(x)
array([[ 0.,  1.,  2.],
[ 3.,  4.,  5.],
[ 6.,  7.,  8.]])
>>> np.atleast_1d(x) is x
True

>>> np.atleast_1d(1, [3, 4])
[array([1]), array([3, 4])]


>>> from numpy import *
>>> a = 1                                       # 0-d array
>>> b = array([2,3])                            # 1-d array
>>> c = array([[4,5],[6,7]])                    # 2-d array
>>> d = arange(8).reshape(2,2,2)                # 3-d array
>>> d
array([[[0, 1],
[2, 3]],
[[4, 5],
[6, 7]]])
>>> atleast_1d(a,b,c,d)                        # all output arrays have dim >= 1
[array([1]), array([2, 3]), array([[4, 5],
[6, 7]]), array([[[0, 1],
[2, 3]],
[[4, 5],
[6, 7]]])]


### atleast_2d()

numpy.atleast_2d(*arys)

View inputs as arrays with at least two dimensions.

Parameters
----------
array1, array2, ... : array_like
One or more array-like sequences.  Non-array inputs are converted
to arrays.  Arrays that already have two or more dimensions are
preserved.

Returns
-------
res, res2, ... : ndarray
An array, or tuple of arrays, each with a.ndim >= 2.
Copies are avoided where possible, and views with two or more
dimensions are returned.

--------
atleast_1d, atleast_3d

Examples
--------
>>> numpy.atleast_2d(3.0)
array([[ 3.]])

>>> x = numpy.arange(3.0)
>>> numpy.atleast_2d(x)
array([[ 0.,  1.,  2.]])
>>> numpy.atleast_2d(x).base is x
True

>>> np.atleast_2d(1, [1, 2], [[1, 2]])
[array([[1]]), array([[1, 2]]), array([[1, 2]])]


>>> from numpy import *
>>> a = 1                                               # 0-d array
>>> b = array([2,3])                                    # 1-d array
>>> c = array([[4,5],[6,7]])                            # 2-d array
>>> d = arange(8).reshape(2,2,2)                        # 3-d array
>>> d
array([[[0, 1],
[2, 3]],
[[4, 5],
[6, 7]]])
>>> atleast_2d(a,b,c,d)                                # all output arrays have dim >= 2
[array([[1]]), array([[2, 3]]), array([[4, 5],
[6, 7]]), array([[[0, 1],
[2, 3]],
[[4, 5],
[6, 7]]])]


### atleast_3d()

numpy.atleast_3d(*arys)

View inputs as arrays with at least three dimensions.

Parameters
----------
array1, array2, ... : array_like
One or more array-like sequences.  Non-array inputs are converted
to arrays. Arrays that already have three or more dimensions are
preserved.

Returns
-------
res1, res2, ... : ndarray
An array, or tuple of arrays, each with a.ndim >= 3.
Copies are avoided where possible, and views with three or more
dimensions are returned.  For example, a one-dimensional array of
shape N becomes a view of shape (1, N, 1).  An (M, N)
array becomes a view of shape (N, M, 1).

--------
numpy.atleast_1d, numpy.atleast_2d

Examples
--------
>>> numpy.atleast_3d(3.0)
array([[[ 3.]]])

>>> x = numpy.arange(3.0)
>>> numpy.atleast_3d(x).shape
(1, 3, 1)

>>> x = numpy.arange(12.0).reshape(4,3)
>>> numpy.atleast_3d(x).shape
(4, 3, 1)
>>> numpy.atleast_3d(x).base is x
True

>>> for arr in np.atleast_3d(1, [1, 2], [[1, 2]]): print arr, "\n"
...
[[[1]]]

[[[1]
[2]]]

[[[1]
[2]]]


>>> from numpy import *
>>> a = 1                                       # 0-d array
>>> b = array([2,3])                            # 1-d array
>>> c = array([[4,5],[6,7]])                    # 2-d array
>>> d = arange(8).reshape(2,2,2)                # 3-d array
>>> d
array([[[0, 1],
[2, 3]],
[[4, 5],
[6, 7]]])
>>> atleast_3d(a,b,c,d)                       # all output arrays have dim >= 3
[array([[[1]]]), array([[[2],
[3]]]), array([[[4],
[5]],
[[6],
[7]]]), array([[[0, 1],
[2, 3]],
[[4, 5],
[6, 7]]])]


### average()

numpy.average(a, axis=None, weights=None, returned=False)

Return the weighted average of array over the specified axis.

Parameters
----------
a : array_like
Data to be averaged.
axis : int, optional
Axis along which to average a. If None, averaging is done over the
entire array irrespective of its shape.
weights : array_like, optional
The importance that each datum has in the computation of the average.
The weights array can either be 1-D (in which case its length must be
the size of a along the given axis) or of the same shape as a.
If weights=None, then all data in a are assumed to have a
weight equal to one.
returned : bool, optional
Default is False. If True, the tuple (average, sum_of_weights)
is returned, otherwise only the average is returned.  Note that
if weights=None, sum_of_weights is equivalent to the number of
elements over which the average is taken.

Returns
-------
average, [sum_of_weights] : {array_type, double}
Return the average along the specified axis. When returned is True,
return a tuple with the average as the first element and the sum
of the weights as the second element. The return type is Float
if a is of integer type, otherwise it is of the same type as a.
sum_of_weights is of the same type as average.

Raises
------
ZeroDivisionError
When all weights along axis are zero. See numpy.ma.average for a
version robust to this type of error.
TypeError
When the length of 1D weights is not the same as the shape of a
along axis.

--------
ma.average : average for masked arrays

Examples
--------
>>> data = range(1,5)
>>> data
[1, 2, 3, 4]
>>> np.average(data)
2.5
>>> np.average(range(1,11), weights=range(10,0,-1))
4.0


>>> from numpy import *
>>> a = array([1,2,3,4,5])
>>> w = array([0.1, 0.2, 0.5, 0.2, 0.2])             # weights, not necessarily normalized
>>> average(a)                                       # plain mean value
3.0
>>> average(a,weights=w)                            # weighted average
3.1666666666666665
>>> average(a,weights=w,returned=True)              # output = weighted average, sum of weights
(3.1666666666666665, 1.2)


### bartlett()

numpy.bartlett(M)

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.

--------
blackman, hamming, hanning, kaiser

Notes
-----
The Bartlett window is defined as

.. math:: w(n) = \frac{2}{M-1} \left(
\frac{M-1}{2} - \left|n - \frac{M-1}{2}\right|
\right)

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. The fourier transform of the Bartlett is the product
of two sinc functions.
Note the excellent discussion in Kanasewich.

References
----------
.. [1] M.S. Bartlett, "Periodogram Analysis and Continuous Spectra",
Biometrika 37, 1-16, 1950.
.. [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics",
The University of Alberta Press, 1975, pp. 109-110.
.. [3] A.V. Oppenheim and R.W. Schafer, "Discrete-Time Signal
Processing", Prentice-Hall, 1999, pp. 468-471.
.. [4] Wikipedia, "Window function",
http://en.wikipedia.org/wiki/Window_function
.. [5] W.H. Press,  B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling,
"Numerical Recipes", Cambridge University Press, 1986, page 429.

Examples
--------
>>> np.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 its frequency response (requires SciPy and matplotlib):

>>> from numpy import clip, log10, array, bartlett
>>> from numpy.fft import fft
>>> import matplotlib.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()


### base_repr()

Return a string representation of a number in the given base system.

Parameters
----------
number : scalar
The value to convert. Only positive values are handled.
base : int
Convert number to the base number system. The valid range is 2-36,
the default value is 2.
Number of zeros padded on the left.

Returns
-------
out : str
String representation of number in base system.

--------
binary_repr : Faster version of base_repr for base 2 that also handles
negative numbers.

Examples
--------
>>> np.base_repr(3, 5)
'3'
>>> np.base_repr(6, 5)
'11'
'00012'


### bench()

numpy.bench(self, label='fast', verbose=1, extra_argv=None)

Run benchmarks for module using nose

Parameters
----------
label : {'fast', 'full', '', attribute identifer}
Identifies the benchmarks to run.  This can be a string to
pass to the nosetests executable with the '-A' option, or one of
several special values.
Special values are:
'fast' - the default - which corresponds to nosetests -A option
of 'not slow'.
'full' - fast (as above) and slow benchmarks as in the
no -A option to nosetests - same as ''
None or '' - run all benchmarks
attribute_identifier - string passed directly to nosetests as '-A'
verbose : integer
verbosity value for test outputs, 1-10
extra_argv : list
List with any extra args to pass to nosetests


### beta()

numpy.random.beta(...)

beta(a, b, size=None)

The Beta distribution over [0, 1].

The Beta distribution is a special case of the Dirichlet distribution,
and is related to the Gamma distribution.  It has the probability
distribution function

.. math:: f(x; a,b) = \frac{1}{B(\alpha, \beta)} x^{\alpha - 1}
(1 - x)^{\beta - 1},

where the normalisation, B, is the beta function,

.. math:: B(\alpha, \beta) = \int_0^1 t^{\alpha - 1}
(1 - t)^{\beta - 1} dt.

It is often seen in Bayesian inference and order statistics.

Parameters
----------
a : float
Alpha, non-negative.
b : float
Beta, non-negative.
size : tuple of ints, optional
The number of samples to draw.  The ouput is packed according to
the size given.

Returns
-------
out : ndarray
Array of the given shape, containing values drawn from a
Beta distribution.


>>> from numpy import *
>>> from numpy.random import *
>>> beta(a=1,b=10,size=(2,2))                  # Beta distribution alpha=1, beta=10
array([[ 0.02571091,  0.04973536],
[ 0.04887027,  0.02382052]])


### binary_repr()

numpy.binary_repr(num, width=None)

Return the binary representation of the input number as a string.

For negative numbers, if width is not given, a minus sign is added to the
front. If width is given, the two's complement of the number is
returned, with respect to that width.

In a two's-complement system negative numbers are represented by the two's
complement of the absolute value. This is the most common method of
representing signed integers on computers [1]_. A N-bit two's-complement
system can represent every integer in the range
:math:-2^{N-1} to :math:+2^{N-1}-1.

Parameters
----------
num : int
Only an integer decimal number can be used.
width : int, optional
The length of the returned string if num is positive, the length of
the two's complement if num is negative.

Returns
-------
bin : str
Binary representation of num or two's complement of num.

--------
base_repr

Notes
-----
binary_repr is equivalent to using base_repr with base 2, but about 25x
faster.

References
----------
.. [1] Wikipedia, "Two's complement",
http://en.wikipedia.org/wiki/Two's_complement

Examples
--------
>>> np.binary_repr(3)
'11'
>>> np.binary_repr(-3)
'-11'
>>> np.binary_repr(3, width=4)
'0011'

The two's complement is returned when the input number is negative and
width is specified:

>>> np.binary_repr(-3, width=4)
'1101'


>>> from numpy import *
>>> a = 25
>>> binary_repr(a)                              # binary representation of 25
'11001'
>>> b = float_(pi)                              # numpy float has extra functionality ...
>>> b.nbytes                                    # ... like the number of bytes it takes
8
>>> binary_repr(b.view('u8'))                   # view float number as an 8 byte integer, then get binary bitstring
'1010100010001000010110100011000'


### bincount()

numpy.bincount(...)

bincount(x,weights=None)

Return the number of occurrences of each value in x.

x must be a list of non-negative integers.  The output, b[i],
represents the number of times that i is found in x.  If weights
is specified, every occurrence of i at a position p contributes



>>> from numpy import *
>>> a = array([1,1,1,1,2,2,4,4,5,6,6,6])              # doesn't need to be sorted
>>> bincount(a)                                       # 0 occurs 0 times, 1 occurs 4 times, 2 occurs twice, 3 occurs 0 times, ...
array([0, 4, 2, 0, 2, 1, 3])
>>> a = array([5,4,4,2,2])
>>> w = array([0.1, 0.2, 0.1, 0.3, 0.5])
>>> bincount(a)                                      # 0 & 1 don't occur, 2 occurs twice, 3 doesn't occur, 4 occurs twice, 5 once
array([0, 0, 2, 0, 2, 1])
>>> bincount(a, weights=w)
array([ 0. ,  0. ,  0.8,  0. ,  0.3,  0.1])
>>> # 0 occurs 0 times -> result[0] = 0
>>> # 1 occurs 0 times -> result[1] = 0
>>> # 2 occurs at indices 3 & 4 -> result[2] = w[3] + w[4]
>>> # 3 occurs 0 times -> result[3] = 0
>>> # 4 occurs at indices 1 & 2 -> result[4] = w[1] + w[2]
>>> # 5 occurs at index 0  -> result[5] = w[0]


### binomial()

numpy.random.binomial(...)

binomial(n, p, size=None)

Draw samples from a binomial distribution.

Samples are drawn from a Binomial distribution with specified
parameters, n trials and p probability of success where
n an integer > 0 and p is in the interval [0,1]. (n may be
input as a float, but it is truncated to an integer in use)

Parameters
----------
n : float (but truncated to an integer)
parameter, > 0.
p : float
parameter, >= 0 and <=1.
size : {tuple, int}
Output shape.  If the given shape is, e.g., (m, n, k), then
m * n * k samples are drawn.

Returns
-------
samples : {ndarray, scalar}
where the values are all integers in  [0, n].

--------
scipy.stats.distributions.binom : probability density function,
distribution or cumulative density function, etc.

Notes
-----
The probability density for the Binomial distribution is

.. math:: P(N) = \binom{n}{N}p^N(1-p)^{n-N},

where :math:n is the number of trials, :math:p is the probability
of success, and :math:N is the number of successes.

When estimating the standard error of a proportion in a population by
using a random sample, the normal distribution works well unless the
product p*n <=5, where p = population proportion estimate, and n =
number of samples, in which case the binomial distribution is used
instead. For example, a sample of 15 people shows 4 who are left
handed, and 11 who are right handed. Then p = 4/15 = 27%. 0.27*15 = 4,
so the binomial distribution should be used in this case.

References
----------
.. [1] Dalgaard, Peter, "Introductory Statistics with R",
Springer-Verlag, 2002.
.. [2] Glantz, Stanton A. "Primer of Biostatistics.", McGraw-Hill,
Fifth Edition, 2002.
.. [3] Lentner, Marvin, "Elementary Applied Statistics", Bogden
and Quigley, 1972.
.. [4] Weisstein, Eric W. "Binomial Distribution." From MathWorld--A
Wolfram Web Resource.
http://mathworld.wolfram.com/BinomialDistribution.html
.. [5] Wikipedia, "Binomial-distribution",
http://en.wikipedia.org/wiki/Binomial_distribution

Examples
--------
Draw samples from the distribution:

>>> n, p = 10, .5 # number of trials, probability of each trial
>>> s = np.random.binomial(n, p, 1000)
# result of flipping a coin 10 times, tested 1000 times.

A real world example. A company drills 9 wild-cat oil exploration
wells, each with an estimated probability of success of 0.1. All nine
wells fail. What is the probability of that happening?

Let's do 20,000 trials of the model, and count the number that
generate zero positive results.

>>> sum(np.random.binomial(9,0.1,20000)==0)/20000.


>>> from numpy import *
>>> from numpy.random import *
>>> binomial(n=100,p=0.5,size=(2,3))    # binomial distribution n trials, p= success probability
array([[38, 50, 53],
[56, 48, 54]])
>>> from pylab import *                         # histogram plot example
>>> hist(binomial(100,0.5,(1000)), 20)


### bitwise_and()

numpy.bitwise_and(...)

y = bitwise_and(x1,x2)

Compute bit-wise AND of two arrays, element-wise.

When calculating the bit-wise AND between two elements, x and y,
each element is first converted to its binary representation (which works
just like the decimal system, only now we're using 2 instead of 10):

.. math:: x = \sum_{i=0}^{W-1} a_i \cdot 2^i\\
y = \sum_{i=0}^{W-1} b_i \cdot 2^i,

where W is the bit-width of the type (i.e., 8 for a byte or uint8),
and each :math:a_i and :math:b_j is either 0 or 1.  For example, 13
is represented as 00001101, which translates to
:math:2^4 + 2^3 + 2.

The bit-wise operator is the result of

.. math:: z = \sum_{i=0}^{i=W-1} (a_i \wedge b_i) \cdot 2^i,

where :math:\wedge is the AND operator, which yields one whenever
both :math:a_i and :math:b_i are 1.

Parameters
----------
x1, x2 : array_like
Only integer types are handled (including booleans).

Returns
-------
out : array_like
Result.

--------
bitwise_or, bitwise_xor
logical_and
binary_repr :
Return the binary representation of the input number as a string.

Examples
--------
We've seen that 13 is represented by 00001101.  Similary, 17 is
represented by 00010001.  The bit-wise AND of 13 and 17 is
therefore 000000001, or 1:

>>> np.bitwise_and(13, 17)
1

>>> np.bitwise_and(14, 13)
12
>>> np.binary_repr(12)
'1100'
>>> np.bitwise_and([14,3], 13)
array([12,  1])

>>> np.bitwise_and([11,7], [4,25])
array([0, 1])
>>> np.bitwise_and(np.array([2,5,255]), np.array([3,14,16]))
array([ 2,  4, 16])
>>> np.bitwise_and([True, True], [False, True])
array([False,  True], dtype=bool)


>>> from numpy import *
>>> bitwise_and(array([2,5,255]), array([4,4,4]))
array([0, 4, 4])
>>> bitwise_and(array([2,5,255,2147483647L],dtype=int32), array([4,4,4,2147483647L],dtype=int32))
array([         0,          4,          4, 2147483647])


### bitwise_not()

numpy.bitwise_not(...)

y = invert(x)

Compute bit-wise inversion, or bit-wise NOT, element-wise.

When calculating the bit-wise NOT of an element x, each element is
first converted to its binary representation (which works
just like the decimal system, only now we're using 2 instead of 10):

.. math:: x = \sum_{i=0}^{W-1} a_i \cdot 2^i

where W is the bit-width of the type (i.e., 8 for a byte or uint8),
and each :math:a_i is either 0 or 1.  For example, 13 is represented
as 00001101, which translates to :math:2^4 + 2^3 + 2.

The bit-wise operator is the result of

.. math:: z = \sum_{i=0}^{i=W-1} (\lnot a_i) \cdot 2^i,

where :math:\lnot is the NOT operator, which yields 1 whenever
:math:a_i is 0 and yields 0 whenever :math:a_i is 1.

For signed integer inputs, the two's complement is returned.
In a two's-complement system negative numbers are represented by the two's
complement of the absolute value. This is the most common method of
representing signed integers on computers [1]_. A N-bit two's-complement
system can represent every integer in the range
:math:-2^{N-1} to :math:+2^{N-1}-1.

Parameters
----------
x1 : ndarray
Only integer types are handled (including booleans).

Returns
-------
out : ndarray
Result.

--------
bitwise_and, bitwise_or, bitwise_xor
logical_not
binary_repr :
Return the binary representation of the input number as a string.

Notes
-----
bitwise_not is an alias for invert:

>>> np.bitwise_not is np.invert
True

References
----------
.. [1] Wikipedia, "Two's complement",
http://en.wikipedia.org/wiki/Two's_complement

Examples
--------
We've seen that 13 is represented by 00001101.
The invert or bit-wise NOT of 13 is then:

>>> np.invert(np.array([13], dtype=uint8))
array([242], dtype=uint8)
>>> np.binary_repr(x, width=8)
'00001101'
>>> np.binary_repr(242, width=8)
'11110010'

The result depends on the bit-width:

>>> np.invert(np.array([13], dtype=uint16))
array([65522], dtype=uint16)
>>> np.binary_repr(x, width=16)
'0000000000001101'
>>> np.binary_repr(65522, width=16)
'1111111111110010'

When using signed integer types the result is the two's complement of
the result for the unsigned type:

>>> np.invert(np.array([13], dtype=int8))
array([-14], dtype=int8)
>>> np.binary_repr(-14, width=8)
'11110010'

Booleans are accepted as well:

>>> np.invert(array([True, False]))
array([False,  True], dtype=bool)


### bitwise_or()

numpy.bitwise_or(...)

y = bitwise_or(x1,x2)

Compute bit-wise OR of two arrays, element-wise.

When calculating the bit-wise OR between two elements, x and y,
each element is first converted to its binary representation (which works
just like the decimal system, only now we're using 2 instead of 10):

.. math:: x = \sum_{i=0}^{W-1} a_i \cdot 2^i\\
y = \sum_{i=0}^{W-1} b_i \cdot 2^i,

where W is the bit-width of the type (i.e., 8 for a byte or uint8),
and each :math:a_i and :math:b_j is either 0 or 1.  For example, 13
is represented as 00001101, which translates to
:math:2^4 + 2^3 + 2.

The bit-wise operator is the result of

.. math:: z = \sum_{i=0}^{i=W-1} (a_i \vee b_i) \cdot 2^i,

where :math:\vee is the OR operator, which yields one whenever
either :math:a_i or :math:b_i is 1.

Parameters
----------
x1, x2 : array_like
Only integer types are handled (including booleans).

Returns
-------
out : array_like
Result.

--------
bitwise_and, bitwise_xor
logical_or
binary_repr :
Return the binary representation of the input number as a string.

Examples
--------
We've seen that 13 is represented by 00001101.  Similary, 16 is
represented by 00010000.  The bit-wise OR of 13 and 16 is
therefore 000111011, or 29:

>>> np.bitwise_or(13, 16)
29
>>> np.binary_repr(29)
'11101'

>>> np.bitwise_or(32, 2)
34
>>> np.bitwise_or([33, 4], 1)
array([33,  5])
>>> np.bitwise_or([33, 4], [1, 2])
array([33,  6])

>>> np.bitwise_or(np.array([2, 5, 255]), np.array([4, 4, 4]))
array([  6,   5, 255])
>>> np.bitwise_or(np.array([2, 5, 255, 2147483647L], dtype=np.int32),
...               np.array([4, 4, 4, 2147483647L], dtype=np.int32))
array([         6,          5,        255, 2147483647])
>>> np.bitwise_or([True, True], [False, True])
array([ True,  True], dtype=bool)


>>> from numpy import *
>>> bitwise_or(array([2,5,255]), array([4,4,4]))
array([  6,   5, 255])
>>> bitwise_or(array([2,5,255,2147483647L],dtype=int32), array([4,4,4,2147483647L],dtype=int32))
array([         6,          5,        255, 2147483647])


### bitwise_xor()

numpy.bitwise_xor(...)

y = bitwise_xor(x1,x2)

Compute bit-wise XOR of two arrays, element-wise.

When calculating the bit-wise XOR between two elements, x and y,
each element is first converted to its binary representation (which works
just like the decimal system, only now we're using 2 instead of 10):

.. math:: x = \sum_{i=0}^{W-1} a_i \cdot 2^i\\
y = \sum_{i=0}^{W-1} b_i \cdot 2^i,

where W is the bit-width of the type (i.e., 8 for a byte or uint8),
and each :math:a_i and :math:b_j is either 0 or 1.  For example, 13
is represented as 00001101, which translates to
:math:2^4 + 2^3 + 2.

The bit-wise operator is the result of

.. math:: z = \sum_{i=0}^{i=W-1} (a_i \oplus b_i) \cdot 2^i,

where :math:\oplus is the XOR operator, which yields one whenever
either :math:a_i or :math:b_i is 1, but not both.

Parameters
----------
x1, x2 : array_like
Only integer types are handled (including booleans).

Returns
-------
out : ndarray
Result.

--------
bitwise_and, bitwise_or
logical_xor
binary_repr :
Return the binary representation of the input number as a string.

Examples
--------
We've seen that 13 is represented by 00001101.  Similary, 17 is
represented by 00010001.  The bit-wise XOR of 13 and 17 is
therefore 00011100, or 28:

>>> np.bitwise_xor(13, 17)
28
>>> np.binary_repr(28)
'11100'

>>> np.bitwise_xor(31, 5)
26
>>> np.bitwise_xor([31,3], 5)
array([26,  6])

>>> np.bitwise_xor([31,3], [5,6])
array([26,  5])
>>> np.bitwise_xor([True, True], [False, True])
array([ True, False], dtype=bool)


>>> from numpy import *
>>> bitwise_xor(array([2,5,255]), array([4,4,4]))
array([  6,   1, 251])
>>> bitwise_xor(array([2,5,255,2147483647L],dtype=int32), array([4,4,4,2147483647L],dtype=int32))
array([  6,   1, 251,   0])


### blackman()

numpy.blackman(M)

Return the Blackman window.

The Blackman window is a taper formed by using the the first
three terms of a summation of cosines. It was designed to have close
to the minimal leakage possible.
It is close to optimal, only slightly worse than a Kaiser window.

Parameters
----------
M : int
Number of points in the output window. If zero or less, an
empty array is returned.

Returns
-------
out : array
The window, normalized to one (the value one
appears only if the number of samples is odd).

--------
bartlett, hamming, hanning, kaiser

Notes
-----
The Blackman window is defined as

.. math::  w(n) = 0.42 - 0.5 \cos(2\pi n/M) + 0.08 \cos(4\pi n/M)

Most references to the Blackman window come from the signal processing
literature, where it is used as one of many windowing functions for
smoothing values.  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. It is known as a
"near optimal" tapering function, almost as good (by some measures)
as the kaiser window.

References
----------
.. [1] Blackman, R.B. and Tukey, J.W., (1958) The measurement of power
spectra, Dover Publications, New York.
.. [2] Wikipedia, "Window function",
http://en.wikipedia.org/wiki/Window_function
.. [3] Oppenheim, A.V., and R.W. Schafer. Discrete-Time Signal Processing.
Upper Saddle River, NJ: Prentice-Hall, 1999, pp. 468-471.

Examples
--------
>>> from numpy import blackman
>>> blackman(12)
array([ -1.38777878e-17,   3.26064346e-02,   1.59903635e-01,
4.14397981e-01,   7.36045180e-01,   9.67046769e-01,
9.67046769e-01,   7.36045180e-01,   4.14397981e-01,
1.59903635e-01,   3.26064346e-02,  -1.38777878e-17])

Plot the window and the frequency response:

>>> from numpy import clip, log10, array, bartlett
>>> from scipy.fftpack import fft, fftshift
>>> import matplotlib.pyplot as plt

>>> window = blackman(51)
>>> plt.plot(window)
>>> plt.title("Blackman 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()


### bmat()

numpy.bmat(obj, ldict=None, gdict=None)

Build a matrix object from a string, nested sequence, or array.

Parameters
----------
obj : string, sequence or array
Input data.  Variables names in the current scope may
be referenced, even if obj is a string.

Returns
-------
out : matrix
Returns a matrix object, which is a specialized 2-D array.

--------
matrix

Examples
--------
>>> A = np.mat('1 1; 1 1')
>>> B = np.mat('2 2; 2 2')
>>> C = np.mat('3 4; 5 6')
>>> D = np.mat('7 8; 9 0')

All the following expressions construct the same block matrix:

>>> np.bmat([[A, B], [C, D]])
matrix([[1, 1, 2, 2],
[1, 1, 2, 2],
[3, 4, 7, 8],
[5, 6, 9, 0]])
>>> np.bmat(np.r_[np.c_[A, B], np.c_[C, D]])
matrix([[1, 1, 2, 2],
[1, 1, 2, 2],
[3, 4, 7, 8],
[5, 6, 9, 0]])
>>> np.bmat('A,B; C,D')
matrix([[1, 1, 2, 2],
[1, 1, 2, 2],
[3, 4, 7, 8],
[5, 6, 9, 0]])


>>> from numpy import *
>>> a = mat('1 2; 3 4')
>>> b = mat('5 6; 7 8')
>>> bmat('a b; b a')       # all elements must be existing symbols
matrix([[1, 2, 5, 6],
[3, 4, 7, 8],
[5, 6, 1, 2],
[7, 8, 3, 4]])


>>> from numpy import *
>>> a = array([[1,2],[3,4]])
>>> b = array([5,6])
>>> c.nd                                     # the number of dimensions in the broadcasted result
2
>>> c.shape                                  # the shape of the broadcasted result
(2, 2)
>>> c.size                                   # total size of the broadcasted result
4
>>> for value in c: print value
...
(1, 5)
(2, 6)
(3, 5)
(4, 6)
>>> c.reset()                                # reset the iterator to the beginning
>>> c.next()                                 # next element
(1, 5)


Broadcast any number of arrays against each other.

Parameters
----------
*args : arrays

Returns
-------
These arrays are views on the original arrays. They are typically not
contiguous. Furthermore, more than one element of a broadcasted array
may refer to a single memory location. If you need to write to the
arrays, make copies first.

Examples
--------
>>> x = np.array([[1,2,3]])
>>> y = np.array([[1],[2],[3]])
[array([[1, 2, 3],
[1, 2, 3],
[1, 2, 3]]), array([[1, 1, 1],
[2, 2, 2],
[3, 3, 3]])]

Here is a useful idiom for getting contiguous copies instead of
non-contiguous views.

[array([[1, 2, 3],
[1, 2, 3],
[1, 2, 3]]), array([[1, 1, 1],
[2, 2, 2],
[3, 3, 3]])]


### byte_bounds()

numpy.byte_bounds(a)

(low, high) are pointers to the end-points of an array

low is the first byte
high is just *past* the last byte

If the array is not single-segment, then it may not actually
use every byte between these bounds.

The array provided must conform to the Python-side of the array interface


### bytes()

numpy.random.bytes(...)

bytes(length)

Return random bytes.

Parameters
----------
length : int
Number of random bytes.

Returns
-------
out : str
String of length N.

Examples
--------
>>> np.random.bytes(10)
' eh\x85\x022SZ\xbf\xa4' #random


>>> from numpy import *
>>> from numpy.random import bytes
>>> print repr(bytes(5))        # string of 5 random bytes
'o\x07\x9f\xdf\xdf'
>>> print repr(bytes(5))        # another string of 5 random bytes
'\x98\xc9KD\xe0'


### byteswap()

ndarray.byteswap(...)

a.byteswap(inplace)

Swap the bytes of the array elements

Toggle between low-endian and big-endian data representation by
returning a byteswapped array, optionally swapped in-place.

Parameters
----------
inplace: bool, optional
If True, swap bytes in-place, default is False.

Returns
-------
out: ndarray
The byteswapped array. If inplace is True, this is
a view to self.

Examples
--------
>>> A = np.array([1, 256, 8755], dtype=np.int16)
>>> map(hex, A)
['0x1', '0x100', '0x2233']
>>> A.byteswap(True)
array([  256,     1, 13090], dtype=int16)
>>> map(hex, A)
['0x100', '0x1', '0x3322']

Arrays of strings are not swapped

>>> A = np.array(['ceg', 'fac'])
>>> A.byteswap()
array(['ceg', 'fac'],
dtype='|S3')


### c_

numpy.c_

Translates slice objects to concatenation along the second axis.

For example:
>>> np.c_[np.array([[1,2,3]]), 0, 0, np.array([[4,5,6]])]
array([1, 2, 3, 0, 0, 4, 5, 6])


>>> from numpy import *
>>> c_[1:5]                           # for single ranges, c_ works like r_
array([1, 2, 3, 4])
>>> c_[1:5,2:6]                       # for comma separated values, c_ stacks column-wise
array([[1, 2],
[2, 3],
[3, 4],
[4, 5]])
>>> a = array([[1,2,3],[4,5,6]])
>>> c_[a,a]                           # concatenation along last (default) axis (column-wise, that's why it's called c_)
array([[1, 2, 3, 1, 2, 3],
[4, 5, 6, 4, 5, 6]])
>>> c_['0',a,a]                       # concatenation along 1st axis, equivalent to r_[a,a]
array([[1, 2, 3],
[4, 5, 6],
[1, 2, 3],
[4, 5, 6]])


### cast[]()

>>> from numpy import *
>>> x = arange(3)
>>> x.dtype
dtype('int32')
>>> cast['int64'](x)
array([0, 1, 2], dtype=int64)
>>> cast['uint'](x)
array([0, 1, 2], dtype=uint32)
>>> cast[float128](x)
array([0.0, 1.0, 2.0], dtype=float128)
>>> cast.keys()                                              # list dtype cast possibilities
<snip>


### can_cast()

numpy.can_cast(...)

can_cast(from=d1, to=d2)

Returns True if cast between data types can occur without losing precision.

Parameters
----------
from: data type code
Data type code to cast from.
to: data type code
Data type code to cast to.

Returns
-------
out : bool
True if cast can occur without losing precision.


### ceil()

numpy.ceil(...)

y = ceil(x)

Return the ceiling of the input, element-wise.

The ceil of the scalar x is the smallest integer i, such that
i >= x.  It is often denoted as :math:\lceil x \rceil.

Parameters
----------
x : array_like
Input data.

Returns
-------
y : {ndarray, scalar}
The ceiling of each element in x.

Examples
--------
>>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0])
>>> np.ceil(a)
array([-1., -1., -0.,  1.,  2.,  2.,  2.])


>>> from numpy import *
>>> a = array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7])
>>> ceil(a)                                                # nearest integers greater-than or equal to a
array([-1., -1., -0.,  1.,  2.,  2.])


### choose()

numpy.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 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, n-1], where n is the number
of choices.
choices : sequence of arrays
Choice arrays. The index array and all of the choices should be
out : array, optional
If provided, the result will be inserted into this array. It should
be of the appropriate shape and dtype
mode : {'raise', 'wrap', 'clip'}, optional
Specifies how out-of-bounds indices will behave:

* 'raise' : raise an error
* 'wrap' : wrap around
* 'clip' : clip to the range

Returns
-------
merged_array : array
The merged results.

--------
ndarray.choose : equivalent method

Examples
--------

>>> choices = [[0, 1, 2, 3], [10, 11, 12, 13],
...   [20, 21, 22, 23], [30, 31, 32, 33]]
>>> np.choose([2, 3, 1, 0], choices)
array([20, 31, 12,  3])
>>> np.choose([2, 4, 1, 0], choices, mode='clip')
array([20, 31, 12,  3])
>>> np.choose([2, 4, 1, 0], choices, mode='wrap')
array([20,  1, 12,  3])


ndarray.choose(...)

a.choose(choices, out=None, mode='raise')

Use an index array to construct a new array from a set of choices.

Refer to numpy.choose for full documentation.

--------
numpy.choose : equivalent function


>>> from numpy import *
>>> choice0 =array([10,12,14,16])                   # selector and choice arrays must be equally sized
>>> choice1 =array([20,22,24,26])
>>> choice2 =array([30,32,34,36])
>>> selector = array([0,0,2,1])                     # selector can only contain integers in range(number_of_choice_arrays)
>>> selector.choose(choice0,choice1,choice2)
array([10, 12, 34, 26])
>>> a = arange(4)
>>> choose(a >= 2, (choice0, choice1))              # separate function also exists
array([10, 12, 24, 26])


### clip()

numpy.clip(a, a_min, a_max, out=None)

Clip (limit) the values in an array.

Given an interval, values outside the interval are clipped to
the interval edges.  For example, if an interval of [0, 1]
is specified, values smaller than 0 become 0, and values larger
than 1 become 1.

Parameters
----------
a : array_like
Array containing elements to clip.
a_min : scalar or array_like
Minimum value.
a_max : scalar or array_like
Maximum value.  If a_min or a_max are array_like, then they will
be broadcasted to the shape of a.
out : ndarray, optional
The results will be placed in this array. It may be the input
array for in-place clipping.  out must be of the right shape
to hold the output.  Its type is preserved.

Returns
-------
clipped_array : ndarray
An array with the elements of a, but where values
< a_min are replaced with a_min, and those > a_max
with a_max.

Examples
--------
>>> a = np.arange(10)
>>> np.clip(a, 1, 8)
array([1, 1, 2, 3, 4, 5, 6, 7, 8, 8])
>>> a
array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
>>> np.clip(a, 3, 6, out=a)
array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6])
>>> a
array([3, 3, 3, 3, 4, 5, 6, 6, 6, 6])
>>> a = np.arange(10)
>>> np.clip(a, [3,4,1,1,1,4,4,4,4,4], 8)
array([3, 4, 2, 3, 4, 5, 6, 7, 8, 8])


ndarray.clip(...)

a.clip(a_min, a_max, out=None)

Return an array whose values are limited to [a_min, a_max].

Refer to numpy.clip for full documentation.

--------
numpy.clip : equivalent function


>>> from numpy import *
>>> a = array([5,15,25,3,13])
>>> a.clip(min=10,max=20)
array([10, 15, 20, 10, 13])
>>> clip(a,10,20)                             # this syntax also exists


### column_stack()

numpy.column_stack(tup)

Stack 1-D arrays as columns into a 2-D array

Take a sequence of 1-D arrays and stack them as columns
to make a single 2-D array. 2-D arrays are stacked as-is,
just like with hstack.  1-D arrays are turned into 2-D columns
first.

Parameters
----------
tup : sequence of 1-D or 2-D arrays.
Arrays to stack. All of them must have the same first dimension.

Examples
--------
>>> a = np.array((1,2,3))
>>> b = np.array((2,3,4))
>>> np.column_stack((a,b))
array([[1, 2],
[2, 3],
[3, 4]])


>>> from numpy import *
>>> a = array([1,2])
>>> b = array([3,4])
>>> c = array([5,6])
>>> column_stack((a,b,c))               # a,b,c are 1-d arrays with equal length
array([[1, 3, 5],
[2, 4, 6]])


### common_type()

numpy.common_type(*arrays)

Return the inexact scalar type which is most common in a list of arrays.

The return type will always be an inexact scalar type, even if all the
arrays are integer arrays

Parameters
----------
array1, array2, ... : ndarray
Input arrays.

Returns
-------
out : data type code
Data type code.

--------
dtype

Examples
--------
>>> np.common_type(np.arange(4), np.array([45,6]), np.array([45.0, 6.0]))
<type 'numpy.float64'>


### compare_chararrays()

numpy.compare_chararrays(...)

### compress()

numpy.compress(condition, a, axis=None, out=None)

Return selected slices of an array along given axis.

Parameters
----------
condition : array_like
Boolean 1-D array selecting which entries to return. If len(condition)
is less than the size of a along the given axis, then output is
truncated to the length of the condition array.
a : array_like
Array from which to extract a part.
axis : int, optional
Axis along which to take slices. If None (default), work on the
flattened array.
out : ndarray, optional
Output array.  Its type is preserved and it must be of the right
shape to hold the output.

Returns
-------
compressed_array : ndarray
A copy of a without the slices along axis for which condition
is false.

--------
ndarray.compress: Equivalent method.

Examples
--------
>>> a = np.array([[1, 2], [3, 4]])
>>> np.compress([0, 1], a, axis=0)
array([[3, 4]])
>>> np.compress([1], a, axis=1)
array([[1],
[3]])
>>> np.compress([0,1,1], a)
array([2, 3])


ndarray.compress(...)

a.compress(condition, axis=None, out=None)

Return selected slices of this array along given axis.

Refer to numpy.compress for full documentation.

--------
numpy.compress : equivalent function


>>> from numpy import *
>>> a = array([10, 20, 30, 40])
>>> condition = (a > 15) & (a < 35)
>>> condition
array([False, True, True, False], dtype=bool)
>>> a.compress(condition)
array([20, 30])
>>> a[condition]                                      # same effect
array([20, 30])
>>> compress(a >= 30, a)                              # this form also exists
array([30, 40])
>>> b = array([[10,20,30],[40,50,60]])
>>> b.compress(b.ravel() >= 22)
array([30, 40, 50, 60])
>>> x = array([3,1,2])
>>> y = array([50, 101])
>>> b.compress(x >= 2, axis=1)                       # illustrates the use of the axis keyword
array([[10, 30],
[40, 60]])
>>> b.compress(y >= 100, axis=0)
array([[40, 50, 60]])


### concatenate()

numpy.concatenate(...)

concatenate((a1, a2, ...), axis=0)

Join a sequence of arrays together.

Parameters
----------
a1, a2, ... : sequence of ndarrays
The arrays must have the same shape, except in the dimension
corresponding to axis (the first, by default).
axis : int, optional
The axis along which the arrays will be joined.  Default is 0.

Returns
-------
res : ndarray
The concatenated array.

--------
array_split : Split an array into multiple sub-arrays of equal or
near-equal size.
split : Split array into a list of multiple sub-arrays of equal size.
hsplit : Split array into multiple sub-arrays horizontally (column wise)
vsplit : Split array into multiple sub-arrays vertically (row wise)
dsplit : Split array into multiple sub-arrays along the 3rd axis (depth).
hstack : Stack arrays in sequence horizontally (column wise)
vstack : Stack arrays in sequence vertically (row wise)
dstack : Stack arrays in sequence depth wise (along third dimension)

Examples
--------
>>> a = np.array([[1, 2], [3, 4]])
>>> b = np.array([[5, 6]])
>>> np.concatenate((a, b), axis=0)
array([[1, 2],
[3, 4],
[5, 6]])


>>> from numpy import *
>>> x = array([[1,2],[3,4]])
>>> y = array([[5,6],[7,8]])
>>> concatenate((x,y))                          # default is axis=0
array([[1, 2],
[3, 4],
[5, 6],
[7, 8]])
>>> concatenate((x,y),axis=1)
array([[1, 2, 5, 6],
[3, 4, 7, 8]])


### conj()

numpy.conj(...)

y = conjugate(x)

Return the complex conjugate, element-wise.

The complex conjugate of a complex number is obtained by changing the
sign of its imaginary part.

Parameters
----------
x : array_like
Input value.

Returns
-------
y : ndarray
The complex conjugate of x, with same dtype as y.

Examples
--------
>>> np.conjugate(1+2j)
(1-2j)


ndarray.conj(...)

a.conj()

Return an array with all complex-valued elements conjugated.


Synonym for conjugate()

See conjugate()

### conjugate()

numpy.conjugate(...)

y = conjugate(x)

Return the complex conjugate, element-wise.

The complex conjugate of a complex number is obtained by changing the
sign of its imaginary part.

Parameters
----------
x : array_like
Input value.

Returns
-------
y : ndarray
The complex conjugate of x, with same dtype as y.

Examples
--------
>>> np.conjugate(1+2j)
(1-2j)


ndarray.conjugate(...)

a.conjugate()

Return an array with all complex-valued elements conjugated.


>>> a = array([1+2j,3-4j])
>>> a.conj()                              # .conj() and .conjugate() are the same
array([ 1.-2.j,  3.+4.j])
>>> a.conjugate()
array([ 1.-2.j,  3.+4.j])
>>> conj(a)                              # is also possible
>>> conjugate(a)                         # is also possible


### convolve()

numpy.convolve(a, v, mode='full')

Returns the discrete, linear convolution of two one-dimensional sequences.

The convolution operator is often seen in signal processing, where it
models the effect of a linear time-invariant system on a signal [1]_.  In
probability theory, the sum of two independent random variables is
distributed according to the convolution of their individual
distributions.

Parameters
----------
a : (N,) array_like
First one-dimensional input array.
v : (M,) array_like
Second one-dimensional input array.
mode : {'full', 'valid', 'same'}, optional
'full':
By default, mode is 'full'.  This returns the convolution
at each point of overlap, with an output shape of (N+M-1,). At
the end-points of the convolution, the signals do not overlap
completely, and boundary effects may be seen.

'same':
Mode same returns output of length max(M, N).  Boundary
effects are still visible.

'valid':
Mode valid returns output of length
max(M, N) - min(M, N) + 1.  The convolution product is only given
for points where the signals overlap completely.  Values outside
the signal boundary have no effect.

Returns
-------
out : ndarray
Discrete, linear convolution of a and v.

--------
scipy.signal.fftconv : Convolve two arrays using the Fast Fourier
Transform.
scipy.linalg.toeplitz : Used to construct the convolution operator.

Notes
-----
The discrete convolution operation is defined as

.. math:: (f * g)[n] = \sum_{m = -\infty}^{\infty} f[m] f[n - m]

It can be shown that a convolution :math:x(t) * y(t) in time/space
is equivalent to the multiplication :math:X(f) Y(f) in the Fourier
circular convolution).  Since multiplication is more efficient (faster)
than convolution, the function scipy.signal.fftconvolve exploits the
FFT to calculate the convolution of large data-sets.

References
----------
.. [1] Wikipedia, "Convolution", http://en.wikipedia.org/wiki/Convolution.

Examples
--------
Note how the convolution operator flips the second array
before "sliding" the two across one another:

>>> np.convolve([1, 2, 3], [0, 1, 0.5])
array([ 0. ,  1. ,  2.5,  4. ,  1.5])

Only return the middle values of the convolution.
Contains boundary effects, where zeros are taken
into account:

>>> np.convolve([1,2,3],[0,1,0.5], 'same')
array([ 1. ,  2.5,  4. ])

The two arrays are of the same length, so there
is only one position where they completely overlap:

>>> np.convolve([1,2,3],[0,1,0.5], 'valid')
array([ 2.5])


### copy()

numpy.copy(a)

Return an array copy of the given object.

Parameters
----------
a : array_like
Input data.

Returns
-------
arr : ndarray
Array interpretation of a.

Notes
-----
This is equivalent to

>>> np.array(a, copy=True)

Examples
--------
Create an array x, with a reference y and a copy z:

>>> x = np.array([1, 2, 3])
>>> y = x
>>> z = np.copy(x)

Note that, when we modify x, y changes, but not z:

>>> x[0] = 10
>>> x[0] == y[0]
True
>>> x[0] == z[0]
False


ndarray.copy(...)

a.copy(order='C')

Return a copy of the array.

Parameters
----------
order : {'C', 'F', 'A'}, optional
By default, the result is stored in C-contiguous (row-major) order in
memory.  If order is F, the result has 'Fortran' (column-major)
order.  If order is 'A' ('Any'), then the result has the same order
as the input.

Examples
--------
>>> x = np.array([[1,2,3],[4,5,6]], order='F')

>>> y = x.copy()

>>> x.fill(0)

>>> x
array([[0, 0, 0],
[0, 0, 0]])

>>> y
array([[1, 2, 3],
[4, 5, 6]])

>>> y.flags['C_CONTIGUOUS']
True


>>> from numpy import *
>>> a = array([1,2,3])
>>> a
array([1, 2, 3])
>>> b = a                                  # b is a reference to a
>>> b[1] = 4
>>> a
array([1, 4, 3])
>>> a = array([1,2,3])
>>> b = a.copy()                           # b is now an independent copy of a
>>> b[1] = 4
>>> a
array([1, 2, 3])
>>> b
array([1, 4, 3])


### corrcoef()

numpy.corrcoef(x, y=None, rowvar=1, bias=0)

Return correlation coefficients.

Please refer to the documentation for cov for more detail.  The
relationship between the correlation coefficient matrix, P, and the
covariance matrix, C, is

.. math:: P_{ij} = \frac{ C_{ij} } { \sqrt{ C_{ii} * C_{jj} } }

The values of P are between -1 and 1.

--------
cov : Covariance matrix


>>> from numpy import *
>>> T = array([1.3, 4.5, 2.8, 3.9])         # temperature measurements
>>> P = array([2.7, 8.7, 4.7, 8.2])         # corresponding pressure measurements
>>> print corrcoef([T,P])                   # correlation matrix of temperature and pressure
[[ 1.          0.98062258]
[ 0.98062258  1.        ]]
>>> rho = array([8.5, 5.2, 6.9, 6.5])       # corresponding density measurements
>>> data = column_stack([T,P,rho])
>>> print corrcoef([T,P,rho])               # correlation matrix of T,P and rho
[[ 1.          0.98062258 -0.97090288]
[ 0.98062258  1.         -0.91538464]
[-0.97090288 -0.91538464  1.        ]]


### correlate()

numpy.correlate(a, v, mode='valid')

Discrete, linear correlation of two 1-dimensional sequences.

This function is equivalent to

>>> np.convolve(a, v[::-1], mode=mode)

where v[::-1] is the reverse of v.

Parameters
----------
a, v : array_like
Input sequences.
mode : {'valid', 'same', 'full'}, optional
Refer to the convolve docstring.  Note that the default
is valid, unlike convolve, which uses full.

--------
convolve : Discrete, linear convolution of two
one-dimensional sequences.


### cos()

numpy.cos(...)

y = cos(x)

Cosine elementwise.

Parameters
----------
x : array_like

Returns
-------
out : ndarray
Output array of same shape as x.

Examples
--------
>>> np.cos(np.array([0, np.pi/2, np.pi]))
array([  1.00000000e+00,   6.12303177e-17,  -1.00000000e+00])


>>> cos(array([0, pi/2, pi]))
array([  1.00000000e+00,   6.12303177e-17,  -1.00000000e+00])


### cosh()

numpy.cosh(...)

y = cosh(x)

Hyperbolic cosine, element-wise.

Equivalent to 1/2 * (np.exp(x) + np.exp(-x)) and np.cos(1j*x).

Parameters
----------
x : array_like
Input array.

Returns
-------
out : ndarray
Output array of same shape as x.

Examples
--------
>>> np.cosh(0)
1.0

The hyperbolic cosine describes the shape of a hanging cable:

>>> import matplotlib.pyplot as plt
>>> x = np.linspace(-4, 4, 1000)
>>> plt.plot(x, np.cosh(x))
>>> plt.show()


### cov()

numpy.cov(m, y=None, rowvar=1, bias=0)

Estimate a covariance matrix, given data.

Covariance indicates the level to which two variables vary together.
If we examine N-dimensional samples, :math:X = [x_1, x_2, ... x_N]^T,
then the covariance matrix element :math:C_{ij} is the covariance of
:math:x_i and :math:x_j. The element :math:C_{ii} is the variance
of :math:x_i.

Parameters
----------
m : array_like
A 1-D or 2-D array containing multiple variables and observations.
Each row of m represents a variable, and each column a single
observation of all those variables. Also see rowvar below.
y : array_like, optional
An additional set of variables and observations. y has the same
form as that of m.
rowvar : int, optional
If rowvar is non-zero (default), then each row represents a
variable, with observations in the columns. Otherwise, the relationship
is transposed: each column represents a variable, while the rows
contain observations.
bias : int, optional
Default normalization is by (N-1), where N is the number of
observations given (unbiased estimate). If bias is 1, then
normalization is by N.

Returns
-------
out : ndarray
The covariance matrix of the variables.

--------
corrcoef : Normalized covariance matrix

Examples
--------
Consider two variables, :math:x_0 and :math:x_1, which
correlate perfectly, but in opposite directions:

>>> x = np.array([[0, 2], [1, 1], [2, 0]]).T
>>> x
array([[0, 1, 2],
[2, 1, 0]])

Note how :math:x_0 increases while :math:x_1 decreases. The covariance
matrix shows this clearly:

>>> np.cov(x)
array([[ 1., -1.],
[-1.,  1.]])

Note that element :math:C_{0,1}, which shows the correlation between
:math:x_0 and :math:x_1, is negative.

Further, note how x and y are combined:

>>> x = [-2.1, -1,  4.3]
>>> y = [3,  1.1,  0.12]
>>> X = np.vstack((x,y))
>>> print np.cov(X)
[[ 11.71        -4.286     ]
[ -4.286        2.14413333]]
>>> print np.cov(x, y)
[[ 11.71        -4.286     ]
[ -4.286        2.14413333]]
>>> print np.cov(x)
11.71


>>> from numpy import *
>>> x = array([1., 3., 8., 9.])
>>> variance = cov(x)                       # normalized by N-1
>>> variance = cov(x, bias=1)               # normalized by N
>>> T = array([1.3, 4.5, 2.8, 3.9])         # temperature measurements
>>> P = array([2.7, 8.7, 4.7, 8.2])         # corresponding pressure measurements
>>> cov(T,P)                                # covariance between temperature and pressure
3.9541666666666657
>>> rho = array([8.5, 5.2, 6.9, 6.5])       # corresponding density measurements
>>> data = column_stack([T,P,rho])
>>> print cov(data)                         # covariance matrix of T,P and rho
[[ 1.97583333  3.95416667 -1.85583333]
[ 3.95416667  8.22916667 -3.57083333]
[-1.85583333 -3.57083333  1.84916667]]


### cross()

numpy.cross(a, b, axisa=-1, axisb=-1, axisc=-1, axis=None)

Return the cross product of two (arrays of) vectors.

The cross product is performed over the last axis of a and b by default,
and can handle axes with dimensions 2 and 3. For a dimension of 2,
the z-component of the equivalent three-dimensional cross product is
returned.


>>> from numpy import *
>>> x = array([1,2,3])
>>> y = array([4,5,6])
>>> cross(x,y)                   # vector cross-product
array([-3,  6, -3])


### cumprod()

numpy.cumprod(a, axis=None, dtype=None, out=None)

Return the cumulative product of elements along a given axis.

Parameters
----------
a : array_like
Input array.
axis : int, optional
Axis along which the cumulative product is computed.  By default the
input is flattened.
dtype : dtype, optional
Type of the returned array, as well as of the accumulator in which
the elements are multiplied.  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 instead.
out : ndarray, optional
Alternative output array in which to place the result. It must
have the same shape and buffer length as the expected output
but the type of the resulting values will be cast if necessary.

Returns
-------
cumprod : ndarray
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
--------
>>> a = np.array([1,2,3])
>>> np.cumprod(a) # intermediate results 1, 1*2
...               # total product 1*2*3 = 6
array([1, 2, 6])
>>> a = np.array([[1, 2, 3], [4, 5, 6]])
>>> np.cumprod(a, dtype=float) # specify type of output
array([   1.,    2.,    6.,   24.,  120.,  720.])

The cumulative product for each column (i.e., over the rows of)
a:

>>> np.cumprod(a, axis=0)
array([[ 1,  2,  3],
[ 4, 10, 18]])

The cumulative product for each row (i.e. over the columns of)
a:

>>> np.cumprod(a,axis=1)
array([[  1,   2,   6],
[  4,  20, 120]])


ndarray.cumprod(...)

a.cumprod(axis=None, dtype=None, out=None)

Return the cumulative product of the elements along the given axis.

Refer to numpy.cumprod for full documentation.

--------
numpy.cumprod : equivalent function


>>> from numpy import *
>>> a = array([1,2,3])
>>> a.cumprod()                                # total product 1*2*3 = 6, and intermediate results 1, 1*2
array([1, 2, 6])
>>> cumprod(a)                                 # also exists
array([1, 2, 6])
>>> a = array([[1,2,3],[4,5,6]])
>>> a.cumprod(dtype=float)                     # specify type of output
array([1., 2., 6., 24., 120., 720.])
>>> a.cumprod(axis=0)                          # for each of the 3 columns: product and intermediate results
array([[ 1,  2,  3],
[ 4, 10, 18]])
>>> a.cumprod(axis=1)                          # for each of the two rows: product and intermediate results
array([[  1,   2,   6],
[  4,  20, 120]])


### cumproduct()

numpy.cumproduct(a, axis=None, dtype=None, out=None)

Return the cumulative product over the given axis.

--------
cumprod : equivalent function; see for details.


### cumsum()

numpy.cumsum(a, axis=None, dtype=None, out=None)

Return the cumulative sum of the elements along a given axis.

Parameters
----------
a : array_like
Input array or object that can be converted to an array.
axis : int, optional
Axis along which the cumulative sum is computed. The default
(axis = None) is to compute the cumsum over the flattened
array. axis may be negative, in which case it counts from the
last to the first axis.
dtype : dtype, optional
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
but the type will be cast if necessary.

Returns
-------
cumsum : ndarray.
A new array holding the result is returned unless out is
specified, in which case a reference to out is returned.

Notes
-----
Arithmetic is modular when using integer types, and no error is
raised on overflow.

Examples
--------
>>> a = np.array([[1,2,3],[4,5,6]])
>>> np.cumsum(a)
array([ 1,  3,  6, 10, 15, 21])
>>> np.cumsum(a,dtype=float)     # specifies type of output value(s)
array([  1.,   3.,   6.,  10.,  15.,  21.])
>>> np.cumsum(a,axis=0)      # sum over rows for each of the 3 columns
array([[1, 2, 3],
[5, 7, 9]])
>>> np.cumsum(a,axis=1)      # sum over columns for each of the 2 rows
array([[ 1,  3,  6],
[ 4,  9, 15]])


ndarray.cumsum(...)

a.cumsum(axis=None, dtype=None, out=None)

Return the cumulative sum of the elements along the given axis.

Refer to numpy.cumsum for full documentation.

--------
numpy.cumsum : equivalent function


>>> from numpy import *
>>> a = array([1,2,3])                                  # cumulative sum = intermediate summing results & total sum
>>> a.cumsum()
array([1, 3, 6])
>>> cumsum(a)                                           # also exists
array([1, 3, 6])
>>> a = array([[1,2,3],[4,5,6]])
>>> a.cumsum(dtype=float)                               # specifies type of output value(s)
array([  1.,   3.,   6.,  10.,  15.,  21.])
>>> a.cumsum(axis=0)                                    # sum over rows for each of the 3 columns
array([[1, 2, 3],
[5, 7, 9]])
>>> a.cumsum(axis=1)                                    # sum over columns for each of the 2 rows
array([[ 1,  3,  6],
[ 4,  9, 15]])


### degrees()

numpy.degrees(...)

y = degrees(x)

Convert angles from radians to degrees.

Parameters
----------
x : array_like

Returns
-------
y : ndarray
The corresponding angle in degrees.

--------
unwrap : Remove large jumps in angle by wrapping.

Notes
-----
degrees(x) is 180 * x / pi.

Examples
--------
>>> np.degrees(np.pi/2)
90.0


### delete()

numpy.delete(arr, obj, axis=None)

Return a new array with sub-arrays along an axis deleted.

Parameters
----------
arr : array_like
Input array.
obj : slice, integer or an array of integers
Indicate which sub-arrays to remove.
axis : integer, optional
The axis along which to delete the subarray defined by obj.
If axis is None, obj is applied to the flattened array.

--------
insert : Insert values into an array.
append : Append values at the end of an array.

Examples
--------
>>> arr = np.array([[1,2,3,4],[5,6,7,8],[9,10,11,12]])
>>> arr
array([[ 1,  2,  3,  4],
[ 5,  6,  7,  8],
[ 9, 10, 11, 12]])
>>> np.delete(arr, 1, 0)
array([[ 1,  2,  3,  4],
[ 9, 10, 11, 12]])
>>> np.delete(arr, np.s_[::2], 1)
array([[ 2,  4],
[ 6,  8],
[10, 12]])
>>> np.delete(arr, [1,3,5], None)
array([ 1,  3,  5,  7,  8,  9, 10, 11, 12])


>>> from numpy import *
>>> a = array([0, 10, 20, 30, 40])
>>> delete(a, [2,4])                                 # remove a[2] and a[4]
array([ 0, 10, 30])
>>> a = arange(16).reshape(4,4)
>>> a
array([[ 0,  1,  2,  3],
[ 4,  5,  6,  7],
[ 8,  9, 10, 11],
[12, 13, 14, 15]])
>>> delete(a, s_[1:3], axis=0)                       # remove rows 1 and 2
array([[ 0,  1,  2,  3],
[12, 13, 14, 15]])
>>> delete(a, s_[1:3], axis=1)                       # remove columns 1 and 2
array([[ 0,  3],
[ 4,  7],
[ 8, 11],
[12, 15]])


### deprecate()

numpy.deprecate(func, oldname=None, newname=None)

Deprecate old functions.
Issues a DeprecationWarning, adds warning to oldname's docstring,
rebinds oldname.__name__ and returns new function object.

Example:
oldfunc = deprecate(newfunc, 'oldfunc', 'newfunc')


### deprecate_with_doc()

numpy.deprecate_with_doc(somestr)

Decorator to deprecate functions and provide detailed documentation
with 'somestr' that is added to the functions docstring.

Example:
depmsg = 'function scipy.foo has been merged into numpy.foobar'
@deprecate_with_doc(depmsg)
def foo():
pass


### diag()

numpy.diag(v, k=0)

Extract a diagonal or construct a diagonal array.

Parameters
----------
v : array_like
If v is a 2-dimensional array, return a copy of
its k-th diagonal. If v is a 1-dimensional array,
return a 2-dimensional array with v on the k-th diagonal.
k : int, optional
Diagonal in question.  The defaults is 0.

Examples
--------
>>> x = np.arange(9).reshape((3,3))
>>> x
array([[0, 1, 2],
[3, 4, 5],
[6, 7, 8]])

>>> np.diag(x)
array([0, 4, 8])

>>> np.diag(np.diag(x))
array([[0, 0, 0],
[0, 4, 0],
[0, 0, 8]])


>>> from numpy import *
>>> a = arange(12).reshape(4,3)
>>> print a
[[ 0  1  2]
[ 3  4  5]
[ 6  7  8]
[ 9 10 11]]
>>> print diag(a,k=0)
[0 4 8]
>>> print diag(a,k=1)
[1 5]
>>> print diag(array([1,4,5]),k=0)
[[1 0 0]
[0 4 0]
[0 0 5]]
>>> print diag(array([1,4,5]),k=1)
[[0 1 0 0]
[0 0 4 0]
[0 0 0 5]
[0 0 0 0]]


### diagflat()

numpy.diagflat(v, k=0)

Create a 2-dimensional array with the flattened input as a diagonal.

Parameters
----------
v : array_like
Input data, which is flattened and set as the k-th
diagonal of the output.
k : int, optional
Diagonal to set.  The default is 0.

Examples
--------
>>> np.diagflat([[1,2],[3,4]])
array([[1, 0, 0, 0],
[0, 2, 0, 0],
[0, 0, 3, 0],
[0, 0, 0, 4]])

>>> np.diagflat([1,2], 1)
array([[0, 1, 0],
[0, 0, 2],
[0, 0, 0]])


>>> from numpy import *
>>> x = array([[5,6],[7,8]])
>>> diagflat(x)                    # flatten x, then put elements on diagonal
array([[5, 0, 0, 0],
[0, 6, 0, 0],
[0, 0, 7, 0],
[0, 0, 0, 8]])


### diagonal()

numpy.diagonal(a, offset=0, axis1=0, axis2=1)

Return specified diagonals.

If a is 2-D, returns the diagonal of a 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 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
----------
a : array_like
Array from which the diagonals are taken.
offset : int, optional
Offset of the diagonal from the main diagonal. Can be both positive
and negative. Defaults to main diagonal (0).
axis1 : int, optional
Axis to be used as the first axis of the 2-D subarrays from which
the diagonals should be taken. Defaults to first axis (0).
axis2 : int, optional
Axis to be used as the second axis of the 2-D subarrays from which
the diagonals should be taken. Defaults to second axis (1).

Returns
-------
array_of_diagonals : ndarray
If a is 2-D, a 1-D array containing the diagonal is
returned.  If a has larger dimensions, then an array of
diagonals is returned.

Raises
------
ValueError
If the dimension of a is less than 2.

--------
diag : Matlab workalike for 1-D and 2-D arrays.
diagflat : Create diagonal arrays.
trace : Sum along diagonals.

Examples
--------
>>> a = np.arange(4).reshape(2,2)
>>> a
array([[0, 1],
[2, 3]])
>>> a.diagonal()
array([0, 3])
>>> a.diagonal(1)
array([1])

>>> a = np.arange(8).reshape(2,2,2)
>>> a
array([[[0, 1],
[2, 3]],
<BLANKLINE>
[[4, 5],
[6, 7]]])
>>> a.diagonal(0,-2,-1)
array([[0, 3],
[4, 7]])


ndarray.diagonal(...)

a.diagonal(offset=0, axis1=0, axis2=1)

Return specified diagonals.

Refer to numpy.diagonal for full documentation.

--------
numpy.diagonal : equivalent function


>>> from numpy import *
>>> a = arange(12).reshape(3,4)
>>> print a
[[ 0  1  2  3]
[ 4  5  6  7]
[ 8  9 10 11]]
>>> a.diagonal()
array([ 0,  5, 10])
>>> a.diagonal(offset=1)
array([ 1,  6, 11])
>>> diagonal(a)                            # Also this form exists
array([ 0,  5, 10])


### diff()

numpy.diff(a, n=1, axis=-1)

Calculate the nth order discrete difference along given axis.

Parameters
----------
a : array_like
Input array
n : int, optional
The number of times values are differenced.
axis : int, optional
The axis along which the difference is taken.

Returns
-------
out : ndarray
The n order differences.  The shape of the output is the same as a
except along axis where the dimension is n less.

Examples
--------
>>> x = np.array([0,1,3,9,5,10])
>>> np.diff(x)
array([ 1,  2,  6, -4,  5])
>>> np.diff(x,n=2)
array([  1,   4, -10,   9])
>>> x = np.array([[1,3,6,10],[0,5,6,8]])
>>> np.diff(x)
array([[2, 3, 4],
[5, 1, 2]])
>>> np.diff(x,axis=0)
array([[-1,  2,  0, -2]])


>>> from numpy import *
>>> x = array([0,1,3,9,5,10])
>>> diff(x)                                          # 1st-order differences between the elements of x
array([ 1,  2,  6, -4,  5])
>>> diff(x,n=2)                                      # 2nd-order differences, equivalent to diff(diff(x))
array([  1,   4, -10,   9])
>>> x = array([[1,3,6,10],[0,5,6,8]])
>>> diff(x)                                         # 1st-order differences between the columns (default: axis=-1)
array([[2, 3, 4],
[5, 1, 2]])
>>> diff(x,axis=0)                                  # 1st-order difference between the rows
array([[-1,  2,  0, -2]])


### digitize()

numpy.digitize(...)

digitize(x,bins)

Return the index of the bin to which each value of x belongs.

Each index i returned is such that bins[i-1] <= x < bins[i] if
bins is monotonically increasing, or bins [i-1] > x >= bins[i] if
bins is monotonically decreasing.

Beyond the bounds of the bins 0 or len(bins) is returned as appropriate.


>>> from numpy import *
>>> x = array([0.2, 6.4, 3.0, 1.6])
>>> bins = array([0.0, 1.0, 2.5, 4.0, 10.0])                      # monotonically increasing
>>> d = digitize(x,bins)                                          # in which bin falls each value of x?
>>> d
array([1, 4, 3, 2])
>>> for n in range(len(x)):
...   print bins[d[n]-1], "<=", x[n], "<", bins[d[n]]
...
0.0 <= 0.2 < 1.0
4.0 <= 6.4 < 10.0
2.5 <= 3.0 < 4.0
1.0 <= 1.6 < 2.5


### disp()

numpy.disp(mesg, device=None, linefeed=True)

Display a message on a device

Parameters
----------
mesg : string
Message to display.
device : device object with 'write' method
Device to write message.  If None, defaults to sys.stdout which is
very similar to print.
linefeed : bool, optional
Option whether to print a line feed or not.  Defaults to True.


### divide()

numpy.divide(...)

y = divide(x1,x2)

Divide arguments element-wise.

Parameters
----------
x1 : array_like
Dividend array.
x2 : array_like
Divisor array.

Returns
-------
y : {ndarray, scalar}
The quotient x1/x2, element-wise. Returns a scalar if
both  x1 and x2 are scalars.

--------
seterr : Set whether to raise or warn on overflow, underflow and division
by zero.

Notes
-----
Equivalent to x1 / x2 in terms of array-broadcasting.

Behavior on division by zero can be changed using seterr.

When both x1 and x2 are of an integer type, divide will return
integers and throw away the fractional part. Moreover, division by zero
always yields zero in integer arithmetic.

Examples
--------
>>> np.divide(2.0, 4.0)
0.5
>>> x1 = np.arange(9.0).reshape((3, 3))
>>> x2 = np.arange(3.0)
>>> np.divide(x1, x2)
array([[ NaN,  1. ,  1. ],
[ Inf,  4. ,  2.5],
[ Inf,  7. ,  4. ]])

Note the behavior with integer types:

>>> np.divide(2, 4)
0
>>> np.divide(2, 4.)
0.5

Division by zero always yields zero in integer arithmetic, and does not
raise an exception or a warning:

>>> np.divide(np.array([0, 1], dtype=int), np.array([0, 0], dtype=int))
array([0, 0])

Division by zero can, however, be caught using seterr:

>>> old_err_state = np.seterr(divide='raise')
>>> np.divide(1, 0)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
FloatingPointError: divide by zero encountered in divide

>>> ignored_states = np.seterr(**old_err_state)
>>> np.divide(1, 0)
0


### dot()

numpy.dot(...)

dot(a,b)
Returns the dot product of a and b for arrays of floating point types.
Like the generic numpy equivalent the product sum is over
the last dimension of a and the second-to-last dimension of b.
NB: The first argument is not conjugated.


>>> from numpy import *
>>> x = array([[1,2,3],[4,5,6]])
>>> x.shape
(2, 3)
>>> y = array([[1,2],[3,4],[5,6]])
>>> y.shape
(3, 2)
>>> dot(x,y)                                               # matrix multiplication  (2,3) x (3,2) -> (2,2)
array([[22, 28],
[49, 64]])
>>>
>>> import numpy
>>> if id(dot) == id(numpy.core.multiarray.dot):           # A way to know if you use fast blas/lapack or not.
...   print "Not using blas/lapack!"


### dsplit()

numpy.dsplit(ary, indices_or_sections)

Split array into multiple sub-arrays along the 3rd axis (depth).

Parameters
----------
ary : ndarray
An array, with at least 3 dimensions, to be divided into sub-arrays
depth-wise, or along the third axis.
indices_or_sections: integer or 1D array
If indices_or_sections is an integer, N, the array will be divided
into N equal arrays along axis. If an equal split is not possible,
a ValueError is raised.

if indices_or_sections is a 1D array of sorted integers representing
indices along axis, the array will be divided such that each index
marks the start of each sub-array. If an index exceeds the dimension of
the array along axis, and empty sub-array is returned for that index.
axis : integer, optional
the axis along which to split.  Default is 0.

Returns
-------
sub-arrays : list
A list of sub-arrays.

--------
array_split : Split an array into a list of multiple sub-arrays
of near-equal size.
split : Split array into a list of multiple sub-arrays of equal size.
hsplit : Split array into a list of multiple sub-arrays horizontally
vsplit : Split array into a list of multiple sub-arrays vertically
concatenate : Join arrays together.
hstack : Stack arrays in sequence horizontally (column wise)
vstack : Stack arrays in sequence vertically (row wise)
dstack : Stack arrays in sequence depth wise (along third dimension)

Notes
-----
dsplit requires that sub-arrays are of equal shape, whereas
array_split allows for sub-arrays to have nearly-equal shape.
Equivalent to split with axis = 2.

Examples
--------
>>> x = np.arange(16.0).reshape(2, 2, 4)
>>> np.dsplit(x, 2)
<BLANKLINE>
[array([[[  0.,   1.],
[  4.,   5.]],
<BLANKLINE>
[[  8.,   9.],
[ 12.,  13.]]]),
array([[[  2.,   3.],
[  6.,   7.]],
<BLANKLINE>
[[ 10.,  11.],
[ 14.,  15.]]])]
<BLANKLINE>
>>> x = np.arange(16.0).reshape(2, 2, 4)
>>> np.dsplit(x, array([3, 6]))
<BLANKLINE>
[array([[[  0.,   1.,   2.],
[  4.,   5.,   6.]],
<BLANKLINE>
[[  8.,   9.,  10.],
[ 12.,  13.,  14.]]]),
array([[[  3.],
[  7.]],
<BLANKLINE>
[[ 11.],
[ 15.]]]),
array([], dtype=float64)]


>>> from numpy import *
>>> a = array([[1,2],[3,4]])
>>> b = dstack((a,a,a,a))
>>> b.shape                                             # stacking in depth: for k in (0,..,3): b[:,:,k] = a
(2, 2, 4)
>>> c = dsplit(b,2)                                    # split, depth-wise, in 2 equal parts
>>> print c[0].shape, c[1].shape                       # for k in (0,1): c[0][:,:,k] = a   and c[1][:,:,k] = a
(2, 2, 2) (2, 2, 2)
>>> d = dsplit(b,[1,2])                               # split before [:,:,1] and before [:,:,2]
>>> print d[0].shape, d[1].shape, d[2].shape          # for any of the parts: d[.][:,:,k] = a
(2, 2, 1) (2, 2, 1) (2, 2, 2)


### dstack()

numpy.dstack(tup)

Stack arrays in sequence depth wise (along third axis)

Takes a sequence of arrays and stack them along the third axis
to make a single array. Rebuilds arrays divided by dsplit.
This is a simple way to stack 2D arrays (images) into a single
3D array for processing.

Parameters
----------
tup : sequence of arrays
Arrays to stack. All of them must have the same shape along all
but the third axis.

Returns
-------
stacked : ndarray
The array formed by stacking the given arrays.

--------
vstack : Stack along first axis.
hstack : Stack along second axis.
concatenate : Join arrays.
dsplit : Split array along third axis.

Notes
-----
Equivalent to np.concatenate(tup, axis=2)

Examples
--------
>>> a = np.array((1,2,3))
>>> b = np.array((2,3,4))
>>> np.dstack((a,b))
array([[[1, 2],
[2, 3],
[3, 4]]])
>>> a = np.array([[1],[2],[3]])
>>> b = np.array([[2],[3],[4]])
>>> np.dstack((a,b))
array([[[1, 2]],
<BLANKLINE>
[[2, 3]],
<BLANKLINE>
[[3, 4]]])


>>> from numpy import *
>>> a = array([[1,2],[3,4]])          # shapes of a and b can only differ in the 3rd dimension (if present)
>>> b = array([[5,6],[7,8]])
>>> dstack((a,b))                     # stack arrays along a third axis (depth wise)
array([[[1, 5],
[2, 6]],
[[3, 7],
[4, 8]]])


### dtype() or .dtype

numpy.dtype(...)

Create a data type.

A numpy array is homogeneous, and contains elements described by a
dtype.  A dtype can be constructed from different combinations of
fundamental numeric types, as illustrated below.

Examples
--------

Using array-scalar type:
>>> np.dtype(np.int16)
dtype('int16')

Record, one field name 'f1', containing int16:
>>> np.dtype([('f1', np.int16)])
dtype([('f1', '<i2')])

Record, one field named 'f1', in itself containing a record with one field:
>>> np.dtype([('f1', [('f1', np.int16)])])
dtype([('f1', [('f1', '<i2')])])

Record, two fields: the first field contains an unsigned int, the
second an int32:
>>> np.dtype([('f1', np.uint), ('f2', np.int32)])
dtype([('f1', '<u4'), ('f2', '<i4')])

Using array-protocol type strings:
>>> np.dtype([('a','f8'),('b','S10')])
dtype([('a', '<f8'), ('b', '|S10')])

Using comma-separated field formats.  The shape is (2,3):
>>> np.dtype("i4, (2,3)f8")
dtype([('f0', '<i4'), ('f1', '<f8', (2, 3))])

Using tuples.  int is a fixed type, 3 the field's shape.  void
is a flexible type, here of size 10:
>>> np.dtype([('hello',(np.int,3)),('world',np.void,10)])
dtype([('hello', '<i4', 3), ('world', '|V10')])

Subdivide int16 into 2 int8's, called x and y.  0 and 1 are
the offsets in bytes:
>>> np.dtype((np.int16, {'x':(np.int8,0), 'y':(np.int8,1)}))
dtype(('<i2', [('x', '|i1'), ('y', '|i1')]))

Using dictionaries.  Two fields named 'gender' and 'age':
>>> np.dtype({'names':['gender','age'], 'formats':['S1',np.uint8]})
dtype([('gender', '|S1'), ('age', '|u1')])

Offsets in bytes, here 0 and 25:
>>> np.dtype({'surname':('S25',0),'age':(np.uint8,25)})
dtype([('surname', '|S25'), ('age', '|u1')])


ndarray.dtype

Data-type for the array.


>>> from numpy import *
>>> dtype('int16')                                        # using array-scalar type
dtype('int16')
>>> dtype([('f1', 'int16')])                              # record, 1 field named 'f1', containing int16
dtype([('f1', '<i2')])
>>> dtype([('f1', [('f1', 'int16')])])                    # record, 1 field named 'f1' containing a record that has 1 field.
dtype([('f1', [('f1', '<i2')])])
>>> dtype([('f1', 'uint'), ('f2', 'int32')])              # record with 2 fields: field 1 contains an unsigned int, 2nd field an int32
dtype([('f1', '<u4'), ('f2', '<i4')])
>>> dtype([('a','f8'),('b','S10')])                       # using array-protocol type strings
dtype([('a', '<f8'), ('b', '|S10')])
>>> dtype("i4, (2,3)f8")                                  # using comma-separated field formats. (2,3) is the shape
dtype([('f0', '<i4'), ('f1', '<f8', (2, 3))])
>>> dtype([('hello',('int',3)),('world','void',10)])      # using tuples. int is fixed-type: 3 is shape; void is flex-type: 10 is size.
dtype([('hello', '<i4', 3), ('world', '|V10')])
>>> dtype(('int16', {'x':('int8',0), 'y':('int8',1)}))    # subdivide int16 in 2 int8, called x and y. 0 and 1 are the offsets in bytes
dtype(('<i2', [('x', '|i1'), ('y', '|i1')]))
>>> dtype({'names':['gender','age'], 'formats':['S1',uint8]})  # using dictionaries. 2 fields named 'gender' and 'age'
dtype([('gender', '|S1'), ('age', '|u1')])
>>> dtype({'surname':('S25',0),'age':(uint8,25)})         # 0 and 25 are offsets in bytes
dtype([('surname', '|S25'), ('age', '|u1')])
>>>
>>> a = dtype('int32')
>>> a
dtype('int32')
>>> a.type                                                # type object
<type 'numpy.int32'>
>>> a.kind                                                # character code (one of 'biufcSUV') to identify general type
'i'
>>> a.char                                                # unique char code of each of the 21 built-in types
'l'
>>> a.num                                                 # unique number of each of the 21 built-in types
7
>>> a.str                                                 # array-protocol typestring
'<i4'
>>> a.name                                                # name of this datatype
'int32'
>>> a.byteorder                                           # '=':native, '<':little endian, '>':big endian, '|':not applicable
'='
>>> a.itemsize                                            # item size in bytes
4
>>> a = dtype({'surname':('S25',0),'age':(uint8,25)})
>>> a.fields.keys()
['age', 'surname']
>>> a.fields.values()
[(dtype('uint8'), 25), (dtype('|S25'), 0)]
>>> a = dtype([('x', 'f4'),('y', 'f4'),                   # nested field
...     ('nested', [('i', 'i2'),('j','i2')])])
>>> a.fields['nested']                                    # access nested fields
(dtype([('i', '<i2'), ('j', '<i2')]), 8)
>>> a.fields['nested'][0].fields['i']                     # access nested fields
(dtype('int16'), 0)
>>> a.fields['nested'][0].fields['i'][0].type
<type 'numpy.int16'>


### dump()

ndarray.dump(...)

a.dump(file)

Dump a pickle of the array to the specified file.

Parameters
----------
file : str
A string naming the dump file.


### dumps()

ndarray.dumps(...)

a.dumps()

Returns the pickle of the array as a string.


### ediff1d()

numpy.ediff1d(ary, to_end=None, to_begin=None)

The differences between consecutive elements of an array.

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 taked onto the beginning of the
returned differences.

Returns
-------
ed : array
The differences. Loosely, this will be (ary[1:] - ary[:-1]).


### empty()

numpy.empty(...)

empty(shape, dtype=float, order='C')

Return a new array of given shape and type, without initialising entries.

Parameters
----------
shape : {tuple of int, int}
Shape of the empty array
dtype : data-type, optional
Desired output data-type.
order : {'C', 'F'}, optional
Whether to store multi-dimensional data in C (row-major) or
Fortran (column-major) order in memory.

--------
empty_like, zeros

Notes
-----
empty, unlike zeros, does not set the array values to zero,
and may therefore be marginally faster.  On the other hand, it requires
the user to manually set all the values in the array, and should be
used with caution.

Examples
--------
>>> np.empty([2, 2])
array([[ -9.74499359e+001,   6.69583040e-309],  #random data
[  2.13182611e-314,   3.06959433e-309]])

>>> np.empty([2, 2], dtype=int)
array([[-1073741821, -1067949133],  #random data
[  496041986,    19249760]])


>>> from numpy import *
>>> empty(3)                                                               # uninitialized array, size=3, dtype = float
array([  6.08581638e+000,   3.45845952e-323,   4.94065646e-324])
>>> empty((2,3),int)                                                       # uninitialized array, dtype = int
array([[1075337192, 1075337192,  135609024],
[1084062604, 1197436517, 1129066306]])


### empty_like()

numpy.empty_like(a)

Create a new array with the same shape and type as another.

Parameters
----------
a : ndarray
Returned array will have same shape and type as a.

--------
zeros_like, ones_like, zeros, ones, empty

Notes
-----
This function does *not* initialize the returned array; to do that use
zeros_like or ones_like instead.

Examples
--------
>>> a = np.array([[1,2,3],[4,5,6]])
>>> np.empty_like(a)
>>> np.empty_like(a)
array([[-1073741821, -1067702173,       65538],    #random data
[      25670,    23454291,       71800]])


>>> from numpy import *
>>> a = array([[1,2,3],[4,5,6]])
>>> empty_like(a)                                            # uninitialized array with the same shape and datatype as 'a'
array([[        0,  25362433,   6571520],
[    21248, 136447968,         4]])


### equal()

numpy.equal(...)

y = equal(x1,x2)

Returns elementwise x1 == x2 in a bool array.

Parameters
----------
x1, x2 : array_like
Input arrays of the same shape.

Returns
-------
out : boolean
The elementwise test x1 == x2.


### exp()

numpy.exp(...)

y = exp(x)

Calculate the exponential of the elements in the input array.

Parameters
----------
x : array_like
Input values.

Returns
-------
out : ndarray
Element-wise exponential of x.

Notes
-----
The irrational number e is also known as Euler's number.  It is
approximately 2.718281, and is the base of the natural logarithm,
ln (this means that, if :math:x = \ln y = \log_e y,
then :math:e^x = y. For real input, exp(x) is always positive.

For complex arguments, x = a + ib, we can write
:math:e^x = e^a e^{ib}.  The first term, :math:e^a, is already
known (it is the real argument, described above).  The second term,
:math:e^{ib}, is :math:\cos b + i \sin b, a function with magnitude
1 and a periodic phase.

References
----------
.. [1] Wikipedia, "Exponential function",
http://en.wikipedia.org/wiki/Exponential_function
.. [2] M. Abramovitz and I. A. Stegun, "Handbook of Mathematical Functions
with Formulas, Graphs, and Mathematical Tables," Dover, 1964, p. 69,
http://www.math.sfu.ca/~cbm/aands/page_69.htm

Examples
--------
Plot the magnitude and phase of exp(x) in the complex plane:

>>> import matplotlib.pyplot as plt

>>> x = np.linspace(-2*np.pi, 2*np.pi, 100)
>>> xx = x + 1j * x[:, np.newaxis] # a + ib over complex plane
>>> out = np.exp(xx)

>>> plt.subplot(121)
>>> plt.imshow(np.abs(out),
...            extent=[-2*np.pi, 2*np.pi, -2*np.pi, 2*np.pi])
>>> plt.title('Magnitude of exp(x)')

>>> plt.subplot(122)
>>> plt.imshow(np.angle(out),
...            extent=[-2*np.pi, 2*np.pi, -2*np.pi, 2*np.pi])
>>> plt.title('Phase (angle) of exp(x)')
>>> plt.show()


### expand_dims()

numpy.expand_dims(a, axis)

Expand the shape of an array.

Insert a new axis, corresponding to a given position in the array shape.

Parameters
----------
a : array_like
Input array.
axis : int
Position (amongst axes) where new axis is to be inserted.

Returns
-------
res : ndarray
Output array. The number of dimensions is one greater than that of
the input array.

--------
doc.indexing, atleast_1d, atleast_2d, atleast_3d

Examples
--------
>>> x = np.array([1,2])
>>> x.shape
(2,)

The following is equivalent to x[np.newaxis,:] or x[np.newaxis]:

>>> y = np.expand_dims(x, axis=0)
>>> y
array([[1, 2]])
>>> y.shape
(1, 2)

>>> y = np.expand_dims(x, axis=1)  # Equivalent to x[:,newaxis]
>>> y
array([[1],
[2]])
>>> y.shape
(2, 1)

Note that some examples may use None instead of np.newaxis.  These
are the same objects:

>>> np.newaxis is None
True


>>> from numpy import *
>>> x = array([1,2])
>>> expand_dims(x,axis=0)                           # Equivalent to x[newaxis,:] or x[None] or x[newaxis]
array([[1, 2]])
>>> expand_dims(x,axis=1)                           # Equivalent to x[:,newaxis]
array([[1],
[2]])


### expm1()

numpy.expm1(...)

y = expm1(x)

Return the exponential of the elements in the array minus one.

Parameters
----------
x : array_like
Input values.

Returns
-------
out : ndarray
Element-wise exponential minus one: out=exp(x)-1.

--------
log1p : log(1+x), the inverse of expm1.

Notes
-----
This function provides greater precision than using exp(x)-1
for small values of x.

Examples
--------
Since the series expansion of e**x = 1 + x + x**2/2! + x**3/3! + ...,
for very small x we expect that e**x -1 ~ x + x**2/2:

>>> np.expm1(1e-10)
1.00000000005e-10
>>> np.exp(1e-10) - 1
1.000000082740371e-10


### extract()

numpy.extract(condition, arr)

Return the elements of an array that satisfy some condition.

This is equivalent to np.compress(ravel(condition), ravel(arr)).  If
condition is boolean np.extract is equivalent to arr[condition].

Parameters
----------
condition : array_like
An array whose nonzero or True entries indicate the elements of arr
to extract.
arr : array_like
Input array of the same size as condition.

--------

Examples
--------
>>> arr = np.array([[1,2,3,4],[5,6,7,8],[9,10,11,12]])
>>> arr
array([[ 1,  2,  3,  4],
[ 5,  6,  7,  8],
[ 9, 10, 11, 12]])
>>> condition = np.mod(arr, 3)==0
>>> condition
array([[False, False,  True, False],
[False,  True, False, False],
[ True, False, False,  True]], dtype=bool)
>>> np.extract(condition, arr)
array([ 3,  6,  9, 12])

If condition is boolean:

>>> arr[condition]
array([ 3,  6,  9, 12])


### eye()

numpy.eye(N, M=None, k=0, dtype=<type 'float'>)

Return a 2-D array with ones on the diagonal and zeros elsewhere.

Parameters
----------
N : int
Number of rows in the output.
M : int, optional
Number of columns in the output. If None, defaults to N.
k : int, optional
Index of the diagonal: 0 refers to the main diagonal, a positive value
refers to an upper diagonal, and a negative value to a lower diagonal.
dtype : dtype, optional
Data-type of the returned array.

Returns
-------
I : ndarray (N,M)
An array where all elements are equal to zero, except for the k-th
diagonal, whose values are equal to one.

--------
diag : Return a diagonal 2-D array using a 1-D array specified by the user.

Examples
--------
>>> np.eye(2, dtype=int)
array([[1, 0],
[0, 1]])
>>> np.eye(3, k=1)
array([[ 0.,  1.,  0.],
[ 0.,  0.,  1.],
[ 0.,  0.,  0.]])


>>> from numpy import *
>>> eye(3,4,0,dtype=float)              # a 3x4 matrix containing zeros except for the 0th diagonal that contains ones
array([[ 1.,  0.,  0.,  0.],
[ 0.,  1.,  0.,  0.],
[ 0.,  0.,  1.,  0.]])
>>> eye(3,4,1,dtype=float)             # a 3x4 matrix containing zeros except for the 1st diagonal that contains ones
array([[ 0.,  1.,  0.,  0.],
[ 0.,  0.,  1.,  0.],
[ 0.,  0.,  0.,  1.]])


### fabs()

numpy.fabs(...)

y = fabs(x)

Compute the absolute values elementwise.

This function returns the absolute values (positive magnitude) of the data
in x. Complex values are not handled, use absolute to find the
absolute values of complex data.

Parameters
----------
x : array_like
The array of numbers for which the absolute values are required. If
x is a scalar, the result y will also be a scalar.

Returns
-------
y : {ndarray, scalar}
The absolute values of x, the returned values are always floats.

--------
absolute : Absolute values including complex types.

Examples
--------
>>> np.fabs(-1)
1.0
>>> np.fabs([-1.2, 1.2])
array([ 1.2,  1.2])


### fastCopyAndTranspose()

numpy.fastCopyAndTranspose(...)

_fastCopyAndTranspose(a)


### fft

numpy.fft

Core FFT routines
==================

Standard FFTs

fft
ifft
fft2
ifft2
fftn
ifftn

Real FFTs

rfft
irfft
rfft2
irfft2
rfftn
irfftn

Hermite FFTs

hfft
ihfft


>>> from numpy import *
>>> from numpy.fft import *
>>> signal = array([-2.,  8., -6.,  4.,  1., 0.,  3.,  5.])    # could also be complex
>>> fourier = fft(signal)
>>> fourier
array([ 13.         +0.j        ,   3.36396103 +4.05025253j,
2.         +1.j        ,  -9.36396103-13.94974747j,
-21.         +0.j        ,  -9.36396103+13.94974747j,
2.         -1.j        ,   3.36396103 -4.05025253j])
>>>
>>> N = len(signal)
>>> fourier = empty(N,complex)
>>> for k in range(N):                                         # equivalent but much slower
...    fourier[k] = sum(signal * exp(-1j*2*pi*k*arange(N)/N))
...
>>> timestep = 0.1                                             # if unit=day -> freq unit=cycles/day
>>> fftfreq(N, d=timestep)                                     # freqs corresponding to 'fourier'
array([ 0.  ,  1.25,  2.5 ,  3.75, -5.  , -3.75, -2.5 , -1.25])


### fftfreq

>>> from numpy import *
>>> from numpy.fft import *
>>> signal = array([-2.,  8., -6.,  4.,  1., 0.,  3.,  5.])
>>> fourier = fft(signal)
>>> N = len(signal)
>>> timestep = 0.1                                             # if unit=day -> freq unit=cycles/day
>>> freq = fftfreq(N, d=timestep)                              # freqs corresponding to 'fourier'
>>> freq
array([ 0.  ,  1.25,  2.5 ,  3.75, -5.  , -3.75, -2.5 , -1.25])
>>>
>>> fftshift(freq)                                             # freqs in ascending order
array([-5.  , -3.75, -2.5 , -1.25,  0.  ,  1.25,  2.5 ,  3.75])


### fftshift

>>> from numpy import *
>>> from numpy.fft import *
>>> signal = array([-2.,  8., -6.,  4.,  1., 0.,  3.,  5.])
>>> fourier = fft(signal)
>>> N = len(signal)
>>> timestep = 0.1                                             # if unit=day -> freq unit=cycles/day
>>> freq = fftfreq(N, d=timestep)                              # freqs corresponding to 'fourier'
>>> freq
array([ 0.  ,  1.25,  2.5 ,  3.75, -5.  , -3.75, -2.5 , -1.25])
>>>
>>> freq = fftshift(freq)                                      # freqs in ascending order
>>> freq
array([-5.  , -3.75, -2.5 , -1.25,  0.  ,  1.25,  2.5 ,  3.75])
>>> fourier = fftshift(fourier)                                # adjust fourier to new freq order
>>>
>>> freq = ifftshift(freq)                                     # undo previous frequency shift
>>> fourier = ifftshift(fourier)                               # undo previous fourier shift


### fill()

ndarray.fill(...)

a.fill(value)

Fill the array with a scalar value.

Parameters
----------
a : ndarray
Input array
value : scalar
All elements of a will be assigned this value.

Examples
--------
>>> a = np.array([1, 2])
>>> a.fill(0)
>>> a
array([0, 0])
>>> a = np.empty(2)
>>> a.fill(1)
>>> a
array([ 1.,  1.])


>>> from numpy import *
>>> a = arange(4, dtype=int)
>>> a
array([0, 1, 2, 3])
>>> a.fill(7)                               # replace all elements with the number 7
>>> a
array([7, 7, 7, 7])
>>> a.fill(6.5)                             # fill value is converted to dtype of a
>>> a
array([6, 6, 6, 6])


### find_common_type()

numpy.find_common_type(array_types, scalar_types)

Determine common type following standard coercion rules

Parameters
----------
array_types : sequence
A list of dtype convertible objects representing arrays
scalar_types : sequence
A list of dtype convertible objects representing scalars

Returns
-------
datatype : dtype
The common data-type which is the maximum of the array_types
ignoring the scalar_types unless the maximum of the scalar_types
is of a different kind.

If the kinds is not understood, then None is returned.

--------
dtype


### finfo()

numpy.finfo(...)

finfo(dtype)

Machine limits for floating point types.

Attributes
----------
eps : floating point number of the appropriate type
The smallest representable number such that 1.0 + eps != 1.0.
epsneg : floating point number of the appropriate type
The smallest representable number such that 1.0 - epsneg != 1.0.
iexp : int
The number of bits in the exponent portion of the floating point
representation.
machar : MachAr
The object which calculated these parameters and holds more detailed
information.
machep : int
The exponent that yields eps.
max : floating point number of the appropriate type
The largest representable number.
maxexp : int
The smallest positive power of the base (2) that causes overflow.
min : floating point number of the appropriate type
The smallest representable number, typically -max.
minexp : int
The most negative power of the base (2) consistent with there being
no leading 0s in the mantissa.
negep : int
The exponent that yields epsneg.
nexp : int
The number of bits in the exponent including its sign and bias.
nmant : int
The number of bits in the mantissa.
precision : int
The approximate number of decimal digits to which this kind of float
is precise.
resolution : floating point number of the appropriate type
The approximate decimal resolution of this type, i.e.
10**-precision.
tiny : floating point number of the appropriate type
The smallest-magnitude usable number.

Parameters
----------
dtype : floating point type, dtype, or instance
The kind of floating point data type to get information about.

--------
numpy.lib.machar.MachAr :
The implementation of the tests that produce this information.
iinfo :
The equivalent for integer data types.

Notes
-----
For developers of numpy: do not instantiate this at the module level. The
initial calculation of these parameters is expensive and negatively impacts
import times. These objects are cached, so calling finfo() repeatedly
inside your functions is not a problem.


>>> from numpy import *
>>> f = finfo(float)                                           # the numbers given are machine dependent
>>> f.nmant, f.nexp                                            # nr of bits in the mantissa and in the exponent
(52, 11)
>>> f.machep                                                   # most negative n so that 1.0 + 2**n != 1.0
-52
>>> f.eps                                                      # floating point precision: 2**machep
array(2.2204460492503131e-16)
>>> f.precision                                                # nr of precise decimal digits: int(-log10(eps))
15
>>> f.resolution                                               # 10**(-precision)
array(1.0000000000000001e-15)
>>> f.negep                                                    # most negative n so that 1.0 - 2**n != 1.0
-53
>>> f.epsneg                                                   # floating point precision: 2**negep
array(1.1102230246251565e-16)
>>> f.minexp                                                   # most negative n so that 2**n gives normal numbers
-1022
>>> f.tiny                                                     # smallest usuable floating point nr: 2**minexp
array(2.2250738585072014e-308)
>>> f.maxexp                                                   # smallest positive n so that 2**n causes overflow
1024
>>> f.min, f.max                                               # the most negative and most positive usuable floating number
(-1.7976931348623157e+308, array(1.7976931348623157e+308))


### fix()

numpy.fix(x, y=None)

Round to nearest integer towards zero.

Round an array of floats element-wise to nearest integer towards zero.
The rounded values are returned as floats.

Parameters
----------
x : array_like
An array of floats to be rounded
y : ndarray, optional
Output array

Returns
-------
out : ndarray of floats
The array of rounded numbers

--------
floor : Round downwards
around : Round to given number of decimals

Examples
--------
>>> np.fix(3.14)
3.0
>>> np.fix(3)
3.0
>>> np.fix([2.1, 2.9, -2.1, -2.9])
array([ 2.,  2., -2., -2.])


>>> from numpy import *
>>> a = array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7])
>>> fix(a)                                                    # round a to nearest integer towards zero
array([-1., -1.,  0.,  0.,  1.,  1.])


### flat

ndarray.flat

A 1-d flat iterator.

Examples
--------
>>> x = np.arange(3*4*5)
>>> x.shape = (3,4,5)
>>> x.flat[19]
19
>>> x.T.flat[19]
31


>>> from numpy import *
>>> a = array([[10,30],[40,60]])
>>> iter = a.flat                    # .flat returns an iterator
>>> iter.next()                      # cycle through array with .next()
10
>>> iter.next()
30
>>> iter.next()
40


### flatnonzero()

numpy.flatnonzero(a)

Return indices that are non-zero in the flattened version of a.

This is equivalent to a.ravel().nonzero()[0].

Parameters
----------
a : ndarray
Input array.

Returns
-------
res : ndarray
Output array, containing the indices of the elements of a.ravel()
that are non-zero.

--------
nonzero : Return the indices of the non-zero elements of the input array.
ravel : Return a 1-D array containing the elements of the input array.

Examples
--------
>>> x = np.arange(-2, 3)
>>> x
array([-2, -1,  0,  1,  2])
>>> np.flatnonzero(x)
array([0, 1, 3, 4])

>>> x.ravel()[np.flatnonzero(x)]
array([-2, -1,  1,  2])


### flatten()

ndarray.flatten(...)

a.flatten(order='C')

Collapse an array into one dimension.

Parameters
----------
order : {'C', 'F'}, optional
Whether to flatten in C (row-major) or Fortran (column-major) order.
The default is 'C'.

Returns
-------
y : ndarray
A copy of the input array, flattened to one dimension.

Examples
--------
>>> a = np.array([[1,2], [3,4]])
>>> a.flatten()
array([1, 2, 3, 4])
>>> a.flatten('F')
array([1, 3, 2, 4])


>>> from numpy import *
>>> a = array([[[1,2]],[[3,4]]])
>>> print a
[[[1 2]]
[[3 4]]]
>>> b = a.flatten()                      # b is now a 1-d version of a, a new array, not a reference
>>> print b
[1 2 3 4]


### fliplr()

numpy.fliplr(m)

Left-right flip.

Flip the entries in each row in the left/right direction.
Columns are preserved, but appear in a different order than before.

Parameters
----------
m : array_like
Input array.

Returns
-------
f : ndarray
A view of m with the columns reversed.  Since a view
is returned, this operation is :math:\mathcal O(1).

--------
flipud : Flip array in the up/down direction.
rot90 : Rotate array counterclockwise.

Notes
-----
Equivalent to A[::-1,...]. Does not require the array to be
two-dimensional.

Examples
--------
>>> A = np.diag([1.,2.,3.])
>>> A
array([[ 1.,  0.,  0.],
[ 0.,  2.,  0.],
[ 0.,  0.,  3.]])
>>> np.fliplr(A)
array([[ 0.,  0.,  1.],
[ 0.,  2.,  0.],
[ 3.,  0.,  0.]])

>>> A = np.random.randn(2,3,5)
>>> np.all(numpy.fliplr(A)==A[:,::-1,...])
True


>>> from numpy import *
>>> a = arange(12).reshape(4,3)
>>> a
array([[ 0,  1,  2],
[ 3,  4,  5],
[ 6,  7,  8],
[ 9, 10, 11]])
>>> fliplr(a)                     # flip left-right
array([[ 2,  1,  0],
[ 5,  4,  3],
[ 8,  7,  6],
[11, 10,  9]])


### flipud()

numpy.flipud(m)

Up-down flip.

Flip the entries in each column in the up/down direction.
Rows are preserved, but appear in a different order than before.

Parameters
----------
m : array_like
Input array.

Returns
-------
out : array_like
A view of m with the rows reversed.  Since a view is
returned, this operation is :math:\mathcal O(1).

Notes
-----
Equivalent to A[::-1,...].
Does not require the array to be two-dimensional.

Examples
--------
>>> A = np.diag([1.0, 2, 3])
>>> A
array([[ 1.,  0.,  0.],
[ 0.,  2.,  0.],
[ 0.,  0.,  3.]])
>>> np.flipud(A)
array([[ 0.,  0.,  3.],
[ 0.,  2.,  0.],
[ 1.,  0.,  0.]])

>>> A = np.random.randn(2,3,5)
>>> np.all(np.flipud(A)==A[::-1,...])
True

>>> np.flipud([1,2])
array([2, 1])


>>> from numpy import *
>>> a = arange(12).reshape(4,3)
>>> a
array([[ 0,  1,  2],
[ 3,  4,  5],
[ 6,  7,  8],
[ 9, 10, 11]])
>>> flipud(a)                       # flip up-down
array([[ 9, 10, 11],
[ 6,  7,  8],
[ 3,  4,  5],
[ 0,  1,  2]])


### floor()

numpy.floor(...)

y = floor(x)

Return the floor of the input, element-wise.

The floor of the scalar x is the largest integer i, such that
i <= x.  It is often denoted as :math:\lfloor x \rfloor.

Parameters
----------
x : array_like
Input data.

Returns
-------
y : {ndarray, scalar}
The floor of each element in x.

Notes
-----
Some spreadsheet programs calculate the "floor-towards-zero", in other
words floor(-2.5) == -2.  NumPy, however, uses the a definition of
floor such that floor(-2.5) == -3.

Examples
--------
>>> a = np.array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7, 2.0])
>>> np.floor(a)
array([-2., -2., -1.,  0.,  1.,  1.,  2.])


>>> from numpy import *
>>> a = array([-1.7, -1.5, -0.2, 0.2, 1.5, 1.7])
>>> floor(a)
array([-2., -2., -1.,  0.,  1.,  1.])                      # nearest integer smaller-than or equal to a                                   # nearest integers greater-than or equal to a


### floor_divide()

numpy.floor_divide(...)

y = floor_divide(x1,x2)

Return the largest integer smaller or equal to the division of the inputs.

Parameters
----------
x1 : array_like
Numerator.
x2 : array_like
Denominator.

Returns
-------
y : ndarray
y = floor(x1/x2)

--------
divide : Standard division.
floor : Round a number to the nearest integer toward minus infinity.
ceil : Round a number to the nearest integer toward infinity.

Examples
--------
>>> np.floor_divide(7,3)
2
>>> np.floor_divide([1., 2., 3., 4.], 2.5)
array([ 0.,  0.,  1.,  1.])


### fmod()

numpy.fmod(...)

y = fmod(x1,x2)

Return the remainder of division.

This is the NumPy implementation of the C modulo operator %.

Parameters
----------
x1 : array_like
Dividend.
x2 : array_like
Divisor.

Returns
-------
y : array_like
The remainder of the division of x1 by x2.

--------
mod : Modulo operation where the quotient is floor(x1,x2).

Notes
-----
The result of the modulo operation for negative dividend and divisors is
bound by conventions. In fmod, the sign of the remainder is the sign of
the dividend, and the sign of the divisor has no influence on the results.

Examples
--------
>>> np.fmod([-3, -2, -1, 1, 2, 3], 2)
array([-1,  0, -1,  1,  0,  1])

>>> np.mod([-3, -2, -1, 1, 2, 3], 2)
array([1, 0, 1, 1, 0, 1])


### frexp()

numpy.frexp(...)

y1,y2 = frexp(x)

Split the number, x, into a normalized fraction (y1) and exponent (y2)


### fromarrays()

numpy.core.records.fromarrays(arrayList, dtype=None, shape=None, formats=None, names=None, titles=None, aligned=False, byteorder=None)

create a record array from a (flat) list of arrays

>>> x1=np.array([1,2,3,4])
>>> x2=np.array(['a','dd','xyz','12'])
>>> x3=np.array([1.1,2,3,4])
>>> r = np.core.records.fromarrays([x1,x2,x3],names='a,b,c')
>>> print r[1]
(2, 'dd', 2.0)
>>> x1[1]=34
>>> r.a
array([1, 2, 3, 4])


>>> from numpy import *
>>> x = array(['Smith','Johnson','McDonald'])                              # datatype is string
>>> y = array(['F','F','M'], dtype='S1')                                   # datatype is a single character
>>> z = array([20,25,23])                                                  # datatype is integer
>>> data = rec.fromarrays([x,y,z], names='surname, gender, age')               # convert to record array
>>> data[0]
('Smith', 'F', 20)
>>> data.age                                                               # names are available as attributes
array([20, 25, 23])


### frombuffer()

numpy.frombuffer(...)

frombuffer(buffer, dtype=float, count=-1, offset=0)

Interpret a buffer as a 1-dimensional array.

Parameters
----------
buffer
An object that exposes the buffer interface.
dtype : data-type, optional
Data type of the returned array.
count : int, optional
Number of items to read. -1 means all data in the buffer.
offset : int, optional
Start reading the buffer from this offset.

Notes
-----
If the buffer has data that is not in machine byte-order, this
should be specified as part of the data-type, e.g.::

>>> dt = np.dtype(int)
>>> dt = dt.newbyteorder('>')
>>> np.frombuffer(buf, dtype=dt)

The data of the resulting array will not be byteswapped,
but will be interpreted correctly.

Examples
--------
>>> s = 'hello world'
>>> np.frombuffer(s, dtype='S1', count=5, offset=6)
array(['w', 'o', 'r', 'l', 'd'],
dtype='|S1')


>>> from numpy import *
>>> buffer = "\x00\x00\x00\x00\x00\x00\xf0?\x00\x00\x00\x00\x00\x00\x00@\x00\x00\x00\x00\x00\x00\x08\
... @\x00\x00\x00\x00\x00\x00\x10@\x00\x00\x00\x00\x00\x00\x14@\x00\x00\x00\x00\x00\x00\x18@"
>>> a = frombuffer(buffer, complex128)
>>> a
array([ 1.+2.j,  3.+4.j,  5.+6.j])


### fromfile()

numpy.fromfile(...)

fromfile(file, dtype=float, count=-1, sep='')

Construct an array from data in a text or binary file.

A highly efficient way of reading binary data with a known data-type,
as well as parsing simply formatted text files.  Data written using the
tofile method can be read using this function.

Parameters
----------
file : file or string
Open file object or filename.
dtype : data-type
Data type of the returned array.
For binary files, it is used to determine the size and byte-order
of the items in the file.
count : int
Number of items to read. -1 means all items (i.e., the complete
file).
sep : string
Separator between items if file is a text file.
Empty ("") separator means the file should be treated as binary.
Spaces (" ") in the separator match zero or more whitespace characters.
A separator consisting only of spaces must match at least one
whitespace.

--------
ndarray.tofile

Notes
-----
Do not rely on the combination of tofile and fromfile for
data storage, as the binary files generated are are not platform
independent.  In particular, no byte-order or data-type information is
saved.  Data can be stored in the platform independent .npy format
using save and load instead.

Examples
--------
Construct an ndarray:

>>> dt = np.dtype([('time', [('min', int), ('sec', int)]),
...                ('temp', float)])
>>> x = np.zeros((1,), dtype=dt)
>>> x['time']['min'] = 10; x['temp'] = 98.25
>>> x
array([((10, 0), 98.25)],
dtype=[('time', [('min', '<i4'), ('sec', '<i4')]), ('temp', '<f8')])

Save the raw data to disk:

>>> import os
>>> fname = os.tmpnam()
>>> x.tofile(fname)

Read the raw data from disk:

>>> np.fromfile(fname, dtype=dt)
array([((10, 0), 98.25)],
dtype=[('time', [('min', '<i4'), ('sec', '<i4')]), ('temp', '<f8')])

The recommended way to store and load data:

>>> np.save(fname, x)
array([((10, 0), 98.25)],
dtype=[('time', [('min', '<i4'), ('sec', '<i4')]), ('temp', '<f8')])


numpy.core.records.fromfile(fd, dtype=None, shape=None, offset=0, formats=None, names=None, titles=None, aligned=False, byteorder=None)

Create an array from binary file data

If file is a string then that file is opened, else it is assumed
to be a file object.

>>> from tempfile import TemporaryFile
>>> a = np.empty(10,dtype='f8,i4,a5')
>>> a[5] = (0.5,10,'abcde')
>>>
>>> fd=TemporaryFile()
>>> a = a.newbyteorder('<')
>>> a.tofile(fd)
>>>
>>> fd.seek(0)
>>> r=np.core.records.fromfile(fd, formats='f8,i4,a5', shape=10,
... byteorder='<')
>>> print r[5]
(0.5, 10, 'abcde')
>>> r.shape
(10,)


>>> from numpy import *
>>> y = array([2.,4.,6.,8.])
>>> y.tofile("myfile.dat")                                 # binary format
>>> y.tofile("myfile.txt", sep='\n', format = "%e")        # ascii format, one column, exponential notation
>>> fromfile('myfile.dat', dtype=float)
array([ 2.,  4.,  6.,  8.])
>>> fromfile('myfile.txt', dtype=float, sep='\n')
array([ 2.,  4.,  6.,  8.])


### fromfunction()

numpy.fromfunction(function, shape, **kwargs)

Construct an array by executing a function over each coordinate.

The resulting array therefore has a value fn(x, y, z) at
coordinate (x, y, z).

Parameters
----------
fn : callable
The function is called with N parameters, each of which
represents the coordinates of the array varying along a
specific axis.  For example, if shape were (2, 2), then
the parameters would be two arrays, [[0, 0], [1, 1]] and
[[0, 1], [0, 1]].  fn must be capable of operating on
arrays, and should return a scalar value.
shape : (N,) tuple of ints
Shape of the output array, which also determines the shape of
the coordinate arrays passed to fn.
dtype : data-type, optional
Data-type of the coordinate arrays passed to fn.  By default,
dtype is float.

--------
indices, meshgrid

Notes
-----
Keywords other than shape and dtype are passed to the function.

Examples
--------
>>> np.fromfunction(lambda i, j: i == j, (3, 3), dtype=int)
array([[ True, False, False],
[False,  True, False],
[False, False,  True]], dtype=bool)

>>> np.fromfunction(lambda i, j: i + j, (3, 3), dtype=int)
array([[0, 1, 2],
[1, 2, 3],
[2, 3, 4]])


>>> from numpy import *
>>> def f(i,j):
...     return i**2 + j**2
...
>>> fromfunction(f, (3,3))                       # evaluate functiom for all combinations of indices [0,1,2]x[0,1,2]
array([[0, 1, 4],
[1, 2, 5],
[4, 5, 8]])


### fromiter()

numpy.fromiter(...)

fromiter(iterable, dtype, count=-1)

Create a new 1-dimensional array from an iterable object.

Parameters
----------
iterable : iterable object
An iterable object providing data for the array.
dtype : data-type
The data type of the returned array.
count : int, optional
The number of items to read from iterable. The default is -1,
which means all data is read.

Returns
-------
out : ndarray
The output array.

Notes
-----
Specify count to improve performance.  It allows
fromiter to pre-allocate the output array, instead of
resizing it on demand.

Examples
--------
>>> iterable = (x*x for x in range(5))
>>> np.fromiter(iterable, np.float)
array([  0.,   1.,   4.,   9.,  16.])


>>> from numpy import *
>>> import itertools
>>> mydata = [[55.5, 40],[60.5, 70]]                                              # List of lists
>>> mydescriptor = {'names': ('weight','age'), 'formats': (float32, int32)}       # Descriptor of the data
>>> myiterator = itertools.imap(tuple,mydata)                                     # Clever way of putting list of lists into iterator
# of tuples. E.g.: myiterator.next() == (55.5, 40.)
>>> a = fromiter(myiterator, dtype = mydescriptor)
>>> a
array([(55.5, 40), (60.5, 70)],
dtype=[('weight', '<f4'), ('age', '<i4')])


### frompyfunc()

numpy.frompyfunc(...)

frompyfunc(func, nin, nout) take an arbitrary python function that takes nin objects as input and returns nout objects and return a universal function (ufunc).  This ufunc always returns PyObject arrays


### fromregex()

numpy.fromregex(file, regexp, dtype)

Construct an array from a text file, using regular-expressions parsing.

Array is constructed from all matches of the regular expression
in the file. Groups in the regular expression are converted to fields.

Parameters
----------
file : str or file
File name or file object to read.
regexp : str or regexp
Regular expression used to parse the file.
Groups in the regular expression correspond to fields in the dtype.
dtype : dtype or dtype list
Dtype for the structured array

Examples
--------
>>> f = open('test.dat', 'w')
>>> f.write("1312 foo\n1534  bar\n444   qux")
>>> f.close()
>>> np.fromregex('test.dat', r"(\d+)\s+(...)",
...              [('num', np.int64), ('key', 'S3')])
array([(1312L, 'foo'), (1534L, 'bar'), (444L, 'qux')],
dtype=[('num', '<i8'), ('key', '|S3')])


### fromstring()

numpy.fromstring(...)

fromstring(string, dtype=float, count=-1, sep='')

Return a new 1d array initialized from raw binary or text data in
string.

Parameters
----------
string : str
A string containing the data.
dtype : dtype, optional
The data type of the array. For binary input data, the data must be
in exactly this format.
count : int, optional
Read this number of dtype elements from the data. If this is
negative, then the size will be determined from the length of the
data.
sep : str, optional
If provided and not empty, then the data will be interpreted as
ASCII text with decimal numbers. This argument is interpreted as the
string separating numbers in the data. Extra whitespace between
elements is also ignored.

Returns
-------
arr : array
The constructed array.

Raises
------
ValueError
If the string is not the correct size to satisfy the requested
dtype and count.

Examples
--------
>>> np.fromstring('\x01\x02', dtype=np.uint8)
array([1, 2], dtype=uint8)
>>> np.fromstring('1 2', dtype=int, sep=' ')
array([1, 2])
>>> np.fromstring('1, 2', dtype=int, sep=',')
array([1, 2])
>>> np.fromstring('\x01\x02\x03\x04\x05', dtype=np.uint8, count=3)
array([1, 2, 3], dtype=uint8)

Invalid inputs:

>>> np.fromstring('\x01\x02\x03\x04\x05', dtype=np.int32)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: string size must be a multiple of element size
>>> np.fromstring('\x01\x02', dtype=np.uint8, count=3)
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
ValueError: string is smaller than requested size


### fv()

numpy.fv(rate, nper, pmt, pv, when='end')

Compute the future value.

Parameters
----------
rate : scalar or array_like of shape(M, )
Rate of interest as decimal (not per cent) per period
nper : scalar or array_like of shape(M, )
Number of compounding periods
pmt : scalar or array_like of shape(M, )
Payment
pv : scalar or array_like of shape(M, )
Present value
when : {{'begin', 1}, {'end', 0}}, {string, int}, optional
When payments are due ('begin' (1) or 'end' (0)).
Defaults to {'end', 0}.

Returns
-------
out : ndarray
Future values.  If all input is scalar, returns a scalar float.  If
any input is array_like, returns future values for each input element.
If multiple inputs are array_like, they all must have the same shape.

Notes
-----
The future value is computed by solving the equation::

fv +
pv*(1+rate)**nper +
pmt*(1 + rate*when)/rate*((1 + rate)**nper - 1) == 0

or, when rate == 0::

fv + pv + pmt * nper == 0

Examples
--------
What is the future value after 10 years of saving $100 now, with an additional monthly savings of$100.  Assume the interest rate is
5% (annually) compounded monthly?

>>> np.fv(0.05/12, 10*12, -100, -100)
15692.928894335748

By convention, the negative sign represents cash flow out (i.e. money not
available today).  Thus, saving $100 a month at 5% annual interest leads to$15,692.93 available to spend in 10 years.

If any input is array_like, returns an array of equal shape.  Let's
compare different interest rates from the example above.

>>> a = np.array((0.05, 0.06, 0.07))/12
>>> np.fv(a, 10*12, -100, -100)
array([ 15692.92889434,  16569.87435405,  17509.44688102])


### generic()

numpy.generic(...)

>>> from numpy import *
>>> numpyscalar = string_('7')            # Convert to numpy scalar
>>> numpyscalar                           # Looks like a build-in scalar...
'7'
>>> type(numpyscalar)                     # ... but it isn't
<type 'numpy.string_'>
>>> buildinscalar = '7'                   # Build-in python scalar
>>> type(buildinscalar)
<type 'str'>
>>> isinstance(numpyscalar, generic)      # Check if scalar is a NumPy one
True
>>> isinstance(buildinscalar, generic)    # Example on how to recognize NumPy scalars
False


### get_array_wrap()

numpy.get_array_wrap(*args)

Find the wrapper for the array with the highest priority.

In case of ties, leftmost wins. If no wrapper is found, return None


### get_include()

numpy.get_include()

Return the directory that contains the numpy \*.h header files.

Extension modules that need to compile against numpy should use this
function to locate the appropriate include directory.

Notes
-----
When using distutils, for example in setup.py.
::

import numpy as np
...
Extension('extension_name', ...
include_dirs=[np.get_include()])
...


### get_numarray_include()

numpy.get_numarray_include(type=None)

Return the directory that contains the numarray \*.h header files.

Extension modules that need to compile against numarray should use this
function to locate the appropriate include directory.

Notes
-----
When using distutils, for example in setup.py.
::

import numpy as np
...
Extension('extension_name', ...
include_dirs=[np.get_numarray_include()])
...


### get_numpy_include()

numpy.get_numpy_include(*args, **kwds)

get_numpy_include is DEPRECATED!! -- use get_include instead

Return the directory that contains the numpy \*.h header files.

Extension modules that need to compile against numpy should use this
function to locate the appropriate include directory.

Notes
-----
When using distutils, for example in setup.py.
::

import numpy as np
...
Extension('extension_name', ...
include_dirs=[np.get_include()])
...


### get_printoptions()

numpy.get_printoptions()

Return the current print options.

Returns
-------
print_opts : dict
Dictionary of current print options with keys

- precision : int
- threshold : int
- edgeitems : int
- linewidth : int
- suppress : bool
- nanstr : string
- infstr : string

--------
set_printoptions : parameter descriptions


### getbuffer()

numpy.getbuffer(...)

getbuffer(obj [,offset[, size]])

Create a buffer object from the given object referencing a slice of
length size starting at offset.  Default is the entire buffer. A


### getbufsize()

numpy.getbufsize()

Return the size of the buffer used in ufuncs.


### geterr()

numpy.geterr()

Get the current way of handling floating-point errors.

Returns a dictionary with entries "divide", "over", "under", and
"invalid", whose values are from the strings
"ignore", "print", "log", "warn", "raise", and "call".


### geterrcall()

numpy.geterrcall()

Return the current callback function used on floating-point errors.


### geterrobj()

numpy.geterrobj(...)

geterrobj()

Used internally by geterr.

Returns
-------
errobj : list
Internal numpy buffer size, error mask, error callback function.


### getfield()

ndarray.getfield(...)

a.getfield(dtype, offset)

Returns a field of the given array as a certain type. A field is a view of
the array data with each itemsize determined by the given type and the
offset into the current array.


Return the gradient of an N-dimensional array.

The gradient is computed using central differences in the interior
and first differences at the boundaries. The returned gradient hence has
the same shape as the input array.

Parameters
----------
f : array_like
An N-dimensional array containing samples of a scalar function.
*varargs : scalars
0, 1, or N scalars specifying the sample distances in each direction,
that is: dx, dy, dz, ... The default distance is 1.

Returns
-------
g : ndarray
N arrays of the same shape as f giving the derivative of f with
respect to each dimension.

Examples
--------
[array([[ 2.,  3.],
[ 2.,  3.]]),
array([[ 0.,  0.],
[ 1.,  1.]])]


### greater()

numpy.greater(...)

y = greater(x1,x2)

Return (x1 > x2) element-wise.

Parameters
----------
x1, x2 : array_like
Input arrays.

Returns
-------
Out : {ndarray, bool}
Output array of bools, or a single bool if x1 and x2 are scalars.

--------
greater_equal

Examples
--------
>>> np.greater([4,2],[2,2])
array([ True, False], dtype=bool)

If the inputs are ndarrays, then np.greater is equivalent to '>'.

>>> a = np.array([4,2])
>>> b = np.array([2,2])
>>> a > b
array([ True, False], dtype=bool)


### greater_equal()

numpy.greater_equal(...)

y = greater_equal(x1,x2)

Element-wise True if first array is greater or equal than second array.

Parameters
----------
x1, x2 : array_like
Input arrays.

Returns
-------
out : ndarray, bool
Output array.

--------
greater, less, less_equal, equal

Examples
--------
>>> np.greater_equal([4,2],[2,2])
array([ True, True], dtype=bool)


### gumbel()

numpy.random.gumbel(...)

gumbel(loc=0.0, scale=1.0, size=None)

Gumbel distribution.

Draw samples from a Gumbel distribution with specified location (or mean)
and scale (or standard deviation).

The Gumbel (or Smallest Extreme Value (SEV) or the Smallest Extreme Value
Type I) distribution is one of a class of Generalized Extreme Value (GEV)
distributions used in modeling extreme value problems.  The Gumbel is a
special case of the Extreme Value Type I distribution for maximums from
distributions with "exponential-like" tails, it may be derived by
considering a Gaussian process of measurements, and generating the pdf for
the maximum values from that set of measurements (see examples).

Parameters
----------
loc : float
The location of the mode of the distribution.
scale : float
The scale parameter of the distribution.
size : tuple of ints
Output shape.  If the given shape is, e.g., (m, n, k), then
m * n * k samples are drawn.

--------
scipy.stats.gumbel : probability density function,
distribution or cumulative density function, etc.
weibull, scipy.stats.genextreme

Notes
-----
The probability density for the Gumbel distribution is

.. math:: p(x) = \frac{e^{-(x - \mu)/ \beta}}{\beta} e^{ -e^{-(x - \mu)/
\beta}},

where :math:\mu is the mode, a location parameter, and :math:\beta
is the scale parameter.

The Gumbel (named for German mathematician Emil Julius Gumbel) was used
very early in the hydrology literature, for modeling the occurrence of
flood events. It is also used for modeling maximum wind speed and rainfall
rates.  It is a "fat-tailed" distribution - the probability of an event in
the tail of the distribution is larger than if one used a Gaussian, hence
the surprisingly frequent occurrence of 100-year floods. Floods were
initially modeled as a Gaussian process, which underestimated the frequency
of extreme events.

It is one of a class of extreme value distributions, the Generalized
Extreme Value (GEV) distributions, which also includes the Weibull and
Frechet.

The function has a mean of :math:\mu + 0.57721\beta and a variance of
:math:\frac{\pi^2}{6}\beta^2.

References
----------
.. [1] Gumbel, E.J. (1958). Statistics of Extremes. Columbia University
Press.
.. [2] Reiss, R.-D. and Thomas M. (2001), Statistical Analysis of Extreme
Values, from Insurance, Finance, Hydrology and Other Fields,
Birkhauser Verlag, Basel: Boston : Berlin.
.. [3] Wikipedia, "Gumbel distribution",
http://en.wikipedia.org/wiki/Gumbel_distribution

Examples
--------
Draw samples from the distribution:

>>> mu, beta = 0, 0.1 # location and scale
>>> s = np.random.gumbel(mu, beta, 1000)

Display the histogram of the samples, along with
the probability density function:

>>> import matplotlib.pyplot as plt
>>> count, bins, ignored = plt.hist(s, 30, normed=True)
>>> plt.plot(bins, (1/beta)*np.exp(-(bins - mu)/beta)
...          * np.exp( -np.exp( -(bins - mu) /beta) ),
...          linewidth=2, color='r')
>>> plt.show()

Show how an extreme value distribution can arise from a Gaussian process
and compare to a Gaussian:

>>> means = []
>>> maxima = []
>>> for i in range(0,1000) :
...    a = np.random.normal(mu, beta, 1000)
...    means.append(a.mean())
...    maxima.append(a.max())
>>> count, bins, ignored = plt.hist(maxima, 30, normed=True)
>>> beta = np.std(maxima)*np.pi/np.sqrt(6)
>>> mu = np.mean(maxima) - 0.57721*beta
>>> plt.plot(bins, (1/beta)*np.exp(-(bins - mu)/beta)
...          * np.exp(-np.exp(-(bins - mu)/beta)),
...          linewidth=2, color='r')
>>> plt.plot(bins, 1/(beta * np.sqrt(2 * np.pi))
...          * np.exp(-(bins - mu)**2 / (2 * beta**2)),
...          linewidth=2, color='g')
>>> plt.show()


>>> from numpy import *
>>> from numpy.random import *
>>> gumbel(loc=0.0,scale=1.0,size=(2,3))        # Gumbel distribution location=0.0, scale=1.0
array([[-1.25923601,  1.68758144,  1.76620507],
[ 1.96820048, -0.21219499,  1.83579566]])
>>> from pylab import *                         # histogram plot example
>>> hist(gumbel(0,1,(1000)), 50)


### hamming()

numpy.hamming(M)

Return the Hamming window.

The Hamming window is a taper formed by using a weighted cosine.

Parameters
----------
M : int
Number of points in the output window. If zero or less, an
empty array is returned.

Returns
-------
out : ndarray
The window, normalized to one (the value one
appears only if the number of samples is odd).

--------
bartlett, blackman, hanning, kaiser

Notes
-----
The Hamming window is defined as

.. math::  w(n) = 0.54 + 0.46cos\left(\frac{2\pi{n}}{M-1}\right)
\qquad 0 \leq n \leq M-1

The Hamming was named for R. W. Hamming, an associate of J. W. Tukey and
is described in Blackman and Tukey. It was recommended for smoothing the
truncated autocovariance function in the time domain.
Most references to the Hamming window come from the signal processing
literature, where it is used as one of many windowing functions for
smoothing values.  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] Blackman, R.B. and Tukey, J.W., (1958) The measurement of power
spectra, Dover Publications, New York.
.. [2] E.R. Kanasewich, "Time Sequence Analysis in Geophysics", The
University of Alberta Press, 1975, pp. 109-110.
.. [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 425.

Examples
--------
>>> from numpy import hamming
>>> hamming(12)
array([ 0.08      ,  0.15302337,  0.34890909,  0.60546483,  0.84123594,
0.98136677,  0.98136677,  0.84123594,  0.60546483,  0.34890909,
0.15302337,  0.08      ])

Plot the window and the frequency response:

>>> from numpy import clip, log10, array, hamming
>>> from scipy.fftpack import fft, fftshift
>>> import matplotlib.pyplot as plt

`