ak.pad_none#

Defined in awkward.operations.ak_pad_none on line 21.

ak.pad_none(array, target, axis=1, *, clip=False, highlevel=True, behavior=None, attrs=None)#

Increases the lengths of lists to a target length by adding None values.

Note that the clip parameter not only determines whether the lengths are at least target or exactly target, it also determines the type of the output:

The in-principle variable-length lists might, in fact, all have the same length, but the type difference is significant, for instance in broadcasting rules (see ak.broadcast_arrays).

Parameters:

  • array – Array-like data (anything ak.to_layout recognizes).

  • target (int) – The intended length of the lists. If clip=True, the output lists will have exactly this length; otherwise, they will have at least this length.

  • axis (int or str) – The dimension at which this operation is applied. 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. If a str, it is interpreted as the name of the axis which maps to an int if named axes are present. Named axes are attached to an array using ak.with_named_axis and removed with ak.without_named_axis; also see the Named axes user guide.

  • clip (bool) – If True, the output lists will have regular lengths (ak.types.RegularType) of exactly target; otherwise the output lists will have in-principle variable lengths (ak.types.ListType) of at least target.

  • 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 whose lists are padded with None to at least the target length.

Examples

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=0, this operation pads the whole array, adding None at the outermost level:

>>> ak.pad_none(array, 5, axis=0).show()
[[[1.1, 2.2, 3.3], [], [4.4, 5.5], [6.6]],
 [],
 [[7.7], [8.8, 9.9]],
 None,
 None]

At axis=1, this operation pads the first nested level:

>>> ak.pad_none(array, 3, axis=1).show()
[[[1.1, 2.2, 3.3], [], [4.4, 5.5], [6.6]],
 [None, None, None],
 [[7.7], [8.8, 9.9], None]]

And so on for higher values of axis:

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

The difference between

>>> ak.pad_none(array, 2, axis=2)
<Array [[[1.1, 2.2, 3.3], ..., [...]], ...] type='3 * var * var * ?float64'>

and

>>> ak.pad_none(array, 2, axis=2, clip=True)
<Array [[[1.1, 2.2], ..., [6.6, None]], ...] type='3 * var * 2 * ?float64'>

is not just in the length of [1.1, 2.2, 3.3] vs [1.1, 2.2], but also in the distinction between the following types.

>>> ak.pad_none(array, 2, axis=2).type.show()
3 * var * var * ?float64
>>> ak.pad_none(array, 2, axis=2, clip=True).type.show()
3 * var *   2 * ?float64