ak.pad_none

Defined in awkward.operations.structure on line 2314.

ak.pad_none(array, target, axis=1, clip=False, highlevel=True, behavior=None)
Parameters
  • array – Data containing nested lists to pad to a target length.

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

  • 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.layout.Content subclass.

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

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

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

>>> ak.to_list(ak.pad_none(array, 5, axis=0))
[[
  [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.to_list(ak.pad_none(array, 3, axis=1))
[[
  [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.to_list(ak.pad_none(array, 2, axis=2))
[[
  [1.1, 2.2, 3.3],
  [None, None],
  [4.4, 5.5],
  [6.6, None]
 ],
 [],
 [
  [7.7, None],
  [8.8, 9.9]
 ]]

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:

  • clip=True returns regular lists (ak.types.RegularType), and

  • clip=False returns in-principle variable lengths (ak.types.ListType).

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

The difference between

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

and

>>> ak.pad_none(array, 2, axis=2, clip=True)
<Array [[[1.1, 2.2], [None, ... [8.8, 9.9]]] 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.type(ak.pad_none(array, 2, axis=2))
3 * var * var * ?float64
>>> ak.type(ak.pad_none(array, 2, axis=2, clip=True))
3 * var *   2 * ?float64