"""

Collection of utilities to manipulate structured arrays.

Most of these functions were initially implemented by John Hunter for

matplotlib. They have been rewritten and extended for convenience.

"""

import itertools

import numpy as np

import numpy.ma as ma

import numpy.ma.mrecords as mrec

from numpy._core.overrides import array_function_dispatch

from numpy.lib._iotools import _is_string_like

__all__ = [

'append_fields', 'apply_along_fields', 'assign_fields_by_name',

'drop_fields', 'find_duplicates', 'flatten_descr',

'get_fieldstructure', 'get_names', 'get_names_flat',

'join_by', 'merge_arrays', 'rec_append_fields',

'rec_drop_fields', 'rec_join', 'recursive_fill_fields',

'rename_fields', 'repack_fields', 'require_fields',

'stack_arrays', 'structured_to_unstructured', 'unstructured_to_structured',

]

def _recursive_fill_fields_dispatcher(input, output):

return (input, output)

@array_function_dispatch(_recursive_fill_fields_dispatcher)

def recursive_fill_fields(input, output):

"""

Fills fields from output with fields from input,

with support for nested structures.

Parameters

----------

input : ndarray

Input array.

output : ndarray

Output array.

Notes

-----

* `output` should be at least the same size as `input`

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> a = np.array([(1, 10.), (2, 20.)], dtype=[('A', np.int64), ('B', np.float64)])

>>> b = np.zeros((3,), dtype=a.dtype)

>>> rfn.recursive_fill_fields(a, b)

array([(1, 10.), (2, 20.), (0, 0.)], dtype=[('A', '<i8'), ('B', '<f8')])

"""

newdtype = output.dtype

for field in newdtype.names:

try:

current = input[field]

except ValueError:

continue

if current.dtype.names is not None:

recursive_fill_fields(current, output[field])

else:

output[field][:len(current)] = current

return output

def _get_fieldspec(dtype):

"""

Produce a list of name/dtype pairs corresponding to the dtype fields

Similar to dtype.descr, but the second item of each tuple is a dtype, not a

string. As a result, this handles subarray dtypes

Can be passed to the dtype constructor to reconstruct the dtype, noting that

this (deliberately) discards field offsets.

Examples

--------

>>> import numpy as np

>>> dt = np.dtype([(('a', 'A'), np.int64), ('b', np.double, 3)])

>>> dt.descr

[(('a', 'A'), '<i8'), ('b', '<f8', (3,))]

>>> _get_fieldspec(dt)

[(('a', 'A'), dtype('int64')), ('b', dtype(('<f8', (3,))))]

"""

if dtype.names is None:

# .descr returns a nameless field, so we should too

return [('', dtype)]

else:

fields = ((name, dtype.fields[name]) for name in dtype.names)

# keep any titles, if present

return [

(name if len(f) == 2 else (f[2], name), f[0])

for name, f in fields

]

def get_names(adtype):

"""

Returns the field names of the input datatype as a tuple. Input datatype

must have fields otherwise error is raised.

Parameters

----------

adtype : dtype

Input datatype

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> rfn.get_names(np.empty((1,), dtype=[('A', int)]).dtype)

('A',)

>>> rfn.get_names(np.empty((1,), dtype=[('A',int), ('B', float)]).dtype)

('A', 'B')

>>> adtype = np.dtype([('a', int), ('b', [('ba', int), ('bb', int)])])

>>> rfn.get_names(adtype)

('a', ('b', ('ba', 'bb')))

"""

listnames = []

names = adtype.names

for name in names:

current = adtype[name]

if current.names is not None:

listnames.append((name, tuple(get_names(current))))

else:

listnames.append(name)

return tuple(listnames)

def get_names_flat(adtype):

"""

Returns the field names of the input datatype as a tuple. Input datatype

must have fields otherwise error is raised.

Nested structure are flattened beforehand.

Parameters

----------

adtype : dtype

Input datatype

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> rfn.get_names_flat(np.empty((1,), dtype=[('A', int)]).dtype) is None

False

>>> rfn.get_names_flat(np.empty((1,), dtype=[('A',int), ('B', str)]).dtype)

('A', 'B')

>>> adtype = np.dtype([('a', int), ('b', [('ba', int), ('bb', int)])])

>>> rfn.get_names_flat(adtype)

('a', 'b', 'ba', 'bb')

"""

