bitfield_to_boolean_mask#
- astropy.nddata.bitmask.bitfield_to_boolean_mask(bitfield, ignore_flags=None, flip_bits=None, good_mask_value=False, dtype=numpy.bool_)[source]#
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:
- bitfield
ndarray
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 thebitfield
array data.- ignore_flags
int
,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 inputbitfield
should be ignored (i.e., zeroed), orNone
.Note
When
bit_flags
is a list of flag names, theflag_name_map
parameter must be provided.Settingignore_flags
toNone
effectively will makebitfield_to_boolean_mask
interpret allbitfield
elements as “good” regardless of their value.Whenignore_flags
argument is an integer bit mask, it will be combined using bitwise-NOT and bitwise-AND with each element of the inputbitfield
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 theignore_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 inputbitfield
array are to be interpreted as “bad”.Whenignore_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, useflip_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 inputbitfield
array should be ignored when generating boolean mask.Note
'None'
,'INDEF'
, and empty (or all white space) strings are special values of stringignore_flags
that are interpreted asNone
.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 astr
and when it is prepended with ‘~’, then the meaning ofignore_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 inputbitfield
array are “bad”. Following this convention, anignore_flags
string value of'~0'
would be equivalent to settingignore_flags=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 throughignore_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 thebitfield
array when creating a boolean mask as opposed to ignoring specific bit flags asignore_flags
behaves by default. This can be achieved by inverting/flipping the bits of the bit mask created fromignore_flags
flags which effectively changes the meaning of theignore_flags
parameter from “ignore” to “use only” these flags. Settingflip_bits
toNone
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 forignore_flags
for more details).- good_mask_value
int
, 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 inputbitfield
array. Whengood_mask_value
is non-zero ornumpy.True_
then values in the output boolean mask array corresponding to “good” bit fields inbitfield
will benumpy.True_
(ifdtype
isnumpy.bool_
) or 1 (ifdtype
is of numerical type) and values of corresponding to “bad” flags will benumpy.False_
(or 0). Whengood_mask_value
is zero ornumpy.False_
then the values in the output boolean mask array corresponding to “good” bit fields inbitfield
will benumpy.False_
(ifdtype
isnumpy.bool_
) or 0 (ifdtype
is of numerical type) and values of corresponding to “bad” flags will benumpy.True_
(or 1).- dtypedata-type (default =
numpy.bool_
) The desired data-type for the output binary mask array.
- flag_name_map
BitFlagNameMap
A
BitFlagNameMap
object that provides mapping from mnemonic bit flag names to integer bit values in order to translate mnemonic flags to numeric values whenbit_flags
that are comma- or ‘+’-separated list of menmonic bit flag names.
- bitfield
- Returns:
- mask
ndarray
Returns an array of the same dimensionality as the input
bitfield
array whose elements can have two possible values, e.g.,numpy.True_
ornumpy.False_
(or 1 or 0 for integerdtype
) according to values of to the inputbitfield
elements,ignore_flags
parameter, and thegood_mask_value
parameter.
- mask
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]])