bitfield_to_boolean_mask

astropy.nddata.bitfield_to_boolean_mask(bitfield, ignore_flags=None, flip_bits=None, good_mask_value=False, dtype=numpy.bool_)

Converts an array of bit fields to a boolean (or integer) mask array according to a bit mask constructed from the supplied bit flags (see ignore_flags parameter).

This function is particularly useful to convert data quality arrays to boolean masks with selective filtering of DQ flags.

Parameters:

bitfieldndarray

An array of bit flags. By default, values different from zero are interpreted as “bad” values and values equal to zero are considered as “good” values. However, see ignore_flags parameter on how to selectively ignore some bits in the bitfield array data.

ignore_flagsint, str, list, None (default = 0)

An integer bit mask, None, a Python list of bit flags, a comma-, or '|'-separated, '+'-separated string list of integer bit flags or mnemonic flag names that indicate what bits in the input bitfield should be ignored (i.e., zeroed), or None.

Note

When bit_flags is a list of flag names, the flag_name_map parameter must be provided.

Setting ignore_flags to None effectively will make bitfield_to_boolean_mask interpret all bitfield elements as “good” regardless of their value.

When ignore_flags argument is an integer bit mask, it will be combined using bitwise-NOT and bitwise-AND with each element of the input bitfield array (~ignore_flags & bitfield). If the resultant bitfield element is non-zero, that element will be interpreted as a “bad” in the output boolean mask and it will be interpreted as “good” otherwise. flip_bits parameter may be used to flip the bits (bitwise-NOT) of the bit mask thus effectively changing the meaning of the ignore_flags parameter from “ignore” to “use only” these flags.

Note

Setting ignore_flags to 0 effectively will assume that all non-zero elements in the input bitfield array are to be interpreted as “bad”.

When ignore_flags argument is a Python list of integer bit flags, these flags are added together to create an integer bit mask. Each item in the list must be a flag, i.e., an integer that is an integer power of 2. In order to flip the bits of the resultant bit mask, use flip_bits parameter.

Alternatively, ignore_flags may be a string of comma- or '+'``(or ``'|')-separated list of integer bit flags that should be added (bitwise OR) together to create an integer bit mask. For example, both '4,8', '4|8', and '4+8' are equivalent and indicate that bit flags 4 and 8 in the input bitfield array should be ignored when generating boolean mask.

Note

'None', 'INDEF', and empty (or all white space) strings are special values of string ignore_flags that are interpreted as None.

Note

Each item in the list must be a flag, i.e., an integer that is an integer power of 2. In addition, for convenience, an arbitrary single integer is allowed and it will be interpreted as an integer bit mask. For example, instead of '4,8' one could simply provide string '12'.

Note

Only one flag separator is supported at a time. ignore_flags string should not mix ',', '+', and '|' separators.

Note

When ignore_flags is a str and when it is prepended with ‘~’, then the meaning of ignore_flags parameters will be reversed: now it will be interpreted as a list of bit flags to be used (or not ignored) when deciding which elements of the input bitfield array are “bad”. Following this convention, an ignore_flags string value of '~0' would be equivalent to setting ignore_flags=None.

Warning

Because prepending ‘~’ to a string ignore_flags is equivalent to setting flip_bits to True, flip_bits cannot be used with string ignore_flags and it must be set to None.

flip_bitsbool, None (default = None)

Specifies whether or not to invert the bits of the bit mask either supplied directly through ignore_flags parameter or built from the bit flags passed through ignore_flags (only when bit flags are passed as Python lists of integer bit flags). Occasionally, it may be useful to consider only specific bit flags in the bitfield array when creating a boolean mask as opposed to ignoring specific bit flags as ignore_flags behaves by default. This can be achieved by inverting/flipping the bits of the bit mask created from ignore_flags flags which effectively changes the meaning of the ignore_flags parameter from “ignore” to “use only” these flags. Setting flip_bits to None means that no bit flipping will be performed. Bit flipping for string lists of bit flags must be specified by prepending ‘~’ to string bit flag lists (see documentation for ignore_flags for more details).

Warning

This parameter can be set to either True or False ONLY when ignore_flags is either an integer bit mask or a Python list of integer bit flags. When ignore_flags is either None or a string list of flags, flip_bits MUST be set to None.

good_mask_valueint, bool (default = False)