listnames = []

names = adtype.names

for name in names:

listnames.append(name)

current = adtype[name]

if current.names is not None:

listnames.extend(get_names_flat(current))

return tuple(listnames)

def flatten_descr(ndtype):

"""

Flatten a structured data-type description.

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> ndtype = np.dtype([('a', '<i4'), ('b', [('ba', '<f8'), ('bb', '<i4')])])

>>> rfn.flatten_descr(ndtype)

(('a', dtype('int32')), ('ba', dtype('float64')), ('bb', dtype('int32')))

"""

names = ndtype.names

if names is None:

return (('', ndtype),)

else:

descr = []

for field in names:

(typ, _) = ndtype.fields[field]

if typ.names is not None:

descr.extend(flatten_descr(typ))

else:

descr.append((field, typ))

return tuple(descr)

def _zip_dtype(seqarrays, flatten=False):

newdtype = []

if flatten:

for a in seqarrays:

newdtype.extend(flatten_descr(a.dtype))

else:

for a in seqarrays:

current = a.dtype

if current.names is not None and len(current.names) == 1:

# special case - dtypes of 1 field are flattened

newdtype.extend(_get_fieldspec(current))

else:

newdtype.append(('', current))

return np.dtype(newdtype)

def _zip_descr(seqarrays, flatten=False):

"""

Combine the dtype description of a series of arrays.

Parameters

----------

seqarrays : sequence of arrays

Sequence of arrays

flatten : {boolean}, optional

Whether to collapse nested descriptions.

"""

return _zip_dtype(seqarrays, flatten=flatten).descr

def get_fieldstructure(adtype, lastname=None, parents=None,):

"""

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

----------

adtype : np.dtype

Input datatype

lastname : optional

Last processed field name (used internally during recursion).

parents : dictionary

Dictionary of parent fields (used internally during recursion).

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> 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']}

"""

if parents is None:

parents = {}

names = adtype.names

for name in names:

current = adtype[name]

if current.names is not None:

if lastname:

parents[name] = [lastname, ]

else:

parents[name] = []

parents.update(get_fieldstructure(current, name, parents))

else:

lastparent = list(parents.get(lastname, []) or [])

if lastparent:

lastparent.append(lastname)

elif lastname:

lastparent = [lastname, ]

parents[name] = lastparent or []

return parents

def _izip_fields_flat(iterable):

"""

Returns an iterator of concatenated fields from a sequence of arrays,

collapsing any nested structure.

"""

for element in iterable:

if isinstance(element, np.void):

yield from _izip_fields_flat(tuple(element))

else:

yield element

def _izip_fields(iterable):

"""

Returns an iterator of concatenated fields from a sequence of arrays.

"""

for element in iterable:

if (hasattr(element, '__iter__') and

not isinstance(element, str)):

yield from _izip_fields(element)

elif isinstance(element, np.void) and len(tuple(element)) == 1:

# this statement is the same from the previous expression

yield from _izip_fields(element)

else:

yield element

def _izip_records(seqarrays, fill_value=None, flatten=True):

"""

Returns an iterator of concatenated items from a sequence of arrays.

Parameters

----------

seqarrays : sequence of arrays

Sequence of arrays.

fill_value : {None, integer}

Value used to pad shorter iterables.

flatten : {True, False},

Whether to

"""

# Should we flatten the items, or just use a nested approach

if flatten:

zipfunc = _izip_fields_flat

else:

zipfunc = _izip_fields

for tup in itertools.zip_longest(*seqarrays, fillvalue=fill_value):

yield tuple(zipfunc(tup))

def _fix_output(output, usemask=True, asrecarray=False):

"""

Private function: return a recarray, an ndarray, a MaskedArray

or a MaskedRecords depending on the input parameters

"""

if not isinstance(output, ma.MaskedArray):

usemask = False

if usemask:

if asrecarray:

output = output.view(mrec.MaskedRecords)

else:

