Glossary#

(n,)#

A parenthesized number followed by a comma denotes a tuple with oneelement. The trailing comma distinguishes a one-element tuple from aparenthesizedn.

-1#

• In a dimension entry, instructs NumPy to choose the lengththat will keep the total number of array elements the same.

  >>>np.arange(12).reshape(4,-1).shape(4, 3)

• In an index, any negative valuedenotesindexing from the right.

…#

AnEllipsis.

• When indexing an array, shorthand that the missing axes, if theyexist, are full slices.

  >>>a=np.arange(24).reshape(2,3,4)

  >>>a[...].shape(2, 3, 4)

  >>>a[...,0].shape(2, 3)

  >>>a[0,...].shape(3, 4)

  >>>a[0,...,0].shape(3,)

  It can be used at most once;a[...,0,...] raises anIndexError.

• In printouts, NumPy substitutes... for the middle elements oflarge arrays. To see the entire array, usenumpy.printoptions

:#

The Pythonsliceoperator. In ndarrays, slicing can be applied to everyaxis:

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

Trailing slices can be omitted:

>>>a[1]==a[1,:,:]array([[ True,  True,  True,  True],       [ True,  True,  True,  True],       [ True,  True,  True,  True]])

In contrast to Python, where slicing creates a copy, in NumPy slicingcreates aview.

For details, seeCombining advanced and basic indexing.

<#

In a dtype declaration, indicates that the data islittle-endian (the bracket is big on the right).

>>>dt=np.dtype('<f')# little-endian single-precision float

>#

In a dtype declaration, indicates that the data isbig-endian (the bracket is big on the left).

>>>dt=np.dtype('>H')# big-endian unsigned short

advanced indexing#

Rather than using ascalar or slice asan index, an axis can be indexed with an array, providing fine-grainedselection. This is known asadvanced indexingor “fancy indexing”.

along an axis#

An operationalong axis n of arraya behaves as if its argumentwere an array of slices ofa where each slice has a successiveindex of axisn.

For example, ifa is a 3 xN array, an operation along axis 0behaves as if its argument were an array containing slices of each row:

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

To make it concrete, we can pick the operation to be the array-reversalfunctionnumpy.flip, which accepts anaxis argument. Weconstruct a 3 x 4 arraya:

>>>a=np.arange(12).reshape(3,4)>>>aarray([[ 0,  1,  2,  3],       [ 4,  5,  6,  7],       [ 8,  9, 10, 11]])

Reversing along axis 0 (the row axis) yields

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

Recalling the definition ofalong an axis,flip along axis 0 istreating its argument as if it were

>>>np.array((a[0,:],a[1,:],a[2,:]))array([[ 0,  1,  2,  3],       [ 4,  5,  6,  7],       [ 8,  9, 10, 11]])

and the result ofnp.flip(a,axis=0) is to reverse the slices:

>>>np.array((a[2,:],a[1,:],a[0,:]))array([[ 8,  9, 10, 11],       [ 4,  5,  6,  7],       [ 0,  1,  2,  3]])

array#

Used synonymously in the NumPy docs withndarray.

array_like#

Anyscalar orsequencethat can be interpreted as an ndarray. In addition to ndarraysand scalars this category includes lists (possibly nested and withdifferent element types) and tuples. Any argument accepted bynumpy.arrayis array_like.

>>>a=np.array([[1,2.0],[0,0],(1+1j,3.)])>>>aarray([[1.+0.j, 2.+0.j],       [0.+0.j, 0.+0.j],       [1.+1.j, 3.+0.j]])

array scalar#

Anarray scalar is an instance of the types/classes float32, float64,etc.. For uniformity in handling operands, NumPy treats a scalar asan array of zero dimension. In contrast, a 0-dimensional array is anndarray instancecontaining precisely one value.

axis#

Another term for an array dimension. Axes are numbered left to right;axis 0 is the first element in the shape tuple.

In a two-dimensional vector, the elements of axis 0 are rows and theelements of axis 1 are columns.

In higher dimensions, the picture changes. NumPy printshigher-dimensional vectors as replications of row-by-column buildingblocks, as in this three-dimensional vector:

>>>a=np.arange(12).reshape(2,2,3)>>>aarray([[[ 0,  1,  2],        [ 3,  4,  5]],       [[ 6,  7,  8],        [ 9, 10, 11]]])

a is depicted as a two-element array whose elements are 2x3 vectors.From this point of view, rows and columns are the final two axes,respectively, in any shape.

