numpy.core.rec

module documentation

(source)

Record arrays expose the fields of structured arrays as properties.

Most commonly, ndarrays contain elements of a single type, e.g. floats, integers, bools etc. However, it is possible for elements to be combinations of these using structured types, such as:

>>> a = np.array([(1, 2.0), (1, 2.0)], dtype=[('x', np.int64), ('y', np.float64)])
>>> a
array([(1, 2.), (1, 2.)], dtype=[('x', '<i8'), ('y', '<f8')])

Here, each element consists of two fields: x (and int), and y (a float). This is known as a structured array. The different fields are analogous to columns in a spread-sheet. The different fields can be accessed as one would a dictionary:

>>> a['x']
array([1, 1])

>>> a['y']
array([2., 2.])

Record arrays allow us to access fields as properties:

>>> ar = np.rec.array(a)

>>> ar.x
array([1, 1])

>>> ar.y
array([2., 2.])

Class	`format_parser`	Class to convert formats, names, titles description to a dtype.
Class	`recarray`	Construct an ndarray that allows field access using attributes.
Class	`record`	A data-type scalar that allows field access as attribute lookup.
Function	`array`	Construct a record array from a wide-variety of objects.
Function	`find_duplicate`	Find duplication in a list, return a list of duplicated elements
Function	`fromarrays`	Create a record array from a (flat) list of arrays
Function	`fromfile`	Create an array from binary file data
Function	`fromrecords`	Create a recarray from a list of records in text form.
Function	`fromstring`	Create a record array from binary data
Function	`get_remaining_size`	Undocumented
Function	`_deprecate_shape_0_as_None`	Undocumented
Variable	`_byteorderconv`	Undocumented

@set_module('numpy.rec')
def array(obj, dtype=None, shape=None, offset=0, strides=None, formats=None, names=None, titles=None, aligned=False, byteorder=None, copy=True): (source) ¶

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

A general-purpose record array constructor that dispatches to the appropriate recarray creation function based on the inputs (see Notes).

Notes

If obj is None, then call the ~numpy.recarray constructor. If obj is a string, then call the fromstring constructor. If obj is a list or a tuple, then if the first object is an ~numpy.ndarray, call fromarrays, otherwise call fromrecords. If obj is a ~numpy.recarray, then make a copy of the data in the recarray (if copy=True) and use the new formats, names, and titles. If obj is a file, then call fromfile. Finally, if obj is an ndarray, then return obj.view(recarray), making a copy of the data if copy=True.

Examples

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

>>> np.core.records.array(a)
rec.array([[1, 2, 3],
           [4, 5, 6],
           [7, 8, 9]],
    dtype=int32)

>>> b = [(1, 1), (2, 4), (3, 9)]
>>> c = np.core.records.array(b, formats = ['i2', 'f2'], names = ('x', 'y'))
>>> c
rec.array([(1, 1.0), (2, 4.0), (3, 9.0)],
          dtype=[('x', '<i2'), ('y', '<f2')])

>>> c.x
rec.array([1, 2, 3], dtype=int16)

>>> c.y
rec.array([ 1.0,  4.0,  9.0], dtype=float16)

>>> r = np.rec.array(['abc','def'], names=['col1','col2'])
>>> print(r.col1)
abc

>>> r.col1
array('abc', dtype='<U3')

>>> r.col2
array('def', dtype='<U3')

Parameters
obj:`any`	Input object. See Notes for details on how various input types are treated.
dtype:`data-type`, optional	Valid dtype for array.
shape:`int` or `tuple` of `ints`, optional	Shape of each array.
offset:`int`, optional	Position in the file or buffer to start reading from.
strides:`tuple` of `ints`, optional	Buffer (`buf`) is interpreted according to these strides (strides define how many bytes each array element, row, column, etc. occupy in memory).
formats	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
names	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
titles	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
aligned	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
byteorder	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
copy:`bool`, optional	Whether to copy the input object (True), or to use a reference instead. This option only applies when the input is an ndarray or recarray. Defaults to True.
Returns
`np.recarray`	Record array created from the specified object.

def find_duplicate(list): (source) ¶

Find duplication in a list, return a list of duplicated elements

@set_module('numpy.rec')
def fromarrays(arrayList, dtype=None, shape=None, formats=None, names=None, titles=None, aligned=False, byteorder=None): (source) ¶