output = ma.filled(output)

if asrecarray:

output = output.view(np.recarray)

return output

def _fix_defaults(output, defaults=None):

"""

Update the fill_value and masked data of `output`

from the default given in a dictionary defaults.

"""

names = output.dtype.names

(data, mask, fill_value) = (output.data, output.mask, output.fill_value)

for (k, v) in (defaults or {}).items():

if k in names:

fill_value[k] = v

data[k][mask[k]] = v

return output

def _merge_arrays_dispatcher(seqarrays, fill_value=None, flatten=None,

usemask=None, asrecarray=None):

return seqarrays

@array_function_dispatch(_merge_arrays_dispatcher)

def merge_arrays(seqarrays, fill_value=-1, flatten=False,

usemask=False, asrecarray=False):

"""

Merge arrays field by field.

Parameters

----------

seqarrays : sequence of ndarrays

Sequence of arrays

fill_value : {float}, optional

Filling value used to pad missing data on the shorter arrays.

flatten : {False, True}, optional

Whether to collapse nested fields.

usemask : {False, True}, optional

Whether to return a masked array or not.

asrecarray : {False, True}, optional

Whether to return a recarray (MaskedRecords) or not.

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> rfn.merge_arrays((np.array([1, 2]), np.array([10., 20., 30.])))

array([( 1, 10.), ( 2, 20.), (-1, 30.)],

dtype=[('f0', '<i8'), ('f1', '<f8')])

>>> rfn.merge_arrays((np.array([1, 2], dtype=np.int64),

... np.array([10., 20., 30.])), usemask=False)

array([(1, 10.0), (2, 20.0), (-1, 30.0)],

dtype=[('f0', '<i8'), ('f1', '<f8')])

>>> rfn.merge_arrays((np.array([1, 2]).view([('a', np.int64)]),

... np.array([10., 20., 30.])),

... usemask=False, asrecarray=True)

rec.array([( 1, 10.), ( 2, 20.), (-1, 30.)],

dtype=[('a', '<i8'), ('f1', '<f8')])

Notes

-----

* Without a mask, the missing value will be filled with something,

depending on what its corresponding type:

* ``-1`` for integers

* ``-1.0`` for floating point numbers

* ``'-'`` for characters

* ``'-1'`` for strings

* ``True`` for boolean values

* XXX: I just obtained these values empirically

"""

# Only one item in the input sequence ?

if (len(seqarrays) == 1):

seqarrays = np.asanyarray(seqarrays[0])

# Do we have a single ndarray as input ?

if isinstance(seqarrays, (np.ndarray, np.void)):

seqdtype = seqarrays.dtype

# Make sure we have named fields

if seqdtype.names is None:

seqdtype = np.dtype([('', seqdtype)])

if not flatten or _zip_dtype((seqarrays,), flatten=True) == seqdtype:

# Minimal processing needed: just make sure everything's a-ok

seqarrays = seqarrays.ravel()

# Find what type of array we must return

if usemask:

if asrecarray:

seqtype = mrec.MaskedRecords

else:

seqtype = ma.MaskedArray

elif asrecarray:

seqtype = np.recarray

else:

seqtype = np.ndarray

return seqarrays.view(dtype=seqdtype, type=seqtype)

else:

seqarrays = (seqarrays,)

else:

# Make sure we have arrays in the input sequence

seqarrays = [np.asanyarray(_m) for _m in seqarrays]

# Find the sizes of the inputs and their maximum

sizes = tuple(a.size for a in seqarrays)

maxlength = max(sizes)

# Get the dtype of the output (flattening if needed)

newdtype = _zip_dtype(seqarrays, flatten=flatten)

# Initialize the sequences for data and mask

seqdata = []

seqmask = []

# If we expect some kind of MaskedArray, make a special loop.

if usemask:

for (a, n) in zip(seqarrays, sizes):

nbmissing = (maxlength - n)

# Get the data and mask

data = a.ravel().__array__()

mask = ma.getmaskarray(a).ravel()

# Get the filling value (if needed)

if nbmissing:

fval = mrec._check_fill_value(fill_value, a.dtype)

if isinstance(fval, (np.ndarray, np.void)):

