ak.layout.Content — Awkward Array documentation

# ak.layout.Content

Superclass of array nodes that build up the structure of an ak.Array; the array layout returned by the ak.Array.layout property.

The array node types are listed below.

> - ak.layout.EmptyArray: array with zero length and ak.types.UnknownType.

> - ak.layout.NumpyArray: complete equivalent to a NumPy np.ndarray, usually with ak.types.PrimitiveType.

> - ak.layout.RegularArray: nested lists of equal length; has ak.types.RegularType.

> - ak.layout.ListArray (64-bit, 32-bit, and unsigned 32-bit specializations): nested lists of any length (built with two indexes, `starts` and `stops`), has ak.types.ListType.

> - ak.layout.ListOffsetArray (64-bit, 32-bit, and unsigned 32-bit specializations): nested lists of any length (built with one index, `offsets`), has ak.types.ListType.

> - ak.layout.RecordArray: array of records or tuples; has ak.types.RecordType.

> - ak.layout.IndexedArray (64-bit, 32-bit, and unsigned 32-bit specializations): contains any array and reorders/duplicates it with an arbitrary integer `index`; has the same type as its content.

> - ak.layout.IndexedOptionArray (64-bit and 32-bit specializations): same as above but `-1` values in the `index` are interpreted as None; has ak.types.OptionType.

> - ak.layout.ByteMaskedArray: boolean bytes in a `mask` are interpreted as valid contents or None; has ak.types.OptionType.

> - ak.layout.BitMaskedArray: boolean bits in a `mask` are interpreted as valid contents or None; has ak.types.OptionType.

> - ak.layout.UnmaskedArray: formally has ak.types.OptionType, but all data are valid (no `mask`).

> - ak.layout.UnionArray (8-bit signed `tags` with 64-bit, 32-bit, and unsigned 32-bit `index` specializations): heterogeneous data represented as a tagged union; has ak.types.UnionType.

In Python, ak.layout.Record is not a subclass of ak.layout.Content (though it is in C++ for technical reasons).

All ak.layout.Content nodes have the following properties and methods in common.

## ak.layout.Content.identities

ak.layout.Content.identities

Returns the ak.layout.Identities object associated with this array node (if any).

## ak.layout.Content.identity

ak.layout.Content.identity

Returns the single element of an ak.layout.Identities associated with this array node (if any).

## ak.layout.Content.nbytes

ak.layout.Content.nbytes

The total number of bytes in all the ak.layout.Index, ak.layout.Identities, and ak.layout.NumpyArray buffers in this array tree.

Note: this calculation takes overlapping buffers into account, to the extent that overlaps are not double-counted, but overlaps are currently assumed to be complete subsets of one another, and so it is theoretically possible (though unlikely) that this number is an underestimate of the true usage.

It also does not count buffers that must be kept in memory because of ownership, but are not directly used in the array. Nor does it count the (small) C++ nodes or Python objects that reference the (large) array buffers.

## ak.layout.Content.numfields

ak.layout.Content.numfields

Number of fields in the outermost records or tuples, or -1 if the array does not contain records or tuples.

## ak.layout.Content.parameters

ak.layout.Content.parameters

Free-form parameters associated with every array node as a dict from parameter name to its JSON-like value. Some parameters are special and are used to assign behaviors to the data.

Note that the dict returned by this property is a copy of the array node’s parameters. Changing the dict will not change the array!

See ak.behavior and ak.Array.

## ak.layout.Content.purelist_depth

ak.layout.Content.purelist_depth

Number of dimensions of nested lists, not counting anything deeper than the first record or tuple layer, if any. The depth of a one-dimensional array is 1.

If the array contains ak.types.UnionType data and its contents have equal depths, the return value is that depth. If they do not have equal depths, the return value is -1.

## ak.layout.Content.purelist_isregular

ak.layout.Content.purelist_isregular

Returns True if all dimensions down to the first record or tuple layer have ak.types.RegularType; False otherwise.

## ak.layout.Content.__getitem__

ak.layout.Content.__getitem__(where)

See ak.Array.__getitem__.

## ak.layout.Content.__iter__

ak.layout.Content.__iter__()

See ak.Array.__iter__.

## ak.layout.Content.__len__

ak.layout.Content.__len__()

See ak.Array.__len__.

## ak.layout.Content.__repr__

ak.layout.Content.__repr__()

A multi-line XML representation of the array structure.

See (for contrast) ak.Array.__repr__.

## ak.layout.Content.all

ak.layout.Content.all(axis=-1, mask=False, keepdims=False)

Implements ak.all.

## ak.layout.Content.any

ak.layout.Content.any(axis=-1, mask=False, keepdims=False)

Implements ak.any.

## ak.layout.Content.argmax

ak.layout.Content.argmax(axis=-1, mask=True, keepdims=False)

Implements ak.argmax.

## ak.layout.Content.argmin

ak.layout.Content.argmin(axis=-1, mask=True, keepdims=False)

Implements ak.argmin.

## ak.layout.Content.combinations

ak.layout.Content.combinations(n, replacement=False, keys=None, parameters=None, axis=1)

Implements ak.combinations.

## ak.layout.Content.count

ak.layout.Content.count(axis=-1, mask=False, keepdims=False)

Implements ak.count.

## ak.layout.Content.count_nonzero

ak.layout.Content.count_nonzero(axis=-1, mask=False, keepdims=False)

Implements ak.count_nonzero.

## ak.layout.Content.deep_copy