This rule helps you anticipate how a vector will be printed, andconversely how to find the index of any of the printed elements. Forinstance, in the example, the last two values of 8’s index must be 0 and2. Since 8 appears in the second of the two 2x3’s, the first index mustbe 1:

>>>a[1,0,2]8

A convenient way to count dimensions in a printed vector is tocount[ symbols after the open-parenthesis. This isuseful in distinguishing, say, a (1,2,3) shape from a (2,3) shape:

>>>a=np.arange(6).reshape(2,3)>>>a.ndim2>>>aarray([[0, 1, 2],       [3, 4, 5]])

>>>a=np.arange(6).reshape(1,2,3)>>>a.ndim3>>>aarray([[[0, 1, 2],        [3, 4, 5]]])

.base#

If an array does not own its memory, then itsbase attribute returnsthe object whose memory the array is referencing. That object may bereferencing the memory from still another object, so the owning objectmay bea.base.base.base.... Some writers erroneously claim thattestingbase determines if arrays areviews. For thecorrect way, seenumpy.shares_memory.

big-endian#

SeeEndianness.

BLAS#

Basic Linear Algebra Subprograms

broadcast#

broadcasting is NumPy’s ability to process ndarrays ofdifferent sizes as if all were the same size.

It permits an elegant do-what-I-mean behavior where, for instance,adding a scalar to a vector adds the scalar value to every element.

>>>a=np.arange(3)>>>aarray([0, 1, 2])

>>>a+[3,3,3]array([3, 4, 5])

>>>a+3array([3, 4, 5])

Ordinarily, vector operands must all be the same size, because NumPyworks element by element – for instance,c=a*b is

c[0,0,0]=a[0,0,0]*b[0,0,0]c[0,0,1]=a[0,0,1]*b[0,0,1]...

But in certain useful cases, NumPy can duplicate data along “missing”axes or “too-short” dimensions so shapes will match. The duplicationcosts no memory or time. For details, seeBroadcasting.

C order#

Same asrow-major.

casting#

The process of converting array data from one dtype to another. Thereexist several casting modes, defined by the following casting rules:

• no: The data types should not be cast at all.Any mismatch in data types between the arrays will raise aTypeError.

• equiv: Only byte-order changes are allowed.

• safe: Only casts that can preserve values are allowed. Upcasting(e.g., from int to float) is allowed, but downcasting is not.

• same_kind: The ‘same_kind’ casting option allows safe casts andcasts within a kind, like float64 to float32.

• unsafe: any data conversions may be done.

column-major#

SeeRow- and column-major order.

contiguous#

An array is contiguous if:

• it occupies an unbroken block of memory, and

• array elements with higher indexes occupy higher addresses (thatis, nostride is negative).

There are two types of proper-contiguous NumPy arrays:

• Fortran-contiguous arrays refer to data that is stored column-wise,i.e. the indexing of data as stored in memory starts from thelowest dimension;

• C-contiguous, or simply contiguous arrays, refer to data that isstored row-wise, i.e. the indexing of data as stored in memorystarts from the highest dimension.

For one-dimensional arrays these notions coincide.

For example, a 2x2 arrayA is Fortran-contiguous if its elements arestored in memory in the following order:

A[0,0]A[1,0]A[0,1]A[1,1]

and C-contiguous if the order is as follows:

A[0,0]A[0,1]A[1,0]A[1,1]

To test whether an array is C-contiguous, use the.flags.c_contiguousattribute of NumPy arrays. To test for Fortran contiguity, use the.flags.f_contiguous attribute.

copy#

Seeview.

dimension#

Seeaxis.

dtype#

The datatype describing the (identically typed) elements in an ndarray.It can be changed to reinterpret the array contents. For details, seeData type objects (dtype).

fancy indexing#

Another term foradvanced indexing.

field#

In astructured data type, each subtype is called afield.Thefield has a name (a string), a type (any valid dtype), andan optionaltitle. SeeData type objects (dtype).

Fortran order#

Same ascolumn-major.

flattened#

Seeravel.

homogeneous#

All elements of a homogeneous array have the same type. ndarrays, incontrast to Python lists, are homogeneous. The type can be complicated,as in astructured array, but all elements have that type.

NumPyobject arrays, which contain references toPython objects, fill the role of heterogeneous arrays.

itemsize#

The size of the dtype element in bytes.

little-endian#

SeeEndianness.

mask#

A boolean array used to select only certain elements for an operation:

>>>x=np.arange(5)>>>xarray([0, 1, 2, 3, 4])

>>>mask=(x>2)>>>maskarray([False, False, False, True,  True])

>>>x[mask]=-1>>>xarray([ 0,  1,  2,  -1, -1])

masked array#

Bad or missing data can be cleanly ignored by putting it in a maskedarray, which has an internal boolean array indicating invalidentries. Operations with masked arrays ignore these entries.

>>>a=np.ma.masked_array([np.nan,2,np.nan],[True,False,True])>>>amasked_array(data=[--, 2.0, --],             mask=[ True, False,  True],       fill_value=1e+20)>>>a+[1,2,3]masked_array(data=[--, 4.0, --],             mask=[ True, False,  True],       fill_value=1e+20)

For details, seeMasked arrays.

matrix#

NumPy’s two-dimensionalmatrix classshould no longer be used; use regular ndarrays.

ndarray#

NumPy’s basic structure.

object array#

An array whose dtype isobject; that is, it contains references toPython objects. Indexing the array dereferences the Python objects, sounlike other ndarrays, an object array has the ability to holdheterogeneous objects.

ravel#

numpy.ravelandnumpy.flattenboth flatten an ndarray.ravel will return a view if possible;flatten always returns a copy.

Flattening collapses a multidimensional array to a single dimension;details of how this is done (for instance, whethera[n+1] should bethe next row or next column) are parameters.

record array#

Astructured array with allowing access in an attribute style(a.field) in addition toa['field']. For details, seenumpy.recarray.

row-major#

SeeRow- and column-major order.NumPy creates arrays in row-major order by default.

scalar#

In NumPy, usually a synonym forarray scalar.

shape#

A tuple showing the length of each dimension of an ndarray. Thelength of the tuple itself is the number of dimensions(numpy.ndim).The product of the tuple elements is the number of elements in thearray. For details, seenumpy.ndarray.shape.

stride#

Physical memory is one-dimensional; strides provide a mechanism to mapa given index to an address in memory. For an N-dimensional array, itsstrides attribute is an N-element tuple; advancing from indexi to indexi+1 on axisn means addinga.strides[n] bytesto the address.

Strides are computed automatically from an array’s dtype andshape, but can be directly specified usingas_strided.

For details, seenumpy.ndarray.strides.

To see how striding underlies the power of NumPy views, seeThe NumPy array: a structure for efficient numerical computation.

structured array#

Array whosedtype is astructured data type.

structured data type#

Users can create arbitrarily complexdtypesthat can include other arrays and dtypes. These composite dtypes are calledstructured data types.

subarray#

An array nested in astructured data type, asb is here:

>>>dt=np.dtype([('a',np.int32),('b',np.float32,(3,))])>>>np.zeros(3,dtype=dt)array([(0, [0., 0., 0.]), (0, [0., 0., 0.]), (0, [0., 0., 0.])],      dtype=[('a', '<i4'), ('b', '<f4', (3,))])

subarray data type#

An element of a structured datatype that behaves like an ndarray.

title#

An alias for a field name in a structured datatype.

type#

In NumPy, usually a synonym fordtype. For the more generalPython meaning,see here.

ufunc#

NumPy’s fast element-by-element computation (vectorization)gives a choice which function gets applied. The general term for thefunction isufunc, short foruniversalfunction. NumPy routineshave built-in ufuncs, but users can alsowrite their own.

vectorization#

NumPy hands off array processing to C, where looping and computation aremuch faster than in Python. To exploit this, programmers using NumPyeliminate Python loops in favor of array-to-array operations.vectorization can refer both to the C offloading and tostructuring NumPy code to leverage it.

view#

Without touching underlying data, NumPy can make one array appearto change its datatype and shape.

An array created this way is aview, and NumPy often exploits theperformance gain of using a view versus making a new array.

A potential drawback is that writing to a view can alter the originalas well. If this is a problem, NumPy instead needs to create aphysically distinct array – acopy.

Some NumPy routines always return views, some always return copies, somemay return one or the other, and for some the choice can be specified.Responsibility for managing views and copies falls to the programmer.numpy.shares_memory will check whetherb is a view ofa, but an exact answer isn’t always feasible, as the documentationpage explains.

>>>x=np.arange(5)>>>xarray([0, 1, 2, 3, 4])

>>>y=x[::2]>>>yarray([0, 2, 4])

>>>x[0]=3# changing x changes y as well, since y is a view on x>>>yarray([3, 2, 4])