if len(fval.dtype) == 1:

fval = fval.item()[0]

fmsk = True

else:

fval = np.array(fval, dtype=a.dtype, ndmin=1)

fmsk = np.ones((1,), dtype=mask.dtype)

else:

fval = None

fmsk = True

# Store an iterator padding the input to the expected length

seqdata.append(itertools.chain(data, [fval] * nbmissing))

seqmask.append(itertools.chain(mask, [fmsk] * nbmissing))

# Create an iterator for the data

data = tuple(_izip_records(seqdata, flatten=flatten))

output = ma.array(np.fromiter(data, dtype=newdtype, count=maxlength),

mask=list(_izip_records(seqmask, flatten=flatten)))

if asrecarray:

output = output.view(mrec.MaskedRecords)

else:

# Same as before, without the mask we don't need...

for (a, n) in zip(seqarrays, sizes):

nbmissing = (maxlength - n)

data = a.ravel().__array__()

if nbmissing:

fval = mrec._check_fill_value(fill_value, a.dtype)

if isinstance(fval, (np.ndarray, np.void)):

if len(fval.dtype) == 1:

fval = fval.item()[0]

else:

fval = np.array(fval, dtype=a.dtype, ndmin=1)

else:

fval = None

seqdata.append(itertools.chain(data, [fval] * nbmissing))

output = np.fromiter(tuple(_izip_records(seqdata, flatten=flatten)),

dtype=newdtype, count=maxlength)

if asrecarray:

output = output.view(np.recarray)

# And we're done...

return output

def _drop_fields_dispatcher(base, drop_names, usemask=None, asrecarray=None):

return (base,)

@array_function_dispatch(_drop_fields_dispatcher)

def drop_fields(base, drop_names, usemask=True, asrecarray=False):

"""

Return a new array with fields in `drop_names` dropped.

Nested fields are supported.

Parameters

----------

base : array

Input array

drop_names : string or sequence

String or sequence of strings corresponding to the names of the

fields to drop.

usemask : {False, True}, optional

Whether to return a masked array or not.

asrecarray : string or sequence, optional

Whether to return a recarray or a mrecarray (`asrecarray=True`) or

a plain ndarray or masked array with flexible dtype. The default

is False.

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> a = np.array([(1, (2, 3.0)), (4, (5, 6.0))],

... dtype=[('a', np.int64), ('b', [('ba', np.double), ('bb', np.int64)])])

>>> rfn.drop_fields(a, 'a')

array([((2., 3),), ((5., 6),)],

dtype=[('b', [('ba', '<f8'), ('bb', '<i8')])])

>>> rfn.drop_fields(a, 'ba')

array([(1, (3,)), (4, (6,))], dtype=[('a', '<i8'), ('b', [('bb', '<i8')])])

>>> rfn.drop_fields(a, ['ba', 'bb'])

array([(1,), (4,)], dtype=[('a', '<i8')])

"""

if _is_string_like(drop_names):

drop_names = [drop_names]

else:

drop_names = set(drop_names)

def _drop_descr(ndtype, drop_names):

names = ndtype.names

newdtype = []

for name in names:

current = ndtype[name]

if name in drop_names:

continue

if current.names is not None:

descr = _drop_descr(current, drop_names)

if descr:

newdtype.append((name, descr))

else:

newdtype.append((name, current))

return newdtype

newdtype = _drop_descr(base.dtype, drop_names)

output = np.empty(base.shape, dtype=newdtype)

output = recursive_fill_fields(base, output)

return _fix_output(output, usemask=usemask, asrecarray=asrecarray)

def _keep_fields(base, keep_names, usemask=True, asrecarray=False):

"""

Return a new array keeping only the fields in `keep_names`,

and preserving the order of those fields.

Parameters

----------

base : array

Input array

keep_names : string or sequence

String or sequence of strings corresponding to the names of the

fields to keep. Order of the names will be preserved.

usemask : {False, True}, optional

Whether to return a masked array or not.

asrecarray : string or sequence, optional

Whether to return a recarray or a mrecarray (`asrecarray=True`) or

a plain ndarray or masked array with flexible dtype. The default

is False.

"""