ak.layout.Content.deep_copy(copyarrays=True, copyindexes=True, copyidentities=True)

Returns a copy of the array node and its children.

> - If `copyarrays`, then ak.layout.NumpyArray buffers are also copied.

> - If `copyindexes`, then ak.layout.Index buffers are also copied.

> - If `copyidentities`, then ak.layout.Identities buffers are also copied.

If all three flags are False, then only (small) C++ and Pyhton objects are copied, not (large) array buffers.

## ak.layout.Content.fieldindex

ak.layout.Content.fieldindex(key)

Returns the `fieldindex` (int) associated with a `key` (str) of the outermost record or tuple. If the array does not contain records or tuples, this method raises an error.

## ak.layout.Content.fillna

ak.layout.Content.fillna(value)

Implements ak.fill_none.

## ak.layout.Content.flatten

ak.layout.Content.flatten(axis=1)

Implements ak.flatten.

## ak.layout.Content.getitem_nothing

ak.layout.Content.getitem_nothing()

Returns an empty array with this array structure. Used for a corner-case of `__getitem__`.

## ak.layout.Content.haskey

ak.layout.Content.haskey(key)

Returns True if the outermost record or tuple has a given `key`; False otherwise (including the case of not containing records or tuples).

## ak.layout.Content.key

ak.layout.Content.key(fieldindex)

Returns the `key` (str) associated with a `fieldindex` (int) of the outermost record or tuple. If the array does not contain records or tuples, this method raises an error.

## ak.layout.Content.keys

ak.layout.Content.keys()

Returns the keys of the outermost record or tuple or an empty list.

## ak.layout.Content.localindex

ak.layout.Content.localindex(axis=1)

Returns nested lists of integers (down to the chosen `axis`) that count from 0 to the length - 1 of the innermost list.

This is used internally to generate ak.argcartesian from ak.cartesian, etc.

## ak.layout.Content.max

ak.layout.Content.max(axis=-1, mask=True, keepdims=False)

Implements ak.max.

## ak.layout.Content.merge

ak.layout.Content.merge(other)

Concatenate this array node with the `other` array node (`axis=0`) by sharing buffers; i.e. without using a ak.layout.UnionArray. If this is not possible, this method raises an error.

## ak.layout.Content.merge_as_union

ak.layout.Content.merge_as_union(other)

Concatenate this array node with the `other` array node (`axis=0`) using a ak.layout.UnionArray instead of attempting to share buffers.

## ak.layout.Content.mergeable

ak.layout.Content.mergeable(other, mergebool=False)

If True, this array node can be concatenated (`axis=0`) with the `other` array node without resorting to a ak.layout.UnionArray; otherwise, they cannot.

If `mergebool` is True, consider booleans to be a numeric type that can be merged with numeric arrays (integers and floating-point).

## ak.layout.Content.min

ak.layout.Content.min(axis=-1, mask=True, keepdims=False)

Implements ak.min.

## ak.layout.Content.num

ak.layout.Content.num(axis=1)

Implements ak.num.

## ak.layout.Content.offsets_and_flatten

ak.layout.Content.offsets_and_flatten(axis=1)

Implements ak.flatten, though it returns a set of `offsets` along with the flattened array.

## ak.layout.Content.parameter

ak.layout.Content.parameter(key)

Get one parameter by its `key` (outermost node only). If a `key` is not found, None is returned.

## ak.layout.Content.prod

ak.layout.Content.prod(axis=-1, mask=False, keepdims=False)

Implements ak.prod.

## ak.layout.Content.purelist_parameter

ak.layout.Content.purelist_parameter(key)

Return the value of the outermost parameter matching `key` in a sequence of nested lists, stopping at the first record or tuple layer.

If a layer has ak.types.UnionType, the value is only returned if all possibilities have the same value.

## ak.layout.Content.rpad

ak.layout.Content.rpad(arg0, arg1)

Implements ak.pad_none with `clip=False`.

## ak.layout.Content.rpad_and_clip

ak.layout.Content.rpad_and_clip(arg0, arg1)

Implements ak.pad_none with `clip=True`.

## ak.layout.Content.setidentities

ak.layout.Content.setidentities()

ak.layout.Content.setidentities(identities)

Sets identities in-place.

Do not use this function: it is deprecated and will be removed. Assign ak.layout.Identities in the constructor only.

## ak.layout.Content.setparameter

ak.layout.Content.setparameter(key, value)

Sets one parameter in-place.

Do not use this function: it is deprecated and will be removed. Assign parameters in the constructor only.

## ak.layout.Content.simplify

ak.layout.Content.simplify()

Flattens one extraneous level of ak.types.OptionType or ak.types.UnionType. If there is no such level, this is a pass-through. In all cases, the output has the same logical meaning as the input.

## ak.layout.Content.sum

ak.layout.Content.sum(axis=-1, mask=False, keepdims=False)

Implements ak.sum.

## ak.layout.Content.toRegularArray

ak.layout.Content.toRegularArray()

Converts the data to a ak.layout.RegularArray, if possible.

## ak.layout.Content.tojson

ak.layout.Content.tojson(pretty=False, maxdecimals=None)

Converts this array node to JSON and returns it as a string.

See ak.to_json.

ak.layout.Content.tojson(destination, pretty=False, maxdecimals=None, buffersize=65536)

Converts this array node to JSON and writes it to a file (`destination`).

See ak.to_json.

## ak.layout.Content.type

ak.layout.Content.type()

Returns the high-level ak.types.Type of this array node.