.help rskysub Sep01 proto .ih NAME rskysub -- sky subtract images using running mean or median .ih USAGE rskysub input output .ih PARAMETERS .ls input The list of input images to be sky subtracted in time of observation order. .le .ls output The list of output sky subtracted images. The number of output images must equal the number of input images. If output is "default", "dir$default", or "dir$" then for every input image an output image called "dir$image.sub.?" is created, where "dir$" is the optional directory specification, "image" is the root input image name, and "?" is the next available version number. .le .ls imasks = "" The optional list of input image masks. The input image masks are assumed to consist of 0's in good pixel regions and > 0 integer values elsewhere. The number of input images masks must be 0, 1, or equal to the number of input images. If imasks is "default", "dir$default", or "dir$" then for every input image a default input image mask called "dir$image.obm.?" is searched for, where "dir$" is the optional directory specification, "image" is the root input image name, and "?" is the highest available version number. .le .ls omasks = "" The optional list of output masks. If output masks are defined they are used to created the sky image in place of the input masks. The output masks are a combination of the original input mask and pixels masked during the input image scale factor computation and consist of 0's in good data regions and 1's elsewhere. Output masks are only computed if \fIscale\fR = "median". The number of output masks must be 0 or equal to the number of input images. If imasks is "default", "dir$default", or "dir$" then for every input image an output mask image called "dir$image.skm.?" is created, where "dir$" is the optional directory specification, "image" is the root input image name, and "?" is the next available version number. .le .ls hmasks = "" The list of output holes masks. The holes masks defined bad pixels in the output images, i.e. those for which the underlying sky image was undefined. Holes masks are created only if \fIhmasks\fR is defined and there is at least 1 undefined sky image pixel in the output image. Holes masks contain 0's in undefined sky regions and 1's elsewhere. If hmasks is "default", "dir$default", or "dir$" then for every input image an output mask image called "dir$image.hom.?" is created, where "dir$" is the optional directory specification, "image" is the root input image name, and "?" is the next available version number. .le .ls rescale = yes Force recomputation of the individual input image scale factors even though they have been previously computed and stored in the keyword \fIskyscale\fR? .le .ls scale = "median" The method used to compute the individual image scale factors. The options are: .ls none The individual scale factors are all set to 1.0. .le .ls ! The individual scale factors are all set to the value of the input image header keyword \fIkeyword\fR. .le .ls median The individual scale factors are set to 1 / median. The medians are estimated using the input masks \fIimasks\fR, input image section \fIstatsec\fR, the minimum and maximum good data values \fIlower\fR and \fIupper\R, the clipping factors \fImaxiter\fR, \fIlnsigrej\fR, and \fIunsigrej\fR and the histogram binning parameter \fIbinwidth\fR. .le .ls @ The individual image scale factors are read from the file \fIfile\fR. .le .le .ls skyscale = "SKYSCALE" The image header keyword containing the computed scaling factor. \fISkyscale\fR is written to both the input and output images. .le .ls statsec = "" The input image section used to compute the individual image scaling factors. Statsec is independent of the input image section if any. .le .ls lower = INDEF, upper = INDEF The minimum and maximum input image good data values. .le .ls maxiter = 20 The maximum number of clipping iterations. .le .ls lnsigrej = 3.0, unsigrej = 3.0 The lower and upper side sigma clipping factors. .le .ls binwidth = 0.1 The histogram bin width in sigma used in estimating the median value. .le .ls resubtract = yes Force recomputation and subtraction of the sky image even though it exists already ? .le .ls combine = "average" The method used to create the sky images. The options are "average" and "median". .le .ls ncombine = 6 The default number of images used to create the sky images. .le .ls nmin = 3 The minimum number of images used to create the sky images. .le .ls nlorej = 0, nhirej = 0 The number of high and low side pixels to reject if \fIcombine\fR is "average". .le .ls blank = 0.0 The value assigned to undefined output image pixels, i.e. those for which the corresponding sky image pixel is undefined. .le .ls skysub = "SKYSUB" The sky subtraction processing keyword which is written to the output image when processing is complete. .le .ls holes = "HOLES" The homes mask name keyword which is written to the output image if an output holes mask is created. .le .ls cache = yes Cache the input images in memory if possible ? .le .ls verbose = yes Print messages about the progress of the task ? .le .ih DESCRIPTION RSKYSUB computes the average sky image for each image in the input image list \fIinlist\fR using a running mean or median technique and subtracts it from the input image to create the output sky subtracted images \fIoutlist\fR. The input image list is assumed to be ordered by time of observation. If the input image masks list \fIimasks\fR is defined then the input image pixels in the bad pixel regions are removed from the sky statistics and sky image computation. RSKYSUB optionally creates a list of output pixel masks \fIomasks\fR and a list of holes masks \fIhmasks\fR. The input masks \fIimasks\fR can be specified in a variety of ways as shown below. .nf "" - empty mask, use all the pixels EMPTY - empty mask, use all the pixels !KEYWORD - use mask specified by header keyword KEYWORD !^KEYWORD - use inverse of mask specified by header keyword KEYWORD mask - use specified mask ^mask - use inverse of specified mask .fi In all cases the mask values are assumed to be 0 in good data regions and non-zero in rejected data regions. The input masks may in pixel list, e.g. ".pl" format, or any supported integer image format, e.g. ".imh", ".fits", etc. The optional output pixel masks \fIomasks\fR are a combination of the input image masks and the scaling factor computation masks. They consist entirely of 0's and 1's with 0's defining the good data regions. The optional output holes masks \fIhmasks\fR which specify those pixels in the output images which are undefined consist entirely of 1's and 0's with 0's defining the holes. Before beginning the sky subtraction step RSKYSUB computes a scaling factor for each individual input image in \fIinlist\fR and stores it in the input image header keyword \fIskyscale\fR. If \fIscale\fR is "median" then the median of the input image pixels is computed using the input image masks \fIimasks\fR, the good data limits \fIlower\fR and \fIupper\fR, the clipping factors \fImaxiter\fR, \fIlnsigrej\fR, and \fIunisgrej\fR, and the histogram resolution parameter \fIbinwidth\fR. The scaling factor is set to 1 / median. If \fIscale\fR is "none", "!", or "@" the individual scale factors are set to 1, read from the input image header keyword \fI\fR, or from a file \fI@\fR respectively. If \fIrescale\fR is yes and \fIscale\fR is "median" then the scaling computation is redone regardless of whether or not the \fIskyscale\fR keyword is present in the input image header. RSKYSUB computes the sky image for each input image by multiplying each input image by the value of its scaling factor and then computing the combination of \fIncombine\fR neighbor images using the algorithm specified by \fIcombine\fR. If \fIcombine\fR is average then the \fInlorej\fR and \fInhirej\fR lowest and highest pixels are rejected from the stack to be combined. For example if the number of input images is 25 and ncombine is 6 then images 2-4 are used to compute the sky image for image 1, images 10-12 and 14-16 are used to compute the sky for image 13, and images 22-24 are used to compute the sky image for image 25. There must be a minimum of \fInmin\fR neighbor images or the sky image will not be computed. If the input masks are defined then pixels in bad regions are also rejected from the final sky image computation. Undefined output image pixels, i.e. those for which the corresponding sky image pixel is undefined, are assigned the value \fIblank\fR. The sky subtraction processing keyword \fIskysub\fR is written to the output image when sky subtraction is complete. If \fIcache\fR is "yes" then RSKYSUB will attempt to buffer the active images in memory and will run significantly faster. If \fIverbose\fR = yes then the task prints messages about its actions as it goes along. .ih EXAMPLES 1. Sky subtract a list of 25 images without masking. .nf cl> rskysub @inlist @outlist maxiter=10 lnsigrej=5.0 unsigrej=5.0 .fi 2. Sky subtract the same list of 25 images with masking where the masks are assumed to be stored in the BPM keyword. .nf cl> rskysub @inlist @outlist imasks="!BPM" maxiter=10 lnsigrej=5.0 \ unsigrej=5.0 .fi .ih TIME REQUIREMENTS .ih BUGS .ih SEE ALSO imcombine, imexpr .endhelp