Skip to main content
`Ctrl`+`K`

# interpret_bit_flags

astropy.nddata.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_flags `python: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_bits bool, `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_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 when `bit_flags` that are comma- or ‘+’-separated list of menmonic bit flag names.

  Returns:
    bitmask `python: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'