NumPy is a collection of extension modules to provide high-performance multidimensional numeric arrays to the Python programming language.

Constructors - Creating an Array Object

The following functions are used to produce a new array.

array(sequence, typecode=None, copy=1)

Creates an array object from the given sequence determining the shape from the structure of the nested python sequence, and the type as the minimal type that will "fit" all the items in the sequence, or from the desired typecode if given.

The typecode should be specfied as a type followed by bits of precision. The following constants are available on most systems: Int8, Int16, Int32, Int64 (on 64-bit processors), Float32, Float64, Complex32, Complex64. You can also use the constants Int, Float, Complex to get the largest version of the given type available on your system. To get an array of heterogeneous python objects, use the code PyObject.

If the copy flag is set, this function will always return a new array with data copied from the source sequence. If it is set to zero, then no copy will be made if the source sequence is already an array object of the appropriate typecode, but instead a new object will be returned which refers to the same memory block as the source sequence.

zeros(shape, typecode=Int)

Will create an array of shape and given typecode filled with zeros. For both this function and for ones, shape is allowed to be either a tuple, or a single integer corresponding to a 1d array shape.

ones(shape, typecode=Int)

Will create an array of shape and given typecode filled with ones.

arrayrange(start=0, stop, step=1, typecode=None)

The same as array(range(start, stop, step), typecode), but much more efficient

fromstring(string, typecode)

Will return the array formed by the binary data given in string of the specified typecode. This is mainly used for reading binary data to and from files, it can also be used to exchange binary data with other modules that use python strings as storage (i.e. PIL).

Note: this function treats the string as a binary array of data. It is not designed for parsing a string of ASCII numbers to produce an array.

Convenience Functions

identity(n)

Will return a n x n identity matrix

indices(shape)

Will return an array of the indices for the given shaped array. The outermost dimension specifies which index, and the other dimensions match those given in shape.

fromfunction(function, shape)

Will return a new array of the given shape where function is called on the indices of the array. function must only use numerical operations and ufuncs on its arguments. This restriction should be relaxed in the future.

arange

This is equivalent to arrayrange

asarray(a, typecode=None)

This is not necessarily a constructor. If its argument is an array of the right type, you get that argument back. If it is anything else, it will be passed to array(a, typecode). This is a handy way in a function of making sure you have an array without doing any unnecessary copying.

Structural Operations on Arrays (or any python sequence)

take(a, indices, axis=0)

Selects the elements of a along the axis indicated by indices. indices is an array of integers, where negative values are considered to be indexing from the end of the axis (just like normal python negative indices).

reshape(a, shape)

Change the shape of a to be given by the new shape. shape is a tuple of the dimensions of the array. One entry in shape is allowed to be -1, and this dimension will be set to whatever value will make the new shape the same total size as the old one. The size of the new array must be exactly equal to the size of the old one. Use resize for changing the size and shape of an array.

resize(a, shape)

Exactly like reshape, except that the new size of a can be anything. This is a less efficient operation that reshape, and can produce strange results if you're not careful.

transpose(a, axes=None)

Will swap the axes of a so that their new order is that given in axes. Negative axes are allowed and are taken as indexing from the end of the list of axes. If axes is not specified, it will be set to range(len(a.shape)).reverse().

repeat(a, repeats, axis=0)

Each element in a is repeated as often as indicated be the corresponding elements in repeats. The length of the result along the given axis is equal to the sum of the elements in repeats. The shape of the result along all other axes is unchanged.

choose(a, (b0, ..., bn))

a is an array of integers between 0 and n. The resulting array will have the same shape as a, with element selected from b0,...,bn as indicating by the value of the corresponding element in a.

concatenate( (a0,...,an), axis=0)

The arrays will be concatenated along the given axis. All arrays must have the same shape along every axis except for the one given. To concatenate arrays along a newly created axis, you can use array((a0,...,an)) so long as all arrays have the same shape.

diagonal(a, k=0)

Returns the entries along the kth diagonal of a (k is an offset from the main diagonal). This is designed for 2d arrays. For larger arrays, it will return the diagonal of each 2d subarray.

The following functions are defined for convenience

ravel(a)

Returns a as a 1d array. Equivalent to reshape(a, (-1,)) .

