liger_iris_pipeline.datamodels.dqflags

Liger and IRIS Data Quality Flags copied from jwst.

The definitions are documented in the JWST RTD:

https://jwst-pipeline.readthedocs.io/en/latest/jwst/references_general/references_general.html#data-quality-flags

Implementation

The flags are implemented as “bit flags”: Each flag is assigned a bit position in a byte, or multi-byte word, of memory. If that bit is set, the flag assigned to that bit is interpreted as being set or active.

The data structure that stores bit flags is just the standard Python int, which provides 32 bits. Bits of an integer are most easily referred to using the formula 2**bit_number where bit_number is the 0-index bit of interest.

liger_iris_pipeline.datamodels.dqflags.ap_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_flagsint, str, list, 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, 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

bitmaskint or 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'

liger_iris_pipeline.datamodels.dqflags.dqflags_to_mnemonics(dqflags, mnemonic_map)[source]

Interpret value as bit flags and return the mnemonics

Parameters

dqflagsint-like: The value to interpret as DQ flags
mnemonic_map: {str: int[,…]}: Dictionary associating the mnemonic string to an integer value representing the set bit for that mnemonic.

Returns

mnemonics{str[,…]}: Set of mnemonics represented by the set bit flags

Examples

>>> pixel = {'GOOD':             0,      # No bits set, all is good
...          'DO_NOT_USE':       2**0,   # Bad pixel. Do not use
...          'SATURATED':        2**1,   # Pixel saturated during exposure
...          'JUMP_DET':         2**2,   # Jump detected during exposure
...          }

>>> group = {'GOOD':       pixel['GOOD'],
...          'DO_NOT_USE': pixel['DO_NOT_USE'],
...          'SATURATED':  pixel['SATURATED'],
...          }

>>> dqflags_to_mnemonics(1, pixel)
{'DO_NOT_USE'}

>>> dqflags_to_mnemonics(7, pixel)             
{'JUMP_DET', 'DO_NOT_USE', 'SATURATED'}

>>> dqflags_to_mnemonics(7, pixel) == {'JUMP_DET', 'DO_NOT_USE', 'SATURATED'}
True

>>> dqflags_to_mnemonics(1, mnemonic_map=pixel)
{'DO_NOT_USE'}

>>> dqflags_to_mnemonics(1, mnemonic_map=group)
{'DO_NOT_USE'}

liger_iris_pipeline.datamodels.dqflags.interpret_bit_flags(bit_flags, flip_bits=None, mnemonic_map=None)[source]

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

Wraps astropy.nddate.bitmask.interpret_bit_flags, allowing the bit mnemonics to be used in place of integers.

Parameters

bit_flagsint, str, list, None: See astropy.nddate.bitmask.interpret_bit_flags. Also allows strings using Roman mnemonics
flip_bitsbool, None: See astropy.nddata.bitmask.interpret_bit_flags.
mnemonic_map{str: int[,…]}: Dictionary associating the mnemonic string to an integer value representing the set bit for that mnemonic.

Returns

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

liger_iris_pipeline.datamodels.dqflags.multiple_replace(string, rep_dict)[source]

Single-pass replacement of multiple substrings

Similar to str.replace, except that a dictionary of replacements can be specified.

The replacements are done in a single-pass. This means that a previous replacement will not be replaced by a subsequent match.

Parameters

string: str: The source string to have replacements done on it.
rep_dict: dict: The replacements were key is the input substring and value is the replacement

Returns

replaced: str: New string with the replacements done

Examples

Basic example that also demonstrates the single-pass nature. If the replacements where chained, the result would have been ‘lamb lamb’

>>> multiple_replace('button mutton', {'but': 'mut', 'mutton': 'lamb'})
'mutton lamb'