IRSCLEAN is all about making and using masks. There are three main kinds of masks that you will deal with in running IRSCLEAN:
4.1 RMASK: The Rogue Pixel Mask
Bad or "rogue" pixel masks used and created by IRSCLEAN are binary images with bad pixels indicated by the value 1 and normal pixels indicated by 0. These masks are for use within the IRSCLEAN distribution and are not interchangeable with the masks created by the IRS pipeline.
When we refer to an RMASK, we usually are talking about a previously-derived mask, stored as a fits file, that you will either edit or use to clean data (as opposed to a "found" or "user-defined" mask; see below).
One set of pre-derived campaign-based rogue masks are available on the Rogue Pixel Masks website. These masks are automatically installed with the IRSCLEAN distribution, under all_campaigns_roguemasks/. In this subdirectory there will be one mask per IRS module and campaign number. The file all_campaigns_roguemasks/campaigns.txt relates the campaign number (eg. IRS1) with the SSC campaign ID (eg. IRSX002500) that is stored in the fits header of your data files.
4.2 FMASK: The "Found" Mask
IRSCLEAN has a built-in algorithm for analyzing your input image and finding rogue pixels automatically. If you run IRSCLEAN's rogue-finding algorithm (using /getFmask) you are then allowed to edit the FMASK in Mask-Edit mode and save the mask to a FITS file for use later as an RMASK.
4.3 UMASK: The User-Defined Mask
You can specify an external function (using maskFunction) that will independently analyze your input image and find rogue pixels based on your own algorithm. This mask can also be edited in Mask-Edit mode and saved to a FITS file for use later as an RMASK.
4.4 BMASK: The Pipeline BCD Mask
The final products of the IRS Basic Calibrated Data pipeline include the processed observation, bcd.fits, the corresponding uncertainty plane, func.fits, and the BCD Mask, bmask.fits. The BMASK file is a 16-bit integer mask with bits set based on the status of BCD image pixels (listed in Table 4.1; for more information, see the IRS Instrument Handbook).
Table 4.1: Pipeline bmask bits
Bit #
Condition
0
Cleaned with IRSCLEAN
1
Latent-image flag
2
Digital saturation detected along the ramp (bit 3 in dmask).
3
RADHIT detection along ramp (bit 9 in dmask).
4
Non-linearity correction could not be computed (bit 12 in dmask).
5
Not used
6
Droop removed using questionable value (bit 6 in dmask).
7
Flat-field applied using questionable value (FLATAP)
8
Flat-field could not be applied (FLATAP)
9
Stray-light removal or cross-talk correction not applied
10
At least one sample exceeds 280000 e−. (bit 13 in dmask).
11
Data missing in downlink (bit 14 n dmask).
12
Only one usable plane
13
No usable planes
14
Pixe masked in pmask
15
Reserved: sign bit
The BMASK file determines which pixels to ignore during IRSCLEAN processing. Pixels that are “fatally” masked are colored blue during rogue mask editing. The default fatal value is decimal 28800 (bits 7 and 12-14). This can be adjusted using either the keyword bMaskVal or bMaskBits. These keywords allow you to enter fatal BMASK bits as either a single 16-bit number expressing the sum of the active bits (eg., bMaskVal=28800), or as a vector of the bits to be set to fatal (eg., bMaskBits=[7,12,13,14]). A fatally masked pixel can be toggled into a rogue pixel and cleaned (not recommended), in which case, IRSCLEAN will automatically update the BMASK for use in spectrum extraction with SPICE.
NOTE: Earlier versions of IRSCLEAN allowed the use of the BMASK as a bad pixel mask, but this led to unstable results. The current approach is to ignore fatally masked pixels.
NOTE: If a pixel is cleaned using IRSCLEAN, bit 0 of the pixel’s BMASK is turned on.
4.5 OMASK: The Order Mask
Each IRS detector array images a set of spectral orders. The mask that specifies which pixels are in which order is given by the order mask, a file produced by the SSC, and delivered with the IRSCLEAN distribution in the subdirectory cal/. Each pixel in the order mask file has a number specifying which order it belongs to. Order mask pixels that are not in an order have the value 0. See Appendix 2 for more information on the locations of the IRS spectral orders. The order mask defines which pixels are cleaned by IRSCLEAN. The default order mask is the “narrow” order mask. You can select a “wide” order mask by setting the keyword /wide_omask at the IRSCLEAN command line. You can also specify no order mask by setting /noOrderMask. This allows you to clean any pixel on the array. Finally, you can define your own order mask with an external file using the keyword orderMask_File=.
4.6 UNCLEAN_MASK: The Mask of Unsuccsessfully Cleaned Pixels
Not all pixels are always successfully cleaned by IRSCLEAN. This is usually due to one of three reasons:
1. The pixel does not need to be cleaned, i.e., its "cleaned" value is nearly equal to the original value.
2. There are not enough "good" pixels (pixels not in the bad pixel mask) in surrounding rows to be used to build the row profile.
3. The average row profile is too noisy.
When one or more pixels are not cleaned, IRSCLEAN will produce a special unclean_mask.fits file for each processed data file (as of version 1.9). Similar to the rogue mask, the "unclean mask" is an image of 1's and 0's indicating whether or not a pixel has been successfully cleaned.
See the hint on "a second pass at cleaning data using the unclean_mask file" in the Appendix.
