; All inputs are optional. The program queries the user for
; anything it needs.
;
;
;
; OPTIONAL INPUTS: dataFile - File with IRS image data (droop, rsc, bcd,
; f2ap, bksub, or coa2d) to be used to produce
; the rogue pixel mask. You will have
; the option to clean this file using
; the mask that you develop. If not
; given, a file picker widget will
; appear. If the filename is a standard
; IRS pipeline name, then IRSCLEAN will
; search for associated bmask and
; uncertainty files.
;
;
; KEYWORD PARAMETERS:
;;;;;;;; INPUT MASKS
; inRmask_File - File name(s) for the input rogue
; pixel mask. This mask will be
; combined with other rogue masks
; derived from getFmask
; and /NAN, and will be editable
; during the mask-editing stage.
; If you do not set getFmask,
; or CampaignRMask,
; then you will be queried
; for inRmask_File (you can cancel
; out of this dialog and start
; mask-editing with no mask).
; Can be a list of file names.
; /CampaignRMask - Set this keyword to
; automatically load the
; campaign rogue mask
; corresponding to your
; data. IRSCLEAN will
; combine this with other
; rogue pixel masks, if
; keywords getFmask,
; inRmask_File, or /NaN are set.
; Bmask_File - The pipeline bmask, a 16-bit
; image. If no file is given, IRSCLEAN will
; automatically search for the
; bmask associated with the
; input image file using the
; standard SSC naming convention. During
; mask-editing, bmask-ed pixels
; (pixels with appropriate
; bmask bits as given in
; bmaskVal) are highlighted in
; blue. These pixels will not
; be considered in rogue
; finding, nor will they be
; used in computing the cleaned
; pixel values. You can turn a
; bmask-ed pixel into a rogue
; pixel (and back) by clicking
; on it during mask-editing.
; bMaskVal - An integer representation of
; the bmask bits for which a pixel is
; removed from consideration.
; Default is 28800 (bits
; 7,12-14).
; These pixels will be
; highlighted in blue during
; mask-editing. To avoid
; considering the bmask, set
; bMaskVal to zero (0). If both bMaskVal
; and bMaskBits are set, then bMaskVal has
; precedence.
; bMaskBits - Explicit listing of
; the bmask bits for which a pixel is
; removed from consideration.
; Default is [7,12,13,14]. 7,12-14).
; These pixels will be
; highlighted in blue during
; mask-editing. To avoid
; considering the bmask, set
; bMaskVal to zero (0).
; /NaN - set this keyword to add NaN pixels to the rogue mask
; orderMask_File - Name of file to use to
; specify the spectral orders. If not given
; (and neither /wide_OMask or /noOrderMask are set) then use
; the default (narrow) order mask delivered with IRSCLEAN.
; /wide_OMask - Use the wide order mask delivered with IRSCLEAN.
;
; /noOrderMask - Set this keyword to define
; the entire image as "Order 1" and ignore the
; need for an order mask. Useful if you want
; to create masks of pixels in between
; orders,or construct masks using non-IRS
; images. Be warned that results of cleaning may not be reliable.
; /peakUp - Set this keyword to enable
; mask-finding and cleaning of the IRS
; peak-up arrays (only valid for Short Low
; data).
;*******************************
;;;;;; ROGUE-FINDING KEYWORDS
; getFmask - Use a rogue-finding algorithm
; to find rogue pixels in your
; dataFile. You can set this keyword
; to 1 (or invoke /getFmask) to find rogues
; using the standard algorithm used
; in IRSCLEAN versions up to 1.9
; (also called the "complex"
; algorithm).
; As of IRSCLEAN 2.0, you can also run an
; alternative "basic" algorithm by
; setting getFmask=2.
; In summary set getFmask=
; 1 - Hierarchical Iterative method (same as in
; IRSCLEAN versions up to
; 1.9). Sigma thresholding
; using first two levels of
; multi-median transform,
; allowing clusters of
; rogues. (Equivalent to
; /getFmask.)
; 2 - Double Unsharp-Mask
; Flattening method.
; Unsharp-mask of image,
; followed by a second
; unsharp-mask of each
; column (flattening).
; NOISE_FLOOR sets the
; minimum nsigma baseline to be considered signal, whereas ROGUE_THRESH sets the
; unsharp-mask of Simple
; sigma thresholding of
; first level of
; multi-median. transform, with
; rejection of clusters of
; three or more pixels.
; /ABS_VAL - Search for positive and negative
; rogues. Normally the image is
; thresholded such that candidates
; with values greater than a
; certain multiple of sigma are
; considered rogues. This method
; allows for a dual thresholding
; of both the image and its
; inverse.
; /NEGATIVE_ONLY - Search only for negative
; rogues. This is useful
; when the background
; observation had a lot of
; rogues that didn't
; cancel out in bg
; subtraction.
; AGGRESSIVE - A number between -2.0 and +2.0
; specifying the sigma threshold
; above which a candidate pixel is
; considered a rogue (see
; online documentation
; for details). If getFmask=1,
; this number also defines the
; number of rogue-finding
; iterations and whether or not
; clusters of pixels are allowed
; in the rogue mask. Default is AGGRESSIVE=0.
; ROGUE_THRESH - The minimum sigma
; for a rogue. If getFmask=2,
; then setting ROGUE_THRESH=0 and NOISE_FLOOR=0
; will result in all pixels being detected as rogues.
; This keyword is interchangeable with AGGRESSIVE:
; ROGUE_THRESH = 2.0 + 2.0 * (1.0-AGGRESSIVE) > 0
; NOISE_FLOOR - When getFmask=2 is set, the minimum sigma to be
; considered signal.
; Alternately, this is the multiple of sigma in the
; small-scale component image of the multi-median
; transform below which a pixel value is
; considered noise and removed from consideration.
; Default is NOISE_SIGMA=1.
; maskFunction - the name of a user-supplied
; function to find rogue
; pixels. This function allows
; as inputs the original fits
; data, the order mask image,
; and the keywords /ABS_VAL,
; /NEGATIVE_ONLY, and
; AGGRESSIVE. The result of
; this function will be combined
; with any other rogue masks
; input (inRmask_File) or
; derived (via /getFmask). See
; documentation for details.
; orders - List of orders to detect
; rogues in, under /getFmask. Setting this
; keyword results in the independent
; analysis of each of the orders given in
; the list. See documentation for the
; order numbering and layout of each IRS
; module.
;*******************************
;;;;;;;;;;;;;;OUTPUT CONTROL
;
; outRmask_File - Output rogue mask file. Set
; this keyword to the name of the file for
; storing the rogue mask
; that has been created. If not
; given and autoSave is not set, you will be queried.
; outClean_File - Output cleaned data file from
; Stage 1.
; Set this keyword to the name of the file for
; storing the cleaned image that corresponds to
; the input image (dataFile). If not given,
; and /autoSave is not set, you will be queried.
; filesToClean - List of files (*.fits) and/or
; file lists (*.txt) to which the derived bad
; pixel mask will be applied. A string array.
; List files have one FITS file per line. The
; clean data will be saved in files with
; similar names, but with "_clean" inserted
; before ".fits". If not given, and /noStage2 is
; not set, you will be queried.
;;;;;;;;;;PROGRAM FLOW
; /noMaskEdit - Set this keyword to skip
; interactive editing of the
; rogue mask.
; /autoSave - Set this keyword to
; automatically save the rogue
; mask and cleaned image from
; Stage 1, using a best guess at
; the file name (unless
; outRmask_File and/or
; outClean_File are set)
; /noStage2 - Set this keyword to skip
; Stage 2 of the process (multiple file
; cleaning using the Stage 1
; mask)
;;;;;;;;;;MISCELLANEOUS
; Directory - Set this keyword to the initial
; working directory (will change if you move
; to another directory in file picker).
; Default is current IDL working directory
; (usually the directory that you start IDL
; in unless you have changed directories during your session).
; dataRange - set this keyword to the range
; in data values over which to scale the
; images for display (a 2-element vector). If
; not given or set to 0
; (1-element scalar), the display
; will be scaled to the min and
; max of the image. Setting
; dataRange=[0,0] will allow you
; to interactively choose the
; display range prior to mask editing.
; WinSize - This keyword (a 2-element
; vector) sets the x,y size of the image
; window (a small pad will be added for
; display purposes). Default is
; [768,768]. Maximum is [2048,2048].
; colorNames - Two element string array giving
; the names of the colors for the
; overlay symbols drawn on rogue
; and bmask pixels during the
; mask editing stage. Default is
; ['red','blue']. Available color names
; can be found by typing
; IDL> print,FSC_COLOR(/names)
; Or to visually choose a color
; name, type
; IDL> print,PICKCOLORNAMES()
;
; /Help - Print the irsclean_mask.pro documentation header
;
; OUTPUTS: All input arguments, if passed as named variables, will
; be returned with their current values as of the
; termination of the program. In particular, file
; names if passed as variables that equal the
; null string (''), or the dataRange keyword if
; passed as a variable that equals [0,0], will
; return in the respective variables the actual
; values chosen during execution of the program.
;
; On exit, IRSCLEAN prints the command line that
; you could have typed to obtain the same result,
; incorporating all changes to input arguments and
; other choices made during your session.
;
;
; OPTIONAL OUTPUTS: If set, Keyword DIRECTORY will be reset to the final working directory.
;
;
; COMMON BLOCKS:
; IRSCLEAN_SHARE contains image display scaling information derived from IRSCLEAN_WINDOWIMAGE.
;
;
; SIDE EFFECTS: This program uses interpolation to edit the values of "rogue" pixels and their associated uncertainties.
; It also resets the bmask for these pixels to zero.
;
;
; RESTRICTIONS: Currently runs only on 128x128 pixel images.
;
;
;
; PROCEDURE:
;
;
;
; EXAMPLE:
;
;
;
; MODIFICATION HISTORY:
;
; Copyright (C) <2011> <J. Ingalls/SSC>
; This program is free software: you can redistribute it and/or modify
; it under the terms of the GNU General Public License as published by
; the Free Software Foundation, either version 3 of the License, or
; any later version.
;
; This program is distributed in the hope that it will be useful,
; but WITHOUT ANY WARRANTY; without even the implied warranty of
; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
; GNU General Public License for more details.
;
; You should have received a copy of the GNU General Public License
; along with this program. If not, see <http://www.gnu.org/licenses/>.
;
;-
[1] The image display scaling widget is based on windowimage.pro by David Fanning.
[2] Starck, J.-L, Murtagh, F., & Louys, M. 1995, in Astronomical Data Analysis Software and Systems IV, eds. R. A. Shaw, H. E. Payne, and J. J. E. Hayes, ASP Conf. Ser. Vol 77
[3] Starck, J.-L., Bijaoui, A., Valtchanov, I., & Murtagh, F. 2000, A&A Supp., 147, 139
