bitfield_to_boolean_mask

ccdproc.bitfield_to_boolean_mask(bitfield, ignore_bits=0, flip_bits=None)[source]

Convert an integer bit field to a boolean mask.

Parameters:
bitfieldnumpy.ndarray of integer dtype

The array of bit flags.

ignore_bitsint, None or str, optional

The bits to ignore when converting the bitfield.

  • If it’s an integer it’s binary representation is interpreted as the bits to ignore. 0 means that all bit flags are taken into account while a binary representation of all 1 means that all flags would be ignored.

  • If it’s None then all flags are ignored

  • If it’s a string then it must be a , or + separated string of integers that bits to ignore. If the string starts with an ~ the integers are interpreted as the only flags to take into account.

Default is 0.

Returns:
masknumpy.ndarray of boolean dtype

The bitfield converted to a boolean mask that can be used for numpy.ma.MaskedArray or CCDData.

Examples

Bitfields (or data quality arrays) are integer arrays where the binary representation of the values indicates whether a specific flag is set or not. The convention is that a value of 0 represents a good value and a value that is != 0 represents a value that is in some (or multiple) ways considered a bad value. The bitfield_to_boolean_mask function can be used by default to create a boolean mask wherever any bit flag is set:

>>> import ccdproc
>>> import numpy as np
>>> ccdproc.bitfield_to_boolean_mask(np.arange(8))
array([False,  True,  True,  True,  True,  True,  True,  True]...)

To ignore all bit flags ignore_bits=None can be used:

>>> ccdproc.bitfield_to_boolean_mask(np.arange(8), ignore_bits=None)
array([False, False, False, False, False, False, False, False]...)

To ignore only specific bit flags one can use a list of bits flags to ignore:

>>> ccdproc.bitfield_to_boolean_mask(np.arange(8), ignore_bits=[1, 4])
array([False, False,  True,  True, False, False,  True,  True]...)

There are some equivalent ways:

>>> # pass in the sum of the "ignore_bits" directly
>>> ccdproc.bitfield_to_boolean_mask(np.arange(8), ignore_bits=5)  # 1 + 4
array([False, False,  True,  True, False, False,  True,  True]...)
>>> # use a comma seperated string of integers
>>> ccdproc.bitfield_to_boolean_mask(np.arange(8), ignore_bits='1, 4')
array([False, False,  True,  True, False, False,  True,  True]...)
>>> # use a + seperated string of integers
>>> ccdproc.bitfield_to_boolean_mask(np.arange(8), ignore_bits='1+4')
array([False, False,  True,  True, False, False,  True,  True]...)

Instead of directly specifying the bits flags to ignore one can also pass in the only bits that shouldn’t be ignored by prepending a ~ to the string of ignore_bits (or if it’s not a string in ignore_bits one can set flip_bits=True):

>>> # ignore all bit flags except the one for 2.
>>> ccdproc.bitfield_to_boolean_mask(np.arange(8), ignore_bits='~(2)')
array([False, False,  True,  True, False, False,  True,  True]...)
>>> # ignore all bit flags except the one for 1, 8 and 32.
>>> ccdproc.bitfield_to_boolean_mask(np.arange(8), ignore_bits='~(1, 8, 32)')
array([False,  True, False,  True, False,  True, False,  True]...)

>>> # Equivalent for a list using flip_bits.
>>> ccdproc.bitfield_to_boolean_mask(np.arange(8), ignore_bits=[1, 8, 32],
...                                  flip_bits=True)
array([False,  True, False,  True, False,  True, False,  True]...)