ak.Record — Awkward Array documentation

# ak.Record

Defined in awkward.highlevel on line 1501.

class ak.Record(self, data, behavior=None, with_name=None, check_valid=False, cache=None, kernels=None)
  Parameters:

    - data (`ak.layout.Record`, `ak.Record`, str, or dict) – Data to wrap or convert into a record. If a string, the data are assumed to be JSON. If a dict, calls `ak.from_iter`, which assumes all inner dimensions have irregular lengths.

    - behavior (None or dict) – Custom `ak.behavior` for this Record only.

    - with_name (None or str) – Gives the record type a name that can be used to override its behavior (see below).

    - check_valid (bool) – If True, verify that the `layout` is valid.

    - kernels (None, `"cpu"`, or `"cuda"`) – If `"cpu"`, the Record will be placed in main memory for use with other `"cpu"` Arrays and Records; if `"cuda"`, the Record will be placed in GPU global memory using CUDA; if None, the `data` are left untouched. For `"cuda"`, awkward-cuda-kernels must be installed, which can be invoked with `pip install awkward[cuda] --upgrade`.

High-level record that can contain fields of any type.

Most users won’t be creating Records manually. This class primarily exists to be overridden in the same way as `ak.Array`.

Records can be used in Numba: they can be passed as arguments to a Numba-compiled function or returned as return values. The only limitation is that they cannot be created inside the Numba-compiled function; to make outputs, consider `ak.ArrayBuilder`.

See also `ak.Array` and `ak.behavior`.

## ak.Record.layout

ak.Record.layout

The `ak.layout.Record` that contains composable `ak.layout.Content` elements to determine how the array is structured.

See `ak.Array.layout` for a more complete description.

The `ak.layout.Record` is not a subclass of `ak.layout.Content` in Python (note: Record is a subclass of Content in C++!) and it is not composable with them: `ak.layout.Record` contains one `ak.layout.RecordArray` (which is a `ak.layout.Content`), but `ak.layout.Content` nodes cannot contain a `ak.layout.Record`.

A `ak.layout.Record` is not an independent entity from its `ak.layout.RecordArray`; it’s really just a marker indicating which element to select. The XML representation reflects that:

    >>> vectors = ak.Array([{"x": 0.1, "y": 1.0, "z": 30.0},
    ...                     {"x": 0.2, "y": 2.0, "z": 20.0},
    ...                     {"x": 0.3, "y": 3.0, "z": 10.0}])

    >>> vectors[1].layout
    <Record at="1">
        <RecordArray>
            <field index="0" key="x">
                <NumpyArray format="d" shape="3" data="0.1 0.2 0.3" at="0x555660dfe7d0"/>
            </field>
            <field index="1" key="y">
                <NumpyArray format="d" shape="3" data="1 2 3" at="0x555660df4180"/>
            </field>
            <field index="2" key="z">
                <NumpyArray format="d" shape="3" data="30 20 10" at="0x555660df6190"/>
            </field>
        </RecordArray>
    </Record>

## ak.Record.behavior

ak.Record.behavior

The `behavior` parameter passed into this Record’s constructor.

> - If a dict, this `behavior` overrides the global `ak.behavior`. Any keys in the global `ak.behavior` but not this `behavior` are still valid, but any keys in both are overridden by this `behavior`. Keys with a None value are equivalent to missing keys, so this `behavior` can effectively remove keys from the global `ak.behavior`.

> - If None, the Record defaults to the global `ak.behavior`.

See `ak.behavior` for a list of recognized key patterns and their meanings.

## ak.Record.caches

ak.Record.caches

## ak.Record.tolist

ak.Record.tolist(self)

Converts this Record into Python objects; same as `ak.to_list` (but without the underscore, like NumPy’s tolist).

## ak.Record.to_list

ak.Record.to_list(self)

Converts this Record into Python objects; same as `ak.to_list`.

## ak.Record.nbytes

ak.Record.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.Record.fields

ak.Record.fields

List of field names or tuple slot numbers (as strings) of this record.

If this is actually a tuple its fields are string representations of integers, such as `"0"`, `"1"`, `"2"`, etc.

See also `ak.fields`.

## ak.Record._ipython_key_completions_

ak.Record._ipython_key_completions_(self)

## ak.Record.__iter__

ak.Record.__iter__(self)

## ak.Record.type

ak.Record.type

The high-level type of this Record; same as `ak.type`.

Note that the outermost element of a Record’s type is always a `ak.types.RecordType`.

## ak.Record.__getitem__

ak.Record.__getitem__(self, where)
  Parameters:

    where (many types supported; see below) – Index of positions to select from this Record.

Select items from the Record using an extension of NumPy’s (already quite extensive) rules.

See `ak.Array.__getitem__` for a more complete description. Since this is a record, the first item in the slice tuple must be a string, selecting a field.

