ak.flatten — Awkward Array documentation

# ak.flatten

Defined in awkward.operations.structure on line 1863.

ak.flatten(array, axis=1, highlevel=True, behavior=None)
  Parameters:

    - array – Data containing nested lists to flatten.

    - axis (None or int) – If None, the operation flattens all levels of nesting, returning a 1-dimensional array. Otherwise, it flattens at a specified depth. The outermost dimension is `0`, followed by `1`, etc., and negative values count backward from the innermost: `-1` is the innermost dimension, `-2` is the next level up, etc.

    - highlevel (bool) – If True, return an `ak.Array`; otherwise, return a low-level `ak.layout.Content` subclass.

    - behavior (None or dict) – Custom `ak.behavior` for the output array, if high-level.

Returns an array with one level of nesting removed by erasing the boundaries between consecutive lists. Since this operates on a level of nesting, `axis=0` is a special case that only removes values at the top level that are equal to None.

Consider the following doubly nested `array`.

    ak.Array([[
               [1.1, 2.2, 3.3],
               [],
               [4.4, 5.5],
               [6.6]],
              [],
              [
               [7.7],
               [8.8, 9.9]
              ]])

At `axis=1`, the outer lists (length 4, length 0, length 2) become a single list (of length 6).

    >>> print(ak.flatten(array, axis=1))
    [[1.1, 2.2, 3.3], [], [4.4, 5.5], [6.6], [7.7], [8.8, 9.9]]

At `axis=2`, the inner lists (lengths 3, 0, 2, 1, 1, and 2) become three lists (of lengths 6, 0, and 3).

    >>> print(ak.flatten(array, axis=2))
    [[1.1, 2.2, 3.3, 4.4, 5.5, 6.6], [], [7.7, 8.8, 9.9]]

There’s also an option to completely flatten the array with `axis=None`. This is useful for passing the data to a function that doesn’t care about nested structure, such as a plotting routine.

    >>> print(ak.flatten(array, axis=None))
    [1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, 8.8, 9.9]

Missing values are eliminated by flattening: there is no distinction between an empty list and a value of None at the level of flattening.

    >>> array = ak.Array([[1.1, 2.2, 3.3], None, [4.4], [], [5.5]])
    >>> ak.flatten(array, axis=1)
    <Array [1.1, 2.2, 3.3, 4.4, 5.5] type='5 * float64'>

As a consequence, flattening at `axis=0` does only one thing: it removes None values from the top level.

    >>> ak.flatten(array, axis=0)
    <Array [[1.1, 2.2, 3.3], [4.4], [], [5.5]] type='4 * var * float64'>

As a technical detail, the flattening operation can be trivial in a common case, `ak.layout.ListOffsetArray` in which the first `offset` is `0`. In that case, the flattened data is simply the array node’s `content`.

    >>> array.layout
    <ListOffsetArray64>
        <offsets><Index64 i="[0 4 4 6]" offset="0" length="4"/></offsets>
        <content><ListOffsetArray64>
            <offsets><Index64 i="[0 3 3 5 6 7 9]" offset="0" length="7"/></offsets>
            <content>
                <NumpyArray format="d" shape="9" data="1.1 2.2 3.3 4.4 5.5 6.6 7.7 8.8 9.9"/>
            </content>
        </ListOffsetArray64></content>
    </ListOffsetArray64>
    >>> np.asarray(array.layout.content.content)
    array([1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, 8.8, 9.9])

However, it is important to keep in mind that this is a special case: `ak.flatten` and `content` are not interchangeable!