Create a record array from a (flat) list of arrays

Examples

>>> 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) # may vary
>>> x1[1]=34
>>> r.a
array([1, 2, 3, 4])

>>> 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],
...     dtype=np.dtype([('a', np.int32), ('b', 'S3'), ('c', np.float32)]))
>>> r
rec.array([(1, b'a', 1.1), (2, b'dd', 2. ), (3, b'xyz', 3. ),
           (4, b'12', 4. )],
          dtype=[('a', '<i4'), ('b', 'S3'), ('c', '<f4')])

Parameters
arrayList:`list` or `tuple`	List of array-like objects (such as lists, tuples, and ndarrays).
dtype:`data-type`, optional	valid dtype for all arrays
shape:`int` or `tuple` of `ints`, optional	Shape of the resulting array. If not provided, inferred from `arrayList[0]`.
formats	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
names	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
titles	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
aligned	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
byteorder	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
Returns
`np.recarray`	Record array consisting of given arrayList columns.

@set_module('numpy.rec')
def fromfile(fd, dtype=None, shape=None, offset=0, formats=None, names=None, titles=None, aligned=False, byteorder=None): (source) ¶

Create an array from binary file data

Examples

>>> 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,)

Parameters
fd:`str` or file type	If file is a string or a path-like object then that file is opened, else it is assumed to be a file object. The file object must support random access (i.e. it must have tell and seek methods).
dtype:`data-type`, optional	valid dtype for all arrays
shape:`int` or `tuple` of `ints`, optional	shape of each array.
offset:`int`, optional	Position in the file to start reading from.
formats	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation
names	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation
titles	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation
aligned	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation
byteorder	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation
Returns
`np.recarray`	record array consisting of data enclosed in file.

@set_module('numpy.rec')
def fromrecords(recList, dtype=None, shape=None, formats=None, names=None, titles=None, aligned=False, byteorder=None): (source) ¶

Create a recarray from a list of records in text form.

Examples

>>> r=np.core.records.fromrecords([(456,'dbe',1.2),(2,'de',1.3)],
... names='col1,col2,col3')
>>> print(r[0])
(456, 'dbe', 1.2)
>>> r.col1
array([456,   2])
>>> r.col2
array(['dbe', 'de'], dtype='<U3')
>>> import pickle
>>> pickle.loads(pickle.dumps(r))
rec.array([(456, 'dbe', 1.2), (  2, 'de', 1.3)],
          dtype=[('col1', '<i8'), ('col2', '<U3'), ('col3', '<f8')])

Parameters
recList:`sequence`	data in the same field may be heterogeneous - they will be promoted to the highest data type.
dtype:`data-type`, optional	valid dtype for all arrays
shape:`int` or `tuple` of `ints`, optional	shape of each array.
formats	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation. If both `formats` and `dtype` are None, then this will auto-detect formats. Use list of tuples rather than list of lists for faster processing.
names	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation. If both `formats` and `dtype` are None, then this will auto-detect formats. Use list of tuples rather than list of lists for faster processing.
titles	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation. If both `formats` and `dtype` are None, then this will auto-detect formats. Use list of tuples rather than list of lists for faster processing.
aligned	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation. If both `formats` and `dtype` are None, then this will auto-detect formats. Use list of tuples rather than list of lists for faster processing.
byteorder	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation. If both `formats` and `dtype` are None, then this will auto-detect formats. Use list of tuples rather than list of lists for faster processing.
Returns
`np.recarray`	record array consisting of given recList rows.

@set_module('numpy.rec')
def fromstring(datastring, dtype=None, shape=None, offset=0, formats=None, names=None, titles=None, aligned=False, byteorder=None): (source) ¶

Create a record array from binary data

Note that despite the name of this function it does not accept str instances.

Parameters
datastring:`bytes-like`	Buffer of binary data
dtype:`data-type`, optional	Valid dtype for all arrays
shape:`int` or `tuple` of `ints`, optional	Shape of each array.
offset:`int`, optional	Position in the buffer to start reading from.
formats	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
names	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
titles	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
aligned	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
byteorder	If `dtype` is `None`, these arguments are passed to `numpy.format_parser` to construct a dtype. See that function for detailed documentation.
Returns
`np.recarray`	Record array view into the data in datastring. This will be readonly if `datastring` is readonly.