Structured arrays are ndarrays whose datatype is a composition of simplerdatatypes organized as a sequence of namedfields. For example,
>>>x=np.array([('Rex',9,81.0),('Fido',3,27.0)],...dtype=[('name','U10'),('age','i4'),('weight','f4')])>>>xarray([('Rex', 9, 81.0), ('Fido', 3, 27.0)], dtype=[('name', 'S10'), ('age', '<i4'), ('weight', '<f4')])
Herex is a one-dimensional array of length two whose datatype is astructure with three fields: 1. A string of length 10 or less named ‘name’, 2.a 32-bit integer named ‘age’, and 3. a 32-bit float named ‘weight’.
If you indexx at position 1 you get a structure:
>>>x[1]('Fido', 3, 27.0)
You can access and modify individual fields of a structured array by indexingwith the field name:
>>>x['age']array([9, 3], dtype=int32)>>>x['age']=5>>>xarray([('Rex', 5, 81.0), ('Fido', 5, 27.0)], dtype=[('name', 'S10'), ('age', '<i4'), ('weight', '<f4')])
Structured arrays are designed for low-level manipulation of structured data,for example, for interpreting binary blobs. Structured datatypes aredesigned to mimic ‘structs’ in the C language, making them also useful forinterfacing with C code. For these purposes, numpy supports specializedfeatures such as subarrays and nested datatypes, and allows manual control overthe memory layout of the structure.
For simple manipulation of tabular data other pydata projects, such as pandas,xarray, or DataArray, provide higher-level interfaces that may be moresuitable. These projects may also give better performance for tabular dataanalysis because the C-struct-like memory layout of structured arrays can leadto poor cache behavior.
To use structured arrays one first needs to define a structured datatype.
A structured datatype can be thought of as a sequence of bytes of a certainlength (the structure’sitemsize) which is interpreted as a collectionof fields. Each field has a name, a datatype, and a byte offset within thestructure. The datatype of a field may be any numpy datatype including otherstructured datatypes, and it may also be asub-array which behaves likean ndarray of a specified shape. The offsets of the fields are arbitrary, andfields may even overlap. These offsets are usually determined automatically bynumpy, but can also be specified.
Structured datatypes may be created using the functionnumpy.dtype.There are 4 alternative forms of specification which vary in flexibility andconciseness. These are further documented in theData Type Objects reference page, and insummary they are:
A list of tuples, one tuple per field
Each tuple has the form(fieldname,datatype,shape) where shape isoptional.fieldname is a string (or tuple if titles are used, seeField Titles below),datatype may be any objectconvertible to a datatype, andshape is a tuple of integers specifyingsubarray shape.
>>>np.dtype([('x','f4'),('y',np.float32),('z','f4',(2,2))])dtype=[('x', '<f4'), ('y', '<f4'), ('z', '<f4', (2, 2))])
Iffieldname is the empty string'', the field will be given adefault name of the formf#, where# is the integer index of thefield, counting from 0 from the left:
>>>np.dtype([('x','f4'),('','i4'),('z','i8')])dtype([('x', '<f4'), ('f1', '<i4'), ('z', '<i8')])
The byte offsets of the fields within the structure and the totalstructure itemsize are determined automatically.
A string of comma-separated dtype specifications
In this shorthand notation any of thestring dtype specifications may be used in a string and separated bycommas. The itemsize and byte offsets of the fields are determinedautomatically, and the field names are given the default namesf0,f1, etc.
>>>np.dtype('i8,f4,S3')dtype([('f0', '<i8'), ('f1', '<f4'), ('f2', 'S3')])>>>np.dtype('3int8, float32, (2,3)float64')dtype([('f0', 'i1', 3), ('f1', '<f4'), ('f2', '<f8', (2, 3))])
A dictionary of field parameter arrays
This is the most flexible form of specification since it allows controlover the byte-offsets of the fields and the itemsize of the structure.
The dictionary has two required keys, ‘names’ and ‘formats’, and fouroptional keys, ‘offsets’, ‘itemsize’, ‘aligned’ and ‘titles’. The valuesfor ‘names’ and ‘formats’ should respectively be a list of field names anda list of dtype specifications, of the same length. The optional ‘offsets’value should be a list of integer byte-offsets, one for each field withinthe structure. If ‘offsets’ is not given the offsets are determinedautomatically. The optional ‘itemsize’ value should be an integerdescribing the total size in bytes of the dtype, which must be largeenough to contain all the fields.
>>>np.dtype({'names':['col1','col2'],'formats':['i4','f4']})dtype([('col1', '<i4'), ('col2', '<f4')])>>>np.dtype({'names':['col1','col2'],...'formats':['i4','f4'],...'offsets':[0,4],...'itemsize':12})dtype({'names':['col1','col2'], 'formats':['<i4','<f4'], 'offsets':[0,4], 'itemsize':12})
Offsets may be chosen such that the fields overlap, though this will meanthat assigning to one field may clobber any overlapping field’s data. Asan exception, fields ofnumpy.object type cannot overlap withother fields, because of the risk of clobbering the internal objectpointer and then dereferencing it.
The optional ‘aligned’ value can be set toTrue to make the automaticoffset computation use aligned offsets (seeAutomatic Byte Offsets and Alignment),as if the ‘align’ keyword argument ofnumpy.dtype had been set toTrue.
The optional ‘titles’ value should be a list of titles of the same lengthas ‘names’, seeField Titles below.
A dictionary of field names
The use of this form of specification is discouraged, but documented herebecause older numpy code may use it. The keys of the dictionary are thefield names and the values are tuples specifying type and offset:
>>>np.dtype=({'col1':('i1',0),'col2':('f4',1)})dtype([(('col1'), 'i1'), (('col2'), '>f4')])
This form is discouraged because Python dictionaries do not preserve orderin Python versions before Python 3.6, and the order of the fields in astructured dtype has meaning.Field Titles may bespecified by using a 3-tuple, see below.
The list of field names of a structured datatype can be found in thenamesattribute of the dtype object:
>>>d=np.dtype([('x','i8'),('y','f4')])>>>d.names('x', 'y')
The field names may be modified by assigning to thenames attribute using asequence of strings of the same length.
The dtype object also has a dictionary-like attribute,fields, whose keysare the field names (andField Titles, see below) and whosevalues are tuples containing the dtype and byte offset of each field.
>>>d.fieldsmappingproxy({'x': (dtype('int64'), 0), 'y': (dtype('float32'), 8)})
Both thenames andfields attributes will equalNone forunstructured arrays.
The string representation of a structured datatype is shown in the “list oftuples” form if possible, otherwise numpy falls back to using the more generaldictionary form.
Numpy uses one of two methods to automatically determine the field byte offsetsand the overall itemsize of a structured datatype, depending on whetheralign=True was specified as a keyword argument tonumpy.dtype.
By default (align=False), numpy will pack the fields together such thateach field starts at the byte offset the previous field ended, and the fieldsare contiguous in memory.
>>>defprint_offsets(d):...print("offsets:",[d.fields[name][1]fornameind.names])...print("itemsize:",d.itemsize)>>>print_offsets(np.dtype('u1,u1,i4,u1,i8,u2'))offsets: [0, 1, 2, 6, 7, 15]itemsize: 17
Ifalign=True is set, numpy will pad the structure in the same way many Ccompilers would pad a C-struct. Aligned structures can give a performanceimprovement in some cases, at the cost of increased datatype size. Paddingbytes are inserted between fields such that each field’s byte offset will be amultiple of that field’s alignment, which is usually equal to the field’s sizein bytes for simple datatypes, seePyArray_Descr.alignment. Thestructure will also have trailing padding added so that its itemsize is amultiple of the largest field’s alignment.
>>>print_offsets(np.dtype('u1,u1,i4,u1,i8,u2',align=True))offsets: [0, 1, 4, 8, 16, 24]itemsize: 32
Note that although almost all modern C compilers pad in this way by default,padding in C structs is C-implementation-dependent so this memory layout is notguaranteed to exactly match that of a corresponding struct in a C program. Somework may be needed, either on the numpy side or the C side, to obtain exactcorrespondence.
If offsets were specified using the optionaloffsets key in thedictionary-based dtype specification, settingalign=True will check thateach field’s offset is a multiple of its size and that the itemsize is amultiple of the largest field size, and raise an exception if not.
If the offsets of the fields and itemsize of a structured array satisfy thealignment conditions, the array will have theALIGNEDflag set.
A convenience functionnumpy.lib.recfunctions.repack_fields converts analigned dtype or array to a packed one and vice versa. It takes either a dtypeor structured ndarray as an argument, and returns a copy with fields re-packed,with or without padding bytes.
In addition to field names, fields may also have an associatedtitle,an alternate name, which is sometimes used as an additional description oralias for the field. The title may be used to index an array, just like afield name.
To add titles when using the list-of-tuples form of dtype specification, thefield name may be specified as a tuple of two strings instead of a singlestring, which will be the field’s title and field name respectively. Forexample:
>>>np.dtype([(('my title','name'),'f4')])
When using the first form of dictionary-based specification, the titles may besupplied as an extra'titles' key as described above. When using the second(discouraged) dictionary-based specification, the title can be supplied byproviding a 3-element tuple(datatype,offset,title) instead of the usual2-element tuple:
>>>np.dtype({'name':('i4',0,'my title')})
Thedtype.fields dictionary will containtitles as keys, if anytitles are used. This means effectively that a field with a title will berepresented twice in the fields dictionary. The tuple values for these fieldswill also have a third element, the field title. Because of this, and becausethenames attribute preserves the field order while thefieldsattribute may not, it is recommended to iterate through the fields of a dtypeusing thenames attribute of the dtype, which will not list titles, asin:
>>>fornameind.names:...print(d.fields[name][:2])
Structured datatypes are implemented in numpy to have base typenumpy.void by default, but it is possible to interpret other numpytypes as structured types using the(base_dtype,dtype) form of dtypespecification described inData Type Objects. Here,base_dtype isthe desired underlying dtype, and fields and flags will be copied fromdtype. This dtype is similar to a ‘union’ in C.
There are a number of ways to assign values to a structured array: Using pythontuples, using scalar values, or using other structured arrays.
The simplest way to assign values to a structured array is using python tuples.Each assigned value should be a tuple of length equal to the number of fieldsin the array, and not a list or array as these will trigger numpy’sbroadcasting rules. The tuple’s elements are assigned to the successive fieldsof the array, from left to right:
>>>x=np.array([(1,2,3),(4,5,6)],dtype='i8,f4,f8')>>>x[1]=(7,8,9)>>>xarray([(1, 2., 3.), (7, 8., 9.)], dtype=[('f0', '<i8'), ('f1', '<f4'), ('f2', '<f8')])
A scalar assigned to a structured element will be assigned to all fields. Thishappens when a scalar is assigned to a structured array, or when anunstructured array is assigned to a structured array:
>>>x=np.zeros(2,dtype='i8,f4,?,S1')>>>x[:]=3>>>xarray([(3, 3.0, True, b'3'), (3, 3.0, True, b'3')], dtype=[('f0', '<i8'), ('f1', '<f4'), ('f2', '?'), ('f3', 'S1')])>>>x[:]=np.arange(2)>>>xarray([(0, 0.0, False, b'0'), (1, 1.0, True, b'1')], dtype=[('f0', '<i8'), ('f1', '<f4'), ('f2', '?'), ('f3', 'S1')])
Structured arrays can also be assigned to unstructured arrays, but only if thestructured datatype has just a single field:
>>>twofield=np.zeros(2,dtype=[('A','i4'),('B','i4')])>>>onefield=np.zeros(2,dtype=[('A','i4')])>>>nostruct=np.zeros(2,dtype='i4')>>>nostruct[:]=twofieldValueError: Can't cast from structure to non-structure, except if the structure only has a single field.>>>nostruct[:]=onefield>>>nostructarray([0, 0], dtype=int32)
Assignment between two structured arrays occurs as if the source elements hadbeen converted to tuples and then assigned to the destination elements. Thatis, the first field of the source array is assigned to the first field of thedestination array, and the second field likewise, and so on, regardless offield names. Structured arrays with a different number of fields cannot beassigned to each other. Bytes of the destination structure which are notincluded in any of the fields are unaffected.
>>>a=np.zeros(3,dtype=[('a','i8'),('b','f4'),('c','S3')])>>>b=np.ones(3,dtype=[('x','f4'),('y','S3'),('z','O')])>>>b[:]=a>>>barray([(0.0, b'0.0', b''), (0.0, b'0.0', b''), (0.0, b'0.0', b'')], dtype=[('x', '<f4'), ('y', 'S3'), ('z', 'O')])
When assigning to fields which are subarrays, the assigned value will first bebroadcast to the shape of the subarray.
Individual fields of a structured array may be accessed and modified by indexingthe array with the field name.
>>>x=np.array([(1,2),(3,4)],dtype=[('foo','i8'),('bar','f4')])>>>x['foo']array([1, 3])>>>x['foo']=10>>>xarray([(10, 2.), (10, 4.)], dtype=[('foo', '<i8'), ('bar', '<f4')])
The resulting array is a view into the original array. It shares the samememory locations and writing to the view will modify the original array.
>>>y=x['bar']>>>y[:]=10>>>xarray([(10, 5.), (10, 5.)], dtype=[('foo', '<i8'), ('bar', '<f4')])
This view has the same dtype and itemsize as the indexed field, so it istypically a non-structured array, except in the case of nested structures.
>>>y.dtype,y.shape,y.strides(dtype('float32'), (2,), (12,))
One can index and assign to a structured array with a multi-field index, wherethe index is a list of field names.
Warning
The behavior of multi-field indexes will change from Numpy 1.15 to Numpy1.16.
In Numpy 1.16, the result of indexing with a multi-field index will be a viewinto the original array, as follows:
>>>a=np.zeros(3,dtype=[('a','i4'),('b','i4'),('c','f4')])>>>a[['a','c']]array([(0, 0.), (0, 0.), (0, 0.)], dtype={'names':['a','c'], 'formats':['<i4','<f4'], 'offsets':[0,8], 'itemsize':12})
Assignment to the view modifies the original array. The view’s fields will bein the order they were indexed. Note that unlike for single-field indexing, theview’s dtype has the same itemsize as the original array, and has fields at thesame offsets as in the original array, and unindexed fields are merely missing.
In Numpy 1.15, indexing an array with a multi-field index returns a copy ofthe result above for 1.16, but with fields packed together in memory as ifpassed throughnumpy.lib.recfunctions.repack_fields. This is thebehavior since Numpy 1.7.
Warning
The new behavior in Numpy 1.16 leads to extra “padding” bytes at thelocation of unindexed fields. You will need to update any code which dependson the data having a “packed” layout. For instance code such as:
>>>a[['a','c']].view('i8')# will fail in Numpy 1.16ValueError: When changing to a smaller dtype, its size must be a divisor of the size of original dtype
will need to be changed. This code has raised aFutureWarning sinceNumpy 1.12.
The following is a recommended fix, which will behave identically in Numpy1.15 and Numpy 1.16:
>>>fromnumpy.lib.recfunctionsimportrepack_fields>>>repack_fields(a[['a','c']]).view('i8')# supported 1.15 and 1.16array([0, 0, 0])
Assigning to an array with a multi-field index will behave the same in Numpy1.15 and Numpy 1.16. In both versions the assignment will modify the originalarray:
>>>a[['a','c']]=(2,3)>>>aarray([(2, 0, 3.0), (2, 0, 3.0), (2, 0, 3.0)], dtype=[('a', '<i8'), ('b', '<i4'), ('c', '<f8')])
This obeys the structured array assignment rules described above. For example,this means that one can swap the values of two fields using appropriatemulti-field indexes:
>>>a[['a','c']]=a[['c','a']]
Indexing a single element of a structured array (with an integer index) returnsa structured scalar:
>>>x=np.array([(1,2.,3.)],dtype='i,f,f')>>>scalar=x[0]>>>scalar(1, 2., 3.)>>>type(scalar)numpy.void
Unlike other numpy scalars, structured scalars are mutable and act like viewsinto the original array, such that modifying the scalar will modify theoriginal array. Structured scalars also support access and assignment by fieldname:
>>>x=np.array([(1,2),(3,4)],dtype=[('foo','i8'),('bar','f4')])>>>s=x[0]>>>s['bar']=100>>>xarray([(1, 100.), (3, 4.)], dtype=[('foo', '<i8'), ('bar', '<f4')])
Similarly to tuples, structured scalars can also be indexed with an integer:
>>>scalar=np.array([(1,2.,3.)],dtype='i,f,f')[0]>>>scalar[0]1>>>scalar[1]=4
Thus, tuples might be thought of as the native Python equivalent to numpy’sstructured types, much like native python integers are the equivalent tonumpy’s integer types. Structured scalars may be converted to a tuple bycallingndarray.item:
>>>scalar.item(),type(scalar.item())((1, 2.0, 3.0), tuple)
In order to prevent clobbering object pointers in fields ofnumpy.object type, numpy currently does not allow views of structuredarrays containing objects.
If the dtypes of two void structured arrays are equal, testing the equality ofthe arrays will result in a boolean array with the dimensions of the originalarrays, with elements set toTrue where all fields of the correspondingstructures are equal. Structured dtypes are equal if the field names,dtypes and titles are the same, ignoring endianness, and the fields are inthe same order:
>>>a=np.zeros(2,dtype=[('a','i4'),('b','i4')])>>>b=np.ones(2,dtype=[('a','i4'),('b','i4')])>>>a==barray([False, False])
Currently, if the dtypes of two void structured arrays are not equivalent thecomparison fails, returning the scalar valueFalse. This behavior isdeprecated as of numpy 1.10 and will raise an error or perform elementwisecomparison in the future.
The< and> operators always returnFalse when comparing voidstructured arrays, and arithmetic and bitwise operations are not supported.
As an optional convenience numpy provides an ndarray subclass,numpy.recarray, and associated helper functions in thenumpy.rec submodule, that allows access to fields of structured arraysby attribute instead of only by index. Record arrays also use a specialdatatype,numpy.record, that allows field access by attribute on thestructured scalars obtained from the array.
The simplest way to create a record array is withnumpy.rec.array:
>>>recordarr=np.rec.array([(1,2.,'Hello'),(2,3.,"World")],...dtype=[('foo','i4'),('bar','f4'),('baz','S10')])>>>recordarr.bararray([ 2., 3.], dtype=float32)>>>recordarr[1:2]rec.array([(2, 3.0, 'World')], dtype=[('foo', '<i4'), ('bar', '<f4'), ('baz', 'S10')])>>>recordarr[1:2].fooarray([2], dtype=int32)>>>recordarr.foo[1:2]array([2], dtype=int32)>>>recordarr[1].baz'World'
numpy.rec.array can convert a wide variety of arguments into recordarrays, including structured arrays:
>>>arr=array([(1,2.,'Hello'),(2,3.,"World")],...dtype=[('foo','i4'),('bar','f4'),('baz','S10')])>>>recordarr=np.rec.array(arr)
Thenumpy.rec module provides a number of other convenience functions forcreating record arrays, seerecord array creation routines.
A record array representation of a structured array can be obtained using theappropriateview:
>>>arr=np.array([(1,2.,'Hello'),(2,3.,"World")],...dtype=[('foo','i4'),('bar','f4'),('baz','a10')])>>>recordarr=arr.view(dtype=dtype((np.record,arr.dtype)),...type=np.recarray)
For convenience, viewing an ndarray as typenp.recarray willautomatically convert tonp.record datatype, so the dtype can be leftout of the view:
>>>recordarr=arr.view(np.recarray)>>>recordarr.dtypedtype((numpy.record, [('foo', '<i4'), ('bar', '<f4'), ('baz', 'S10')]))
To get back to a plain ndarray both the dtype and type must be reset. Thefollowing view does so, taking into account the unusual case that therecordarr was not a structured type:
>>>arr2=recordarr.view(recordarr.dtype.fieldsorrecordarr.dtype,np.ndarray)
Record array fields accessed by index or by attribute are returned as a recordarray if the field has a structured type but as a plain ndarray otherwise.
>>>recordarr=np.rec.array([('Hello',(1,2)),("World",(3,4))],...dtype=[('foo','S6'),('bar',[('A',int),('B',int)])])>>>type(recordarr.foo)<type 'numpy.ndarray'>>>>type(recordarr.bar)<class 'numpy.core.records.recarray'>
Note that if a field has the same name as an ndarray attribute, the ndarrayattribute takes precedence. Such fields will be inaccessible by attribute butwill still be accessible by index.
Collection of utilities to manipulate structured arrays.
Most of these functions were initially implemented by John Hunter formatplotlib. They have been rewritten and extended for convenience.
numpy.lib.recfunctions.append_fields(base,names,data,dtypes=None,fill_value=-1,usemask=True,asrecarray=False)[source]¶Add new fields to an existing array.
The names of the fields are given with thenames arguments,the corresponding values with thedata arguments.If a single field is appended,names,data anddtypes do not haveto be lists but just values.
| Parameters: |
|
|---|
numpy.lib.recfunctions.drop_fields(base,drop_names,usemask=True,asrecarray=False)[source]¶Return a new array with fields indrop_names dropped.
Nested fields are supported.
| Parameters: |
|
|---|
Examples
>>>fromnumpy.libimportrecfunctionsasrfn>>>a=np.array([(1,(2,3.0)),(4,(5,6.0))],...dtype=[('a',int),('b',[('ba',float),('bb',int)])])>>>rfn.drop_fields(a,'a')array([((2.0, 3),), ((5.0, 6),)], dtype=[('b', [('ba', '<f8'), ('bb', '<i4')])])>>>rfn.drop_fields(a,'ba')array([(1, (3,)), (4, (6,))], dtype=[('a', '<i4'), ('b', [('bb', '<i4')])])>>>rfn.drop_fields(a,['ba','bb'])array([(1,), (4,)], dtype=[('a', '<i4')])
numpy.lib.recfunctions.find_duplicates(a,key=None,ignoremask=True,return_index=False)[source]¶Find the duplicates in a structured array along a given key
| Parameters: |
|
|---|
Examples
>>>fromnumpy.libimportrecfunctionsasrfn>>>ndtype=[('a',int)]>>>a=np.ma.array([1,1,1,2,2,3,3],...mask=[0,0,1,0,0,0,1]).view(ndtype)>>>rfn.find_duplicates(a,ignoremask=True,return_index=True)...# XXX: judging by the output, the ignoremask flag has no effect
numpy.lib.recfunctions.get_fieldstructure(adtype,lastname=None,parents=None)[source]¶Returns a dictionary with fields indexing lists of their parent fields.
This function is used to simplify access to fields nested in other fields.
| Parameters: |
|
|---|
Examples
>>>fromnumpy.libimportrecfunctionsasrfn>>>ndtype=np.dtype([('A',int),...('B',[('BA',int),...('BB',[('BBA',int),('BBB',int)])])])>>>rfn.get_fieldstructure(ndtype)...# XXX: possible regression, order of BBA and BBB is swapped{'A': [], 'B': [], 'BA': ['B'], 'BB': ['B'], 'BBA': ['B', 'BB'], 'BBB': ['B', 'BB']}
numpy.lib.recfunctions.join_by(key,r1,r2,jointype='inner',r1postfix='1',r2postfix='2',defaults=None,usemask=True,asrecarray=False)[source]¶Join arraysr1 andr2 on keykey.
The key should be either a string or a sequence of string correspondingto the fields used to join the array. An exception is raised if thekey field cannot be found in the two input arrays. Neitherr1 norr2 should have any duplicates alongkey: the presence of duplicateswill make the output quite unreliable. Note that duplicates are notlooked for by the algorithm.
| Parameters: |
|
|---|
Notes
numpy.lib.recfunctions.merge_arrays(seqarrays,fill_value=-1,flatten=False,usemask=False,asrecarray=False)[source]¶Merge arrays field by field.
| Parameters: |
|
|---|
Notes
-1 for integers-1.0 for floating point numbers'-' for characters'-1' for stringsTrue for boolean valuesExamples
>>>fromnumpy.libimportrecfunctionsasrfn>>>rfn.merge_arrays((np.array([1,2]),np.array([10.,20.,30.])))masked_array(data = [(1, 10.0) (2, 20.0) (--, 30.0)], mask = [(False, False) (False, False) (True, False)], fill_value = (999999, 1e+20), dtype = [('f0', '<i4'), ('f1', '<f8')])
>>>rfn.merge_arrays((np.array([1,2]),np.array([10.,20.,30.])),...usemask=False)array([(1, 10.0), (2, 20.0), (-1, 30.0)], dtype=[('f0', '<i4'), ('f1', '<f8')])>>>rfn.merge_arrays((np.array([1,2]).view([('a',int)]),...np.array([10.,20.,30.])),...usemask=False,asrecarray=True)rec.array([(1, 10.0), (2, 20.0), (-1, 30.0)], dtype=[('a', '<i4'), ('f1', '<f8')])
numpy.lib.recfunctions.rec_append_fields(base,names,data,dtypes=None)[source]¶Add new fields to an existing array.
The names of the fields are given with thenames arguments,the corresponding values with thedata arguments.If a single field is appended,names,data anddtypes do not haveto be lists but just values.
| Parameters: |
|
|---|---|
| Returns: |
|
See also
numpy.lib.recfunctions.rec_drop_fields(base,drop_names)[source]¶Returns a new numpy.recarray with fields indrop_names dropped.
numpy.lib.recfunctions.rec_join(key,r1,r2,jointype='inner',r1postfix='1',r2postfix='2',defaults=None)[source]¶Join arraysr1 andr2 on keys.Alternative to join_by, that always returns a np.recarray.
See also
join_bynumpy.lib.recfunctions.recursive_fill_fields(input,output)[source]¶Fills fields from output with fields from input,with support for nested structures.
| Parameters: |
|
|---|
Notes
Examples
>>>fromnumpy.libimportrecfunctionsasrfn>>>a=np.array([(1,10.),(2,20.)],dtype=[('A',int),('B',float)])>>>b=np.zeros((3,),dtype=a.dtype)>>>rfn.recursive_fill_fields(a,b)array([(1, 10.0), (2, 20.0), (0, 0.0)], dtype=[('A', '<i4'), ('B', '<f8')])
numpy.lib.recfunctions.rename_fields(base,namemapper)[source]¶Rename the fields from a flexible-datatype ndarray or recarray.
Nested fields are supported.
| Parameters: |
|
|---|
Examples
>>>fromnumpy.libimportrecfunctionsasrfn>>>a=np.array([(1,(2,[3.0,30.])),(4,(5,[6.0,60.]))],...dtype=[('a',int),('b',[('ba',float),('bb',(float,2))])])>>>rfn.rename_fields(a,{'a':'A','bb':'BB'})array([(1, (2.0, [3.0, 30.0])), (4, (5.0, [6.0, 60.0]))], dtype=[('A', '<i4'), ('b', [('ba', '<f8'), ('BB', '<f8', 2)])])
numpy.lib.recfunctions.stack_arrays(arrays,defaults=None,usemask=True,asrecarray=False,autoconvert=False)[source]¶Superposes arrays fields by fields
| Parameters: |
|
|---|
Examples
>>>fromnumpy.libimportrecfunctionsasrfn>>>x=np.array([1,2,])>>>rfn.stack_arrays(x)isxTrue>>>z=np.array([('A',1),('B',2)],dtype=[('A','|S3'),('B',float)])>>>zz=np.array([('a',10.,100.),('b',20.,200.),('c',30.,300.)],...dtype=[('A','|S3'),('B',float),('C',float)])>>>test=rfn.stack_arrays((z,zz))>>>testmasked_array(data = [('A', 1.0, --) ('B', 2.0, --) ('a', 10.0, 100.0) ('b', 20.0, 200.0) ('c', 30.0, 300.0)], mask = [(False, False, True) (False, False, True) (False, False, False) (False, False, False) (False, False, False)], fill_value = ('N/A', 1e+20, 1e+20), dtype = [('A', '|S3'), ('B', '<f8'), ('C', '<f8')])