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

Defined in awkward.operations.ak_mask on line 19.

ak.mask(array, mask, *, valid_when=True, highlevel=True, behavior=None, attrs=None)#

Parameters:

• array – Array-like data (anything ak.to_layout recognizes).
• mask (array of booleans) – The mask that overlays elements in thearray with None. Must have the same length as array.
• valid_when (bool) – If True, True values in mask are considered valid (passed from array to the output); if False, False values in mask are considered valid.
• 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 for which

output[i] = array[i] if mask[i] == valid_when else None

Unlike filtering data with ak.Array.__getitem__, this output has the same length as the original array and can therefore be used in calculations with it, such asuniversal functions.

For example, with

array = ak.Array([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])

with a boolean selection of good elements like

good = (array % 2 == 1) good <Array [False, True, False, True, ..., True, False, True] type='10 * bool'>

could be used to filter the original array (or another with the same length).

array[good] <Array [1, 3, 5, 7, 9] type='5 * int64'>

However, this eliminates information about which elements were dropped and where they were. If we instead use ak.mask,

ak.mask(array, good) <Array [None, 1, None, 3, None, 5, None, 7, None, 9] type='10 * ?int64'>

this information and the length of the array is preserved, and it can be used in further calculations with the original array (or another with the same length).

ak.mask(array, good) + array <Array [None, 2, None, 6, None, 10, None, 14, None, 18] type='10 * ?int64'>

In particular, successive filters can be applied to the same array.

Even if the array and/or the mask is nested,

array = ak.Array([[[0, 1, 2], [], [3, 4], [5]], [[6, 7, 8], [9]]]) good = (array % 2 == 1) good <Array [[[False, True, False], ..., [True]], ...] type='2 * var * var * bool'>

it can still be used with ak.mask because the array and maskparameters are broadcasted.

ak.mask(array, good) <Array [[[None, 1, None], [], ..., [5]], ...] type='2 * var * var * ?int64'>

See ak.broadcast_arrays for details about broadcasting and the generalized set of broadcasting rules.

Another syntax for

ak.mask(array, array_of_booleans)

is

array.mask[array_of_booleans]

(which is 5 characters away from simply filtering the array).