STScI Logo
STScI Logo


What's New

Resetting DQ Bits [Added: 5 June 2009]

Problems with alignment between the images being combined by MultiDrizzle will result in the mis-identification of cosmic-rays in the image's DQ array. Parameters inconsistent with the characteristics of the observation may also result in mis-identification of cosmic rays. Those incorrectly flagged pixels need to have their value in the DQ array reset before running MultiDrizzle again with improved settings or alignment. Parameters in MultiDrizzle will allow it to use those previously identified pixels as if they were good, however, the DQ array will still be updated to reflect both the old and newly identified cosmic-rays. This can result in a DQ array which does not accurately represent the best determination of the quality of the pixels. The DQ arrays for input images can be edited to reset the bit value used by MultiDrizzle to flag cosmic-rays so that the DQ array will only flag those cosmic-rays detected by a subsequent run of MultiDrizzle. A couple of simple routines can be used to reset any bit value or combination of bit values in the DQ array, one for use under IRAF and one for use under Python.

Primer on DQ arrays and bit values

The DQ array keeps track of several types of problems that could affect the science quality of the pixel in the image. They are set up as 16-bit integer arrays with each of the 15 bits (the 16th bit is used to represent the sign of the integer) representing a different type of problem with the pixel. Each instrument has a table documenting what problems are flagged with various bits in the DQ array. MultiDrizzle, by default, uses the bit value of 4096 to flag pixels which have been identified as being affected by cosmic-rays. Other problems may affect that pixel as well resulting in a integer value for that pixel being greater than 4096. The process of resetting a single bit value in the array involves checking each pixel to see whether or not that pixel has the specified bit set to 1 already, and if so, resetting it to 0.

Using IRAF to reset bits in a DQ array

Anyone who has IRAF installed can use the following pair of interactive commands (modified to name their own input files) to reset all pixels flagged with the 4096 bit.
  imexpr "a - (a & (32768 - 4096))" output_dq.fits a="input_file_flt.fits[dq,1]"
  imcopy output_dq.fits[*,*] input_file_flt.fits[dq,1][*,*]
The first line creates a new file output_dq.fits which contains the DQ array from the input image, given in this example by input_file_flt.fits[dq,1], after resetting the 4096 bit to 0. If you want to reset other bits, replace the value of 4096 in the example with the integer corresponding to the sum of all the bits you want to reset. The second line then copies the newly updated DQ array back into the original input image, replacing the previous values of the DQ array. You could verify that the new array worked as expected before replacing the input array, if you are not sure that the bit value was specified correctly in the first command.

Using Python to reset bits in a DQ array

The operation of resetting bits in a DQ array using Python can take advantage of bitwise operators in numpy under Python to directly reset the desired bits. This Python function will allow a user to reset the desired bits in any or all integer extensions, like a DQ array, in-place. Simply save it into a directory on your PYTHONPATH and import it. If you do not already have a directory for your own custom Python modules, you can create one, save this module in that directory, then add it to your PYTHONPATH in a couple of different ways. A new directory can always be added to the PYTHONPATH environment variable, with syntax for doing so under *nix operating Systems (including Mac OS X) of:
  setenv PYTHONPATH /new/directory/for/your/module:{$PYHTONPATH}
Alternatively, you can add a new directory immediately to any Python session using the built in 'sys.path' list with syntax such as:
  import sys
This particular command will add this new directory as the last place Python will look for a module by placing it in the list as position -1 to avoid loading this module (or any other module in that directory) instead of system installed modules of the same name. You can choose, of course, to add your directory to the path list at any position that is appropriate for your use or environment.

The new module will allow the user to reset the 4096 bit in all the DQ arrays of the input file input_file_flt.fits using the commands:

  import resetbits
Additional help with the syntax and usage of this function can be obtained using:
WARNING: This simple function WILL OVERWRITE the original DQ array of the input image with the new version that has had the specified bits reset to 0.

Using this module for a list of images

This module was written to explicity process only a single FITS image at a time. A whole list of images can be processed interactively using simple Python tools. One of the simplest ways of looping over a list of images interactively, in this case all FLT images in the current directory, can be run using:
  import glob,resetbits
  for img in glob.glob("*q_flt.fits"): resetbits.reset_dq_bits(img,4096)
Any filename specifier understood by the glob module can be used in this way to process a custom list of images.

Copyright  | Help