Output Bitmasks

PypeIt uses bitmasks to flag data for various reasons. For a primer on the general use of bitmasks, see the SDSS bitmasks primer.

For the underlying bitmask utility class used by PypeIt, see Bitmasks.

---

Spec2D Bits

In terms of the output data, the main bitmask you will encounter is in the Spec2D Output. The BPMMASK extension in these files contain the bad-pixel bitmask values accrued during the processing and reduction of the data. The main object that manages the bitmasks is ImageBitMask, which defines the following bits:

Bit Name	Bit Number	Decimal Value	Description
BPM	0	1	Component of the instrument-specific bad pixel mask
CR	1	2	Cosmic ray detected
SATURATION	2	4	Saturated pixel
MINCOUNTS	3	8	Pixel below the instrument-specific minimum counts
OFFSLITS	4	16	Pixel does not belong to any slit
IS_NAN	5	32	Pixel value is undefined
IVAR0	6	64	Inverse variance is undefined
IVAR_NAN	7	128	Inverse variance is NaN
EXTRACT	8	256	Pixel masked during local skysub and extraction
BADSCALE	9	512	Bad image rescaling operation (e.g., flat-field value <= 0)
STCKMASK	10	1024	All pixels masked in image stack
USER	11	2048	Pixel masked by user

Interpreting the bit values

You can construct the appropriate bitmask in two ways:

• (Recommended) Instantiate the bitmask directly:

  from pypeit.images.imagebitmask import ImageBitMask
  bm = ImageBitMask()
  

• Specifically for the spec2d* files, the names of the bits and their order is saved to the header. You can instantiate a generic BitMask from the header; however, it’s not clear how long this behavior will remain. To instantiate the relevant BitMask from the header:

  from astropy.io import fits
  from pypeit.bitmask import BitMask
  hdu = fits.open('spec2d_DE.20100913.22358-CFHQS1_DEIMOS_20100913T061231.334.fits')
  bm = BitMask(hdu[1].header['IMGBITM'].split(','))
  

With the BitMask or ImageBitMask instantiated, you can interpret the meaning of the BPMMASK extensions as follows:

• Use the flagged() method to produce a boolean array that selects pixels flagged with a given bit:

  extract_flag = bm.flagged(hdu['DET01-BPMMASK'].data, flag='EXTRACT')
  

• Use the same method to select multiple bits:

  process_flag = bm.flagged(hdu['DET01-BPMMASK'].data, flag=['BPM', 'CR', 'SATURATION'])
  

• Or select bits that are flagged for any reason:

  # You can use the `flagged` method for this
  any_flag = bm.flagged(hdu['DET01-BPMMASK'].data)
  # or equivalently
  _any_flag = hdu['DET01-BPMMASK'].data > 0
  

• To get the human-readable reason that any given value is flagged, use the flagged_bits() method. Currently this can only be used with a single bit value:

  print(bm.flagged_bits(hdu['DET01-BPMMASK'].data[0,0]))