For example, with a `record` like

    ak.Record({"x": 3.3, "y": [1, 2, 3]})

we can select

    >>> record["x"]
    3.3
    >>> record["y"]
    <Array [1, 2, 3] type='3 * int64'>
    >>> record["y", 1]
    2

## ak.Record.__setitem__

ak.Record.__setitem__(self, where, what)
  Parameters:

    - where (str) – Field name to add data to the record.

    - what – Data to add as the new field.

For example:

    >>> record = ak.Record({"x": 3.3})
    >>> record["y"] = 4
    >>> record["z"] = {"another": "record"}
    >>> print(record)
    {x: 3.3, y: 4, z: {another: 'record'}}

See `ak.with_field` for a variant that does not change the `ak.Record` in-place. (Internally, this method uses `ak.with_field`, so performance is not a factor in choosing one over the other.)

## ak.Record.__getattr__

ak.Record.__getattr__(self, where)

Whenever possible, fields can be accessed as attributes.

For example, the fields of an `record` like

    ak.Record({"x": 1.1, "y": [2, 2], "z": "three"})

can be accessed as

    >>> record.x
    1.1
    >>> record.y
    <Array [2, 2] type='2 * int64'>
    >>> record.z
    'three'

which are equivalent to `record["x"]`, `record["y"]`, and `record["z"]`.

Fields can’t be accessed as attributes when

> - `ak.Record` methods or properties take precedence,

> - a domain-specific behavior has methods or properties that take precedence, or

> - the field name is not a valid Python identifier or is a Python keyword.

## ak.Record.__dir__

ak.Record.__dir__(self)

Lists all methods, properties, and field names (see `__getattr__`) that can be accessed as attributes.

## ak.Record.slot0

ak.Record.slot0

Equivalent to `__getitem__` with `"0"`, which selects slot `0` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.slot1

ak.Record.slot1

Equivalent to `__getitem__` with `"1"`, which selects slot `1` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.slot2

ak.Record.slot2

Equivalent to `__getitem__` with `"2"`, which selects slot `2` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.slot3

ak.Record.slot3

Equivalent to `__getitem__` with `"3"`, which selects slot `3` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.slot4

ak.Record.slot4

Equivalent to `__getitem__` with `"4"`, which selects slot `4` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.slot5

ak.Record.slot5

Equivalent to `__getitem__` with `"5"`, which selects slot `5` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.slot6

ak.Record.slot6

Equivalent to `__getitem__` with `"6"`, which selects slot `6` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.slot7

ak.Record.slot7

Equivalent to `__getitem__` with `"7"`, which selects slot `7` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.slot8

ak.Record.slot8

Equivalent to `__getitem__` with `"8"`, which selects slot `8` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.slot9

ak.Record.slot9

Equivalent to `__getitem__` with `"9"`, which selects slot `9` from the Record as a tuple.

See `ak.Array.slot0` for a more complete description.

## ak.Record.__str__

ak.Record.__str__(self)
  Parameters:

    limit_value (int) – Maximum number of characters to use when presenting the Record as a string.

Presents this Record as a string without type or `"<Record ...>"`.

See `ak.Array.__str__` for a more complete description.

## ak.Record.__repr__

ak.Record.__repr__(self)
  Parameters:

    - limit_value (int) – Maximum number of characters to use when presenting the data of the Record.

    - limit_total (int) – Maximum number of characters to use for the whole string (should be larger than `limit_value`).

Presents this Record as a string with its type and `"<Record ...>"`.

See `ak.Array.__repr__` for a more complete description.

## ak.Record._str

ak.Record._str(self, limit_value=85)

## ak.Record._repr

ak.Record._repr(self, limit_value=40, limit_total=85)

## ak.Record.__array_ufunc__

ak.Record.__array_ufunc__(self, ufunc, method)

Intercepts attempts to pass this Record to a NumPy universal functions (ufuncs) and passes it through the Record’s structure.

This method conforms to NumPy’s NEP 13 for overriding ufuncs, which has been available since NumPy 1.13 (and thus NumPy 1.13 is the minimum allowed version).

See `ak.Array.__array_ufunc__` for a more complete description.

## ak.Record.numba_type

ak.Record.numba_type

The type of this Record when it is used in Numba. It contains enough information to generate low-level code for accessing any element, down to the leaves.

See Numba documentation on types and signatures.

## ak.Record.__getstate__

ak.Record.__getstate__(self)

## ak.Record.__setstate__

ak.Record.__setstate__(self, state)

## ak.Record.__copy__

ak.Record.__copy__(self)

## ak.Record.__deepcopy__

ak.Record.__deepcopy__(self, memo)

## ak.Record.__bool__

ak.Record.__bool__(self)

## ak.Record.__contains__

ak.Record.__contains__(self, element)