ak.flatten — Awkward Array 2.8.2 documentation (original) (raw)

Defined in awkward.operations.ak_flatten on line 23.

ak.flatten(array, axis=1, *, highlevel=True, behavior=None, attrs=None)#

Parameters:

• array – Array-like data (anything ak.to_layout recognizes).
• 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.contents.Content subclass.
• behavior (None or dict) – Custom ak.behavior for the output array, if high-level.
• attrs (None or dict) – Custom attributes 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.

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).

ak.flatten(array, axis=1).show() [[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).

ak.flatten(array, axis=2).show() [[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.

ak.flatten(array, axis=None).show() [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.contents.ListOffsetArray in which the first offset is 0. In that case, the flattened data is simply the array node’s content.

array = ak.Array([[0.0, 1.1, 2.2], [], [3.3, 4.4], [5.5], [6.6, 7.7, 8.8, 9.9]]) array.layout [ 0 3 3 5 6 10] [0. 1.1 2.2 3.3 4.4 5.5 6.6 7.7 8.8 9.9]

ak.flatten(array).layout [0. 1.1 2.2 3.3 4.4 5.5 6.6 7.7 8.8 9.9]

array.layout.content [0. 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!

array = ak.Array( ... ak.contents.ListArray( ... ak.index.Index64(np.array([ 9, 100, 5, 8, 1])), ... ak.index.Index64(np.array([12, 100, 7, 9, 5])), ... ak.contents.NumpyArray( ... np.array([999, 6.6, 7.7, 8.8, 9.9, 3.3, 4.4, 999, 5.5, 0., 1.1, 2.2, 999]) ... ), ... ) ... ) array.show() [[0, 1.1, 2.2], [], [3.3, 4.4], [5.5], [6.6, 7.7, 8.8, 9.9]]

ak.flatten(array).show() [0, 1.1, 2.2, 3.3, 4.4, 5.5, 6.6, 7.7, 8.8, 9.9]

ak.Array(array.layout.content).show() [999, 6.6, 7.7, 8.8, 9.9, 3.3, 4.4, 999, 5.5, 0, 1.1, 2.2, 999]