newdtype = [(n, base.dtype[n]) for n in keep_names]

output = np.empty(base.shape, dtype=newdtype)

output = recursive_fill_fields(base, output)

return _fix_output(output, usemask=usemask, asrecarray=asrecarray)

def _rec_drop_fields_dispatcher(base, drop_names):

return (base,)

@array_function_dispatch(_rec_drop_fields_dispatcher)

def rec_drop_fields(base, drop_names):

"""

Returns a new numpy.recarray with fields in `drop_names` dropped.

"""

return drop_fields(base, drop_names, usemask=False, asrecarray=True)

def _rename_fields_dispatcher(base, namemapper):

return (base,)

@array_function_dispatch(_rename_fields_dispatcher)

def rename_fields(base, namemapper):

"""

Rename the fields from a flexible-datatype ndarray or recarray.

Nested fields are supported.

Parameters

----------

base : ndarray

Input array whose fields must be modified.

namemapper : dictionary

Dictionary mapping old field names to their new version.

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> 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., [ 3., 30.])), (4, (5., [ 6., 60.]))],

dtype=[('A', '<i8'), ('b', [('ba', '<f8'), ('BB', '<f8', (2,))])])

"""

def _recursive_rename_fields(ndtype, namemapper):

newdtype = []

for name in ndtype.names:

newname = namemapper.get(name, name)

current = ndtype[name]

if current.names is not None:

newdtype.append(

(newname, _recursive_rename_fields(current, namemapper))

)

else:

newdtype.append((newname, current))

return newdtype

newdtype = _recursive_rename_fields(base.dtype, namemapper)

return base.view(newdtype)

def _append_fields_dispatcher(base, names, data, dtypes=None,

fill_value=None, usemask=None, asrecarray=None):

yield base

yield from data

@array_function_dispatch(_append_fields_dispatcher)

def append_fields(base, names, data, dtypes=None,

fill_value=-1, usemask=True, asrecarray=False):

"""

Add new fields to an existing array.

The names of the fields are given with the `names` arguments,

the corresponding values with the `data` arguments.

If a single field is appended, `names`, `data` and `dtypes` do not have

to be lists but just values.

Parameters

----------

base : array

Input array to extend.

names : string, sequence

String or sequence of strings corresponding to the names

of the new fields.

data : array or sequence of arrays

Array or sequence of arrays storing the fields to add to the base.

dtypes : sequence of datatypes, optional

Datatype or sequence of datatypes.

If None, the datatypes are estimated from the `data`.

fill_value : {float}, optional

Filling value used to pad missing data on the shorter arrays.

usemask : {False, True}, optional

Whether to return a masked array or not.

asrecarray : {False, True}, optional

Whether to return a recarray (MaskedRecords) or not.

"""

# Check the names

if isinstance(names, (tuple, list)):

if len(names) != len(data):

msg = "The number of arrays does not match the number of names"

raise ValueError(msg)

elif isinstance(names, str):

names = [names, ]

data = [data, ]

#

if dtypes is None:

data = [np.array(a, copy=None, subok=True) for a in data]

data = [a.view([(name, a.dtype)]) for (name, a) in zip(names, data)]

else:

if not isinstance(dtypes, (tuple, list)):

dtypes = [dtypes, ]

if len(data) != len(dtypes):

if len(dtypes) == 1:

dtypes = dtypes * len(data)

else:

msg = "The dtypes argument must be None, a dtype, or a list."

raise ValueError(msg)

data = [np.array(a, copy=None, subok=True, dtype=d).view([(n, d)])

for (a, n, d) in zip(data, names, dtypes)]

#

base = merge_arrays(base, usemask=usemask, fill_value=fill_value)

if len(data) > 1:

data = merge_arrays(data, flatten=True, usemask=usemask,

fill_value=fill_value)

else:

data = data.pop()

#

output = ma.masked_all(

max(len(base), len(data)),

dtype=_get_fieldspec(base.dtype) + _get_fieldspec(data.dtype))

output = recursive_fill_fields(base, output)

output = recursive_fill_fields(data, output)

#

