.help cosmicrays Dec87 noao.imred.ccdred .ih NAME cosmicrays -- Detect and replace cosmic rays .ih USAGE cosmicrays input output .ih PARAMETERS .ls input List of input images in which to detect cosmic rays. .le .ls output List of output images in which the detected cosmic rays will be replaced by an average of neighboring pixels. If the output image name differs from the input image name then a copy of the input image is made with the detected cosmic rays replaced. If no output images are specified then the input images are modified in place. In place modification of an input image also occurs when the output image name is the same as the input image name. .le .ls badpix = "" List of bad pixel files to be created, one for each input image. If no file names are given then no bad pixel file is created. The bad pixel file is a simple list of pixel coordinates for each replaced cosmic ray. This file may be used in conjunction with \fBbadpixelimage\fR to create a mask image. .le .ls ccdtype = "" If specified only the input images of the desired CCD image type will be selected. .le .ls threshold = 25. Detection threshold above the mean of the surrounding pixels for cosmic rays. The threshold will depend on the noise characteristics of the image and how weak the cosmic rays may be for detection. A typical value is 5 or more times the sigma of the background. .le .ls fluxratio = 2. The ratio (as a percent) of the mean neighboring pixel flux to the candidate cosmic ray pixel for rejection. The value depends on the seeing and the characteristics of the cosmic rays. Typical values are in the range 2 to 10 percent. .le .ls npasses = 5 Number of cosmic ray detection passes. Since only the locally strongest pixel is considered a cosmic ray, multiple detection passes are needed to detect and replace multiple pixel cosmic ray events. .le .ls window = 5 Size of cosmic ray detection window. A square window of either 5 by 5 or 7 by 7 is used to detect cosmic rays. The smaller window allows detection in the presence of greater background gradients but is less sensitive at discriminating multiple event cosmic rays from stars. It is also marginally faster. .le .ls interactive = yes Examine parameters interactively? A plot of the mean flux within the detection window (x100) vs the flux ratio (x100) is plotted and the user may set the flux ratio threshold, delete and undelete specific events, and examine specific events. This is useful for new data in which one is uncertain of an appropriate flux ratio threshold. Once determined the task need not be used interactively. .le .ls answer This parameter is used for interactive queries when processing a list of images. The responses may be "no", "yes", "NO", or "YES". The upper case responses permanently enable or disable the interactive review while the lower case reponses allow selective examination of certain input images. .le .ih OTHER PARAMETERS There are other parameters which may be defined by the package, as is the case with \fBccdred\fR, or as part of the task, as is the case with standalone version in the \fBgeneric\fR package. .ls verbose If yes then a time stamped log of the operation is printed on the standard output. .le .ls logfile If a log file is specified then a time stamped log of the operation is recorded. .le .ls plotfile If a plot file is specified then the graph of the flux ratio (x100) vs the mean flux (x100) is recorded as metacode. This may be spooled or examined later. .le .ls graphics = "stdgraph" Interactive graphic output device for interactive examination of the detection parameters. .le .ls cursor = "" Interactive graphics cursor input. If null the graphics display cursor is used, otherwise a file containing cursor input may be specified. .le .ls instrument The \fBccdred\fR instrument file is used for mapping header keywords and CCD image types. .le .ih CURSOR COMMANDS .nf d Mark candidate for replacement (applys to '+' points) q Quit and replace the selected pixels r Redraw the graph s Make a surface plot for the candidate nearest the cursor t Set the flux ratio threshold at the y cursor position u Mark candidate to not be replaced (applys to 'x' points) w Adjust the graph window (see \fBgtools\fR) .fi There are no colon commands except those for the windowing options (type :\help or see \fBgtools\fR). .ih DESCRIPTION Cosmic ray events in each input image are detected and replaced by the average of the four neighbors. The replacement may be performed directly on the input image if no output image is specified or if the output image name is the same as the input image name. If a new image is created it is a copy of the input image except for the replaced pixels. The processing keyword CRCOR is added to the output image header. Optional output includes a log file to which a processing log is appended, a verbose log output to the standard output (the same as that in the log file), a plot file showing the parameters of the detected cosmic ray candidates and the flux ratio threshold used, and a bad pixel file containing the coordinates of the replaced pixels. The bad pixel file may be used for plotting purposes or to create a mask image for display and analysis using the task \fBbadpiximage\fR. This bad pixel file will be replaced by the IRAF bad pixel facility when it becomes available. If one wants more than a simple mask image then by creating a different output image a difference image between the original and the modified image may be made using \fBimarith\fR. This task may be applied to an image previously processed to detect additional cosmic rays. A warning will be given (because of the CRCOR header parameter) and the previous processing header keyword will be overwritten. The cosmic ray detection algorithm consists of the following steps. First a pixel must be the brightest pixel within the specified detection window (either 5x5 or 7x7). The mean flux in the surrounding pixels with the second brightest pixel excluded (which may also be a cosmic ray event) is computed and the candidate pixel must exceed this mean by the amount specified by the parameter \fIthreshold\fR. A plane is fit to the border pixels of the window and the fitted background is subtracted. The mean flux (now background subtracted) and the ratio of this mean to the cosmic ray candidate (the brightest pixel) are computed. The mean flux (x100) and the ratio (x100) are recorded for interactive examination if desired. Once the list of cosmic ray candidates has been created and a threshold for the flux ratio established (either by the parameter \fIfluxratio\fR or modified interactively) the pixels with ratios below the threshold are replaced in the output by the average of the four neighboring pixels (with the second strongest pixel in the detection window excluded if it is one of these pixels). Additonal pixels may then be detected and replaced in further passes as specified by the parameter \fInpasses\fR. Note that only pixels in the vicinity of replaced pixels need be considered in further passes. The division between the peaks of real objects and cosmic rays is made based on the flux ratio between the mean flux (excluding the center pixel and the second strongest pixel) and the candidate pixel. This threshold depends on the point spread function and the distribution of multiple cosmic ray events and any additional neighboring light caused by the events. This threshold is not strongly coupled to small changes in the data so that once it is set for a new type of image data it may be used for similar images. To set it initially one may examine the scatter plot of the flux ratio as a function of the mean flux. This may be done interactively or from the optional plot file produced. When the interactive flag is set the user is queried for each image. Responses may be made for specific images or for all images by using lower or upper case answers respectively. When the parameters are examined interactively the user may change the flux ratio threshold ('t' key). Changes made are stored in the parameter file and, thus, learned for further images. Pixels to be deleted are marked by crosses and pixels which are peaks of objects are marked by pluses. The user may explicitly delete or undelete any point if desired but this is only for special cases near the threshold. In the future keys for interactive display of the specific detections will be added. Currently a surface plot of any candidate may be displayed graphically in four 90 degree rotated views using the 's' key. Note that the initial graph does not show all the points some of which are clearly cosmic rays because they have negative mean flux or flux ratio. To view all data one must rewindow the graph with the 'w' key or ":/" commands (see \fBgtools\fR). .ih EXAMPLES 1. To replace cosmic rays in a set of images ccd*: .nf cl> cosmicrays ccd* new//ccd* ccd001: Examine parameters interactively? (yes): [A scatter plot graph is made. One can adjust the threshold.] [Looking at a few points using the 's' key can be instructive.] [When done type 'q'.] ccd002: Examine parameters interactively? (yes): NO [No further interactive examination is done.] .fi After cleaning one typically displays the images and possibly blinks them. A difference image or mask image may also be created. 2. To create a mask image a bad pixel file must be specified. In the following we replace the cosmic rays in place and create a bad pixel file and mask image: .nf cl> cosmicrays ccd001 ccd001 badpix=ccd001.bp cl> badpiximage ccd001.bp ccd001 ccd001bp .fi .ih SEE ALSO badpixelimage gtools .endhelp