This parameter is used to derive the values that will be assigned to the elements in the output boolean mask array that correspond to the “good” bit fields (that are 0 after zeroing bits specified by ignore_flags) in the input bitfield array. When good_mask_value is non-zero or numpy.True_ then values in the output boolean mask array corresponding to “good” bit fields in bitfield will be numpy.True_ (if dtype is numpy.bool_) or 1 (if dtype is of numerical type) and values of corresponding to “bad” flags will be numpy.False_ (or 0). When good_mask_value is zero or numpy.False_ then the values in the output boolean mask array corresponding to “good” bit fields in bitfield will be numpy.False_ (if dtype is numpy.bool_) or 0 (if dtype is of numerical type) and values of corresponding to “bad” flags will be numpy.True_ (or 1).

dtypedata-type (default = numpy.bool_)

The desired data-type for the output binary mask array.

flag_name_mapBitFlagNameMap

A BitFlagNameMap object that provides mapping from mnemonic bit flag names to integer bit values in order to translate mnemonic flags to numeric values when bit_flags that are comma- or ‘+’-separated list of menmonic bit flag names.

Returns:

maskndarray

Returns an array of the same dimensionality as the input bitfield array whose elements can have two possible values, e.g., numpy.True_ or numpy.False_ (or 1 or 0 for integer dtype) according to values of to the input bitfield elements, ignore_flags parameter, and the good_mask_value parameter.

Examples

>>> from astropy.nddata import bitmask
>>> import numpy as np
>>> dqarr = np.asarray([[0, 0, 1, 2, 0, 8, 12, 0],
...                     [10, 4, 0, 0, 0, 16, 6, 0]])
>>> flag_map = bitmask.extend_bit_flag_map(
...     'ST_DQ', CR=2, CLOUDY=4, RAINY=8, HOT=16, DEAD=32
... )
>>> bitmask.bitfield_to_boolean_mask(dqarr, ignore_flags=0,
...                                  dtype=int)
array([[0, 0, 1, 1, 0, 1, 1, 0],
       [1, 1, 0, 0, 0, 1, 1, 0]])
>>> bitmask.bitfield_to_boolean_mask(dqarr, ignore_flags=0,
...                                  dtype=bool)
array([[False, False,  True,  True, False,  True,  True, False],
       [ True,  True, False, False, False,  True,  True, False]]...)
>>> bitmask.bitfield_to_boolean_mask(dqarr, ignore_flags=6,
...                                  good_mask_value=0, dtype=int)
array([[0, 0, 1, 0, 0, 1, 1, 0],
       [1, 0, 0, 0, 0, 1, 0, 0]])
>>> bitmask.bitfield_to_boolean_mask(dqarr, ignore_flags=~6,
...                                  good_mask_value=0, dtype=int)
array([[0, 0, 0, 1, 0, 0, 1, 0],
       [1, 1, 0, 0, 0, 0, 1, 0]])
>>> bitmask.bitfield_to_boolean_mask(dqarr, ignore_flags=6, dtype=int,
...                                  flip_bits=True, good_mask_value=0)
array([[0, 0, 0, 1, 0, 0, 1, 0],
       [1, 1, 0, 0, 0, 0, 1, 0]])
>>> bitmask.bitfield_to_boolean_mask(dqarr, ignore_flags='~(2+4)',
...                                  good_mask_value=0, dtype=int)
array([[0, 0, 0, 1, 0, 0, 1, 0],
       [1, 1, 0, 0, 0, 0, 1, 0]])
>>> bitmask.bitfield_to_boolean_mask(dqarr, ignore_flags=[2, 4],
...                                  flip_bits=True, good_mask_value=0,
...                                  dtype=int)
array([[0, 0, 0, 1, 0, 0, 1, 0],
       [1, 1, 0, 0, 0, 0, 1, 0]])
>>> bitmask.bitfield_to_boolean_mask(dqarr, ignore_flags='~(CR,CLOUDY)',
...                                  good_mask_value=0, dtype=int,
...                                  flag_name_map=flag_map)
array([[0, 0, 0, 1, 0, 0, 1, 0],
       [1, 1, 0, 0, 0, 0, 1, 0]])
>>> bitmask.bitfield_to_boolean_mask(dqarr, ignore_flags='~(CR+CLOUDY)',
...                                  good_mask_value=0, dtype=int,
...                                  flag_name_map=flag_map)
array([[0, 0, 0, 1, 0, 0, 1, 0],
       [1, 1, 0, 0, 0, 0, 1, 0]])