nonzero(a)

Returns the indices of the elements in a that are nonzero. Only makes sense for 1d arrays.

where(condition, true, false)

The result is shaped like condition and has elements of true and false where condition is respectively true or false.

compress(condition, a, axis=0)

Returns those elements of a corresponding to those elements of condition that are nonzero. Condition must be the same size as the given axis of a. The shape of the result along axis will be equal to the number of nonzero elements in condition. The shape of the result along all other axes will be the same as a.

trace(a, k=0)

Returns the sum of the elements in a along the kth diagonal.

Sorting and searching arrays

sort(a, axis=-1)

Will sort the elements of a along the given axis.

argsort(a, axis=-1)

Will return the indices of the elements of a needed to produce sort(a). ie. take(a, argsort(a)) == sort(a).

searchsorted(a, values)

a must be sorted in ascending order and 1d. This will return the indices of the positions in a where the corresponding values would fit.

argmax(a, axis=-1), argmin(a, axis=-1)

Returns the arguments of the maximum/minimum values of a along the given axis. The returned array will have one less dimension than a.

Methods on array objects

There are very few methods provided for array objects, most of the functionality is instead available as functions. This is done in order to allow these functions to work on arbitrary python sequences. i.e. transpose([[1,2],[3,4]]) works just fine, but [[1,2],[3,4]].transpose() couldn't possibly work. This approach also allows uniformity in interface between functions defined in the base system in C, in python and functions defined on array objects in extensions. All of these methods depend critically on the implementation details of array objects.

a.astype(typecode)

Will return a new array with all the elements of a cast to typecode. Warning: this cast is the straight C cast from one type to another and contains no range checks at all! You can always add you're own range checks if you're concerned.

a.itemsize()

The size in bytes of a single element in a.

a.byteswapped()

Returns a new array containg the same data as a, except its byteswapped. This is useful for exchanging binary data between machines with different byte orders.

a.typecode()

Returns the character used to indicate the type of the elements in a.

a.iscontiguous()

True if a is a contiguous array. array(a) or copy.copy(a) are guaranteed to produce contiguous arrays if needed.

a.tostring()

Returns the binary data contained in a as a python string. If a is discontiguous, this data will still be faked to look as if it came from a contiguous array.

a.tolist()

Returns a as a hierarchical python list. This is useful for passing to functions that explicitly want python lists.

Attributes of Array Objects

Array objects have four attributes, only two of which are likely to be of general usefulness.

a.shape

Returns a tuple of the lengths of a along each of its dimensions. Use len(a.shape) to get the number of dimensions in a. This attribute is settable, and can be used to change the shape of an array. It can only be set to a new shape that will have exactly the same number of elements as the original shape. See the function resize if this is not the desired behavior.

a.flat

This attribute is only available for contiguous arrays. It will return a one-dimensional array of the elements in a.

a.real

This returns the real part of an array. For non-complex arrays, this is exactly equal to the array itself.

a.imaginary

This returns the imaginary part of a complex array, and raises an exception for a real array.

Arithmetic and logical operations

These are the objects contained in umath (and fast_umath). They are callable objects and can be used just like the equivalent functions, in addition they have methods to allow reductions, accumulations, and outer products.

add, subtract, multiply, divide, remainder, power

arccos, arccosh, arcsin, arcsinh, arctan, arctanh, cos, cosh, exp, log, log10, sin, sinh, sqrt, tan, tanh

maximum, minimum, conjugate

equal, not_equal, greater, greater_equal, less, less_equal

logical_and, logical_or, logical_xor, logical_not, boolean_and, boolean_or, boolean_xor, boolean_not

Hopefully these names are all self explanatory!

Ufunc Methods

All of the previously given functions have the following methods

ufunc.reduce(a, axis=0)