return _fix_output(output, usemask=usemask, asrecarray=asrecarray)

def _rec_append_fields_dispatcher(base, names, data, dtypes=None):

yield base

yield from data

@array_function_dispatch(_rec_append_fields_dispatcher)

def rec_append_fields(base, names, data, dtypes=None):

"""

Add new fields to an existing array.

The names of the fields are given with the `names` arguments,

the corresponding values with the `data` arguments.

If a single field is appended, `names`, `data` and `dtypes` do not have

to be lists but just values.

Parameters

----------

base : array

Input array to extend.

names : string, sequence

String or sequence of strings corresponding to the names

of the new fields.

data : array or sequence of arrays

Array or sequence of arrays storing the fields to add to the base.

dtypes : sequence of datatypes, optional

Datatype or sequence of datatypes.

If None, the datatypes are estimated from the `data`.

See Also

--------

append_fields

Returns

-------

appended_array : np.recarray

"""

return append_fields(base, names, data=data, dtypes=dtypes,

asrecarray=True, usemask=False)

def _repack_fields_dispatcher(a, align=None, recurse=None):

return (a,)

@array_function_dispatch(_repack_fields_dispatcher)

def repack_fields(a, align=False, recurse=False):

"""

Re-pack the fields of a structured array or dtype in memory.

The memory layout of structured datatypes allows fields at arbitrary

byte offsets. This means the fields can be separated by padding bytes,

their offsets can be non-monotonically increasing, and they can overlap.

This method removes any overlaps and reorders the fields in memory so they

have increasing byte offsets, and adds or removes padding bytes depending

on the `align` option, which behaves like the `align` option to

`numpy.dtype`.

If `align=False`, this method produces a "packed" memory layout in which

each field starts at the byte the previous field ended, and any padding

bytes are removed.

If `align=True`, this methods produces an "aligned" memory layout in which

each field's offset is a multiple of its alignment, and the total itemsize

is a multiple of the largest alignment, by adding padding bytes as needed.

Parameters

----------

a : ndarray or dtype

array or dtype for which to repack the fields.

align : boolean

If true, use an "aligned" memory layout, otherwise use a "packed" layout.

recurse : boolean

If True, also repack nested structures.

Returns

-------

repacked : ndarray or dtype

Copy of `a` with fields repacked, or `a` itself if no repacking was

needed.

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> def print_offsets(d):

... print("offsets:", [d.fields[name][1] for name in d.names])

... print("itemsize:", d.itemsize)

...

>>> dt = np.dtype('u1, <i8, <f8', align=True)

>>> dt

dtype({'names': ['f0', 'f1', 'f2'], 'formats': ['u1', '<i8', '<f8'], \

'offsets': [0, 8, 16], 'itemsize': 24}, align=True)

>>> print_offsets(dt)

offsets: [0, 8, 16]

itemsize: 24

>>> packed_dt = rfn.repack_fields(dt)

>>> packed_dt

dtype([('f0', 'u1'), ('f1', '<i8'), ('f2', '<f8')])

>>> print_offsets(packed_dt)

offsets: [0, 1, 9]

itemsize: 17

"""

if not isinstance(a, np.dtype):

dt = repack_fields(a.dtype, align=align, recurse=recurse)

return a.astype(dt, copy=False)

if a.names is None:

return a

fieldinfo = []

for name in a.names:

tup = a.fields[name]

if recurse:

fmt = repack_fields(tup[0], align=align, recurse=True)

else:

fmt = tup[0]

if len(tup) == 3:

name = (tup[2], name)

fieldinfo.append((name, fmt))

dt = np.dtype(fieldinfo, align=align)

return np.dtype((a.type, dt))

def _get_fields_and_offsets(dt, offset=0):

"""

Returns a flat list of (dtype, count, offset) tuples of all the

scalar fields in the dtype "dt", including nested fields, in left

to right order.

"""

# counts up elements in subarrays, including nested subarrays, and returns

# base dtype and count

def count_elem(dt):

count = 1

while dt.shape != ():

for size in dt.shape:

count *= size

dt = dt.base

return dt, count

fields = []

for name in dt.names:

field = dt.fields[name]

