Table Of Content

NumPy Reference Release 1.9.1 Written by the NumPy community November02,2014 CONTENTS 1 Arrayobjects 3 1.1 TheN-dimensionalarray(ndarray) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2 Scalars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 1.3 Datatypeobjects(dtype). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 1.4 Indexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98 1.5 IteratingOverArrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 1.6 Standardarraysubclasses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117 1.7 Maskedarrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 1.8 TheArrayInterface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 1.9 DatetimesandTimedeltas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 2 Universalfunctions(ufunc) 413 2.1 Broadcasting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413 2.2 Outputtypedetermination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 2.3 Useofinternalbuffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 2.4 Errorhandling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414 2.5 CastingRules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 2.6 OverridingUfuncbehavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 2.7 ufunc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 2.8 Availableufuncs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429 3 Routines 433 3.1 Arraycreationroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433 3.2 Arraymanipulationroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469 3.3 Binaryoperations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 3.4 Stringoperations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 3.5 C-TypesForeignFunctionInterface(numpy.ctypeslib) . . . . . . . . . . . . . . . . . . . . . . 555 3.6 DatetimeSupportFunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 556 3.7 Datatyperoutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561 3.8 OptionallyScipy-acceleratedroutines(numpy.dual) . . . . . . . . . . . . . . . . . . . . . . . . . 577 3.9 Mathematicalfunctionswithautomaticdomain(numpy.emath) . . . . . . . . . . . . . . . . . . . 578 3.10 Floatingpointerrorhandling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578 3.11 DiscreteFourierTransform(numpy.fft) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 585 3.12 Financialfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608 3.13 Functionalprogramming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 3.14 Numpy-specifichelpfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623 3.15 Indexingroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 3.16 Inputandoutput . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 3.17 Linearalgebra(numpy.linalg) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 681 3.18 Logicfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715 3.19 Maskedarrayoperations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 i 3.20 Mathematicalfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857 3.21 Matrixlibrary(numpy.matlib) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 922 3.22 Miscellaneousroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 928 3.23 PaddingArrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 929 3.24 Polynomials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 933 3.25 Randomsampling(numpy.random) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1108 3.26 Setroutines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1211 3.27 Sorting,searching,andcounting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1216 3.28 Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1232 3.29 TestSupport(numpy.testing) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1260 3.30 Windowfunctions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1273 4 Packaging(numpy.distutils) 1281 4.1 Modulesinnumpy.distutils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1281 4.2 BuildingInstallableClibraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1292 4.3 Conversionof.srcfiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1293 5 NumpyC-API 1295 5.1 PythonTypesandC-Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1295 5.2 Systemconfiguration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1309 5.3 DataTypeAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1311 5.4 ArrayAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1316 5.5 ArrayIteratorAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1355 5.6 UFuncAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1372 5.7 GeneralizedUniversalFunctionAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1378 5.8 Numpycorelibraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1380 5.9 CAPIDeprecations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1386 6 Numpyinternals 1387 6.1 NumpyCCodeExplanations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1387 6.2 Internalorganizationofnumpyarrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1394 6.3 MultidimensionalArrayIndexingOrderIssues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1395 7 NumpyandSWIG 1397 7.1 Numpy.i: aSWIGInterfaceFileforNumPy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397 7.2 Testingthenumpy.iTypemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1412 8 Acknowledgements 1415 Bibliography 1417 PythonModuleIndex 1425 Index 1427 ii NumPyReference,Release1.9.1 Release 1.9 Date November02,2014 Thisreferencemanualdetailsfunctions,modules,andobjectsincludedinNumpy,describingwhattheyareandwhat theydo. ForlearninghowtouseNumPy,seealsouser. CONTENTS 1 NumPyReference,Release1.9.1 2 CONTENTS CHAPTER ONE ARRAY OBJECTS NumPyprovidesanN-dimensionalarraytype,thendarray,whichdescribesacollectionof“items”ofthesametype. TheitemscanbeindexedusingforexampleNintegers. All ndarrays are homogenous: every item takes up the same size block of memory, and all blocks are interpreted in exactlythesameway. Howeachiteminthearrayistobeinterpretedisspecifiedbyaseparatedata-typeobject,one ofwhichisassociatedwitheveryarray. Inadditiontobasictypes(integers,floats,etc.),thedatatypeobjectscanalso representdatastructures. Anitemextractedfromanarray, e.g., byindexing, isrepresentedbyaPythonobjectwhosetypeisoneofthearray scalar types built in Numpy. The array scalars allow easy manipulation of also more complicated arrangements of data. Figure1.1: FigureConceptualdiagramshowingtherelationshipbetweenthethreefundamentalobjectsusedtode- scribethedatainanarray: 1)thendarrayitself,2)thedata-typeobjectthatdescribesthelayoutofasinglefixed-size elementofthearray,3)thearray-scalarPythonobjectthatisreturnedwhenasingleelementofthearrayisaccessed. 1.1 The N-dimensional array (ndarray) An ndarray is a (usually fixed-size) multidimensional container of items of the same type and size. The number of dimensions and items in an array is defined by its shape, which is a tuple of N positive integers that specify thesizesofeachdimension. Thetypeofitemsinthearrayisspecifiedbyaseparatedata-typeobject(dtype),oneof whichisassociatedwitheachndarray. AswithothercontainerobjectsinPython,thecontentsofanndarraycanbeaccessedandmodifiedbyindexingor slicingthearray(using,forexample,N integers),andviathemethodsandattributesofthendarray. 3 NumPyReference,Release1.9.1 Differentndarrayscansharethesamedata,sothatchangesmadeinonendarraymaybevisibleinanother. That is,anndarraycanbea“view”toanotherndarray,andthedataitisreferringtoistakencareofbythe“base”ndarray. ndarrays can also be views to memory owned by Python strings or objects implementing the buffer or array interfaces. Example A2-dimensionalarrayofsize2x3,composedof4-byteintegerelements: >>> x = np.array([[1, 2, 3], [4, 5, 6]], np.int32) >>> type(x) <type ’numpy.ndarray’> >>> x.shape (2, 3) >>> x.dtype dtype(’int32’) ThearraycanbeindexedusingPythoncontainer-likesyntax: >>> x[1,2] # i.e., the element of x in the *second* row, *third* column, namely, 6. Forexampleslicingcanproduceviewsofthearray: >>> y = x[:,1] >>> y array([2, 5]) >>> y[0] = 9 # this also changes the corresponding element in x >>> y array([9, 5]) >>> x array([[1, 9, 3], [4, 5, 6]]) 1.1.1 Constructing arrays NewarrayscanbeconstructedusingtheroutinesdetailedinArraycreationroutines,andalsobyusingthelow-level ndarrayconstructor: ndarray Anarrayobjectrepresentsamultidimensional,homogeneousarrayoffixed-sizeitems. classnumpy.ndarray Anarrayobjectrepresentsamultidimensional,homogeneousarrayoffixed-sizeitems. Anassociateddata-type objectdescribestheformatofeachelementinthearray(itsbyte-order,howmanybytesitoccupiesinmemory, whetheritisaninteger,afloatingpointnumber,orsomethingelse,etc.) Arrays should be constructed using array, zeros or empty (refer to the See Also section below). The parametersgivenhererefertoalow-levelmethod(ndarray(...)) forinstantiatinganarray. Formoreinformation,refertothenumpymoduleandexaminethethemethodsandattributesofanarray. Parameters (forthe__new__method;seeNotesbelow): shape: tupleofints Shapeofcreatedarray. 4 Chapter1. Arrayobjects NumPyReference,Release1.9.1 dtype: data-type,optional Anyobjectthatcanbeinterpretedasanumpydatatype. buffer: objectexposingbufferinterface,optional Usedtofillthearraywithdata. offset: int,optional Offsetofarraydatainbuffer. strides: tupleofints,optional Stridesofdatainmemory. order: {‘C’,‘F’},optional Row-majororcolumn-majororder. Seealso: array Constructanarray. zeros Createanarray,eachelementofwhichiszero. empty Createanarray,butleaveitsallocatedmemoryunchanged(i.e.,itcontains“garbage”). dtype Createadata-type. Notes Therearetwomodesofcreatinganarrayusing__new__: 1.IfbufferisNone,thenonlyshape,dtype,andorderareused. 2.Ifbufferisanobjectexposingthebufferinterface,thenallkeywordsareinterpreted. No__init__methodisneededbecausethearrayisfullyinitializedafterthe__new__method. Examples These examples illustrate the low-level ndarray constructor. Refer to the See Also section above for easier waysofconstructinganndarray. Firstmode,bufferisNone: >>> np.ndarray(shape=(2,2), dtype=float, order=’F’) array([[ -1.13698227e+002, 4.25087011e-303], [ 2.88528414e-306, 3.27025015e-309]]) #random Secondmode: >>> np.ndarray((2,), buffer=np.array([1,2,3]), ... offset=np.int_().itemsize, ... dtype=int) # offset = 1*itemsize, i.e. skip first element array([2, 3]) Attributes 1.1. TheN-dimensionalarray(ndarray) 5 NumPyReference,Release1.9.1 T Sameasself.transpose(),exceptthatselfisreturnedifself.ndim<2. data Pythonbufferobjectpointingtothestartofthearray’sdata. dtype Data-typeofthearray’selements. flags Informationaboutthememorylayoutofthearray. flat A1-Diteratoroverthearray. imag Theimaginarypartofthearray. real Therealpartofthearray. size Numberofelementsinthearray. itemsize Lengthofonearrayelementinbytes. nbytes Totalbytesconsumedbytheelementsofthearray. ndim Numberofarraydimensions. shape Tupleofarraydimensions. strides Tupleofbytestostepineachdimensionwhentraversinganarray. ctypes Anobjecttosimplifytheinteractionofthearraywiththectypesmodule. base Baseobjectifmemoryisfromsomeotherobject. ndarray.T Sameasself.transpose(),exceptthatselfisreturnedifself.ndim<2. Examples >>> x = np.array([[1.,2.],[3.,4.]]) >>> x array([[ 1., 2.], [ 3., 4.]]) >>> x.T array([[ 1., 3.], [ 2., 4.]]) >>> x = np.array([1.,2.,3.,4.]) >>> x array([ 1., 2., 3., 4.]) >>> x.T array([ 1., 2., 3., 4.]) ndarray.data Pythonbufferobjectpointingtothestartofthearray’sdata. ndarray.dtype Data-typeofthearray’selements. Parameters None: Returns d: numpydtypeobject Seealso: numpy.dtype Examples >>> x array([[0, 1], [2, 3]]) >>> x.dtype dtype(’int32’) 6 Chapter1. Arrayobjects