ak.flatten¶
Defined in awkward.operations.structure on line 1822.
- 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 by1
, 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-levelak.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!