f_dt, f_offset = field[0], field[1]

f_dt, n = count_elem(f_dt)

if f_dt.names is None:

fields.append((np.dtype((f_dt, (n,))), n, f_offset + offset))

else:

subfields = _get_fields_and_offsets(f_dt, f_offset + offset)

size = f_dt.itemsize

for i in range(n):

if i == 0:

# optimization: avoid list comprehension if no subarray

fields.extend(subfields)

else:

fields.extend([(d, c, o + i * size) for d, c, o in subfields])

return fields

def _common_stride(offsets, counts, itemsize):

"""

Returns the stride between the fields, or None if the stride is not

constant. The values in "counts" designate the lengths of

subarrays. Subarrays are treated as many contiguous fields, with

always positive stride.

"""

if len(offsets) <= 1:

return itemsize

negative = offsets[1] < offsets[0] # negative stride

if negative:

# reverse, so offsets will be ascending

it = zip(reversed(offsets), reversed(counts))

else:

it = zip(offsets, counts)

prev_offset = None

stride = None

for offset, count in it:

if count != 1: # subarray: always c-contiguous

if negative:

return None # subarrays can never have a negative stride

if stride is None:

stride = itemsize

if stride != itemsize:

return None

end_offset = offset + (count - 1) * itemsize

else:

end_offset = offset

if prev_offset is not None:

new_stride = offset - prev_offset

if stride is None:

stride = new_stride

if stride != new_stride:

return None

prev_offset = end_offset

if negative:

return -stride

return stride

def _structured_to_unstructured_dispatcher(arr, dtype=None, copy=None,

casting=None):

return (arr,)

@array_function_dispatch(_structured_to_unstructured_dispatcher)

def structured_to_unstructured(arr, dtype=None, copy=False, casting='unsafe'):

"""

Converts an n-D structured array into an (n+1)-D unstructured array.

The new array will have a new last dimension equal in size to the

number of field-elements of the input array. If not supplied, the output

datatype is determined from the numpy type promotion rules applied to all

the field datatypes.

Nested fields, as well as each element of any subarray fields, all count

as a single field-elements.

Parameters

----------

arr : ndarray

Structured array or dtype to convert. Cannot contain object datatype.

dtype : dtype, optional

The dtype of the output unstructured array.

copy : bool, optional

If true, always return a copy. If false, a view is returned if

possible, such as when the `dtype` and strides of the fields are

suitable and the array subtype is one of `numpy.ndarray`,

`numpy.recarray` or `numpy.memmap`.

.. versionchanged:: 1.25.0

A view can now be returned if the fields are separated by a

uniform stride.

casting : {'no', 'equiv', 'safe', 'same_kind', 'unsafe'}, optional

See casting argument of `numpy.ndarray.astype`. Controls what kind of

data casting may occur.

Returns

-------

unstructured : ndarray

Unstructured array with one more dimension.

Examples

--------

>>> import numpy as np

>>> from numpy.lib import recfunctions as rfn

>>> a = np.zeros(4, dtype=[('a', 'i4'), ('b', 'f4,u2'), ('c', 'f4', 2)])

>>> a

array([(0, (0., 0), [0., 0.]), (0, (0., 0), [0., 0.]),

(0, (0., 0), [0., 0.]), (0, (0., 0), [0., 0.])],

dtype=[('a', '<i4'), ('b', [('f0', '<f4'), ('f1', '<u2')]), ('c', '<f4', (2,))])

>>> rfn.structured_to_unstructured(a)

array([[0., 0., 0., 0., 0.],

[0., 0., 0., 0., 0.],

[0., 0., 0., 0., 0.],

[0., 0., 0., 0., 0.]])

>>> b = np.array([(1, 2, 5), (4, 5, 7), (7, 8 ,11), (10, 11, 12)],

... dtype=[('x', 'i4'), ('y', 'f4'), ('z', 'f8')])

>>> np.mean(rfn.structured_to_unstructured(b[['x', 'z']]), axis=-1)

array([ 3. , 5.5, 9. , 11. ])

""" # noqa: E501

if arr.dtype.names is None:

raise ValueError('arr must be a structured array')