interpret_bit_flags

astropy.nddata.bitmask.interpret_bit_flags(bit_flags, flip_bits=None, flag_name_map=None)

Converts input bit flags to a single integer value (bit mask) or None.

When input is a list of flags (either a Python list of integer flags or a string of comma-, '|'-, or '+'-separated list of flags), the returned bit mask is obtained by summing input flags.

Note

In order to flip the bits of the returned bit mask, for input of str type, prepend ‘~’ to the input string. ‘~’ must be prepended to the entire string and not to each bit flag! For input that is already a bit mask or a Python list of bit flags, set flip_bits for True in order to flip the bits of the returned bit mask.

Parameters:

bit_flagspython:int, python:str, python:list, python:None

An integer bit mask or flag, None, a string of comma-, '|'- or '+'-separated list of integer bit flags or mnemonic flag names, or a Python list of integer bit flags. If bit_flags is a str and if it is prepended with ‘~’, then the output bit mask will have its bits flipped (compared to simple sum of input flags). For input bit_flags that is already a bit mask or a Python list of bit flags, bit-flipping can be controlled through flip_bits parameter.

Note

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

Note

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

flip_bitsbool, python:None

Indicates whether or not to flip the bits of the returned bit mask obtained from input bit flags. This parameter must be set to None when input bit_flags is either None or a Python list of flags.

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:

bitmaskpython:int or python:None

Returns an integer bit mask formed from the input bit value or None if input bit_flags parameter is None or an empty string. If input string value was prepended with ‘~’ (or flip_bits was set to True), then returned value will have its bits flipped (inverse mask).

Examples

>>> from astropy.nddata.bitmask import interpret_bit_flags, extend_bit_flag_map
>>> ST_DQ = extend_bit_flag_map('ST_DQ', CR=1, CLOUDY=4, RAINY=8, HOT=16, DEAD=32)
>>> "{0:016b}".format(0xFFFF & interpret_bit_flags(28))
'0000000000011100'
>>> "{0:016b}".format(0xFFFF & interpret_bit_flags('4,8,16'))
'0000000000011100'
>>> "{0:016b}".format(0xFFFF & interpret_bit_flags('CLOUDY,RAINY,HOT', flag_name_map=ST_DQ))
'0000000000011100'
>>> "{0:016b}".format(0xFFFF & interpret_bit_flags('~4,8,16'))
'1111111111100011'
>>> "{0:016b}".format(0xFFFF & interpret_bit_flags('~(4+8+16)'))
'1111111111100011'
>>> "{0:016b}".format(0xFFFF & interpret_bit_flags('~(CLOUDY+RAINY+HOT)',
... flag_name_map=ST_DQ))
'1111111111100011'
>>> "{0:016b}".format(0xFFFF & interpret_bit_flags([4, 8, 16]))
'0000000000011100'
>>> "{0:016b}".format(0xFFFF & interpret_bit_flags([4, 8, 16], flip_bits=True))
'1111111111100011'