Works just like reduce(ufunc, a, [ufunc's identity element]) except you get to choose the axis to perform the reduction along. Note that if the length of a long axis is 0, then the appropriate identity element for the ufunc will be returned.

ufunc.accumulate(a, axis=0)

This is the same as reduce, except that all the intermediate results are kept along the way.

ufunc.outer(a, b)

This will take the outer product of a and b. The new results shape will be the same as a.shape+b.shape (where plus means concatenate, not add!)

ufunc.reduceat(a, indices, axis=0)

This is a weird function, and most people should just ignore it. It will reduce a to each of the given indices so that as new size along the given axis will be the same as the length of indices.

Numerical Functions

dot(a,b)

Will return the dot product of a and b. This is equivalent to matrix multiply for 2d arrays (without the transpose). Somebody who does more linear algebra really needs to do this function right some day!

convolve(a,b,mode=0)

Will return the convolution of a and b. This function is implemented in the standard manner, not using FFT's. It is intended for convolving a large array with a small one. I personally use it for convolving with a gaussian to smooth waveforms. The mode can be set to either 0, 1, or 2.

For modes 1 and 2, the arrays are zero padded on the left and right sides to provide for missing elements.

clip(a, max, min)

Will clip the values in a to lie between max and min.

The following functions are defined for convenience

sum, cumsum, product, cumproduct, alltrue, sometrue

Standard Extensions to the Numeric Extensions

Discrete Fourier Transforms - FFT.py

The underlying code for these functions is an f2c translated and modified version of the FFTPACK routines.

fft(a, n=None, axis=-1)

Will return the n point discrete Fourier transform of a. n defaults to the length of a. This is most efficient for n a power of two. If n is larger than a, then a will be zero-padded to make up the difference. If n is smaller than a, then a will be aliased to reduce its size. This also stores a cache of working memory for different sizes of fft's, so you could theoretically run into memory problems if you call this too many times with too many different n's.

inverse_fft(a, n=None, axis=-1)

Will return the n point inverse discrete Fourier transform of a. n defaults to the length of a. This is most efficient for n a power of two. If n is larger than a, then a will be zero-padded to make up the difference. If n is smaller than a, then a will be aliased to reduce its size. This also stores a cache of working memory for different sizes of fft's, so you could theoretically run into memory problems if you call this too many times with too many different n's.

real_fft(a, n=None, axis=-1)

Will return the n point discrete Fourier transform of the real valued array a. n defaults to the length of a. This is most efficient for n a power of two. The returned array will be one half of the symmetric complex transform of the real array.

fft2d(a, s=None, axes=(-2,-1))

The 2d fft of a.

real_fft2d(a, s=None, axes=(-2,-1))

The 2d fft of the real valued array a.

Random Numbers - RandomArray.py

The underlying code for these routines is from ranlib

seed(x=0,y=0)

Set the seed of the random number generator from two integers. If both are zero, then seed will come from the system clock.

get_seed()

Returns the two integers that are the generators current seed.

random(shape=[])

Returns an array of random numbers uniformly distributed between 0 and 1 of the given shape. Returns a scalar if shape is empty (as in the default).

uniform(minimum, maximum, shape=[])

The random numbers are uniformly distributed between minimum and maximum

randint(minimum=0, maximum, shape=[])

An array of integers between minimum and maximum, not including the value of maximum (as in range).

permutation(n):

A random resorting of the values in arrayrange(n)

Linear Algebra - LinearAlgebra.py

The underlying code for these routines comes from LAPACK

solve_linear_equations(a,b)

inverse(a)

Returns the inverse of the matrix a. matrixmultiply(a, inverse(a)) == identity(len(a))

eigenvalues(a)

Just get the eigenvalues for a

eigenvectors(a)

eigenvectors(a) returns u,v where u is the eigenvalues and

v is a matrix of eigenvectors with vector v[i] corresponds to

eigenvalue u[i]. Satisfies the equation matrixmultiply(a, v[i]) = u[i]*v[i]

singular_value_decomposition(a)

generalized_inverse(a)

determinant(a)

Returns the determinate of the square matrix a

linear_least_squares(a,b,rcond=1.e-10)

solveLinearLeastSquares(a,b) returns x,resids,rank,s

where x minimizes 2-norm(|b - Ax|)

resids is the sum square residuals

rank is the rank of A

s is an rank of the singual values of A in desending order

If b is a matrix then x is also a matrix with corresponding columns.

If the rank of A is less than the number of columns of A or greater than

the numer of rows, then residuals will be returned as an empty array

otherwise resids = sum((b-dot(A,x)**2).

Singular values less than s[0]*rcond are treated as zero.