rskysub: Sky subtract images using running mean or median

Package: proto

Usage

rskysub input output

Parameters

input

The list of input images to be sky subtracted in time of observation order.

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.

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.

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 scale = "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.

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 hmasks 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.

rescale = yes

Force recomputation of the individual input image scale factors even though they have been previously computed and stored in the keyword skyscale?

scale = "median"

The method used to compute the individual image scale factors. The options are:

none

The individual scale factors are all set to 1.0.

!<keyword>

The individual scale factors are all set to the value of the input image header keyword keyword.

median

The individual scale factors are set to 1 / median. The medians are estimated using the input masks imasks, input image section statsec, the minimum and maximum good data values lower and upper\R, the clipping factors fImaxiter, lnsigrej, and unsigrej and the histogram binning parameter binwidth.

@<file>

The individual image scale factors are read from the file file.

skyscale = "SKYSCALE"

The image header keyword containing the computed scaling factor. Skyscale is written to both the input and output images.

statsec = ""

The input image section used to compute the individual image scaling factors. Statsec is independent of the input image section if any.

lower = INDEF, upper = INDEF

The minimum and maximum input image good data values.

maxiter = 20

The maximum number of clipping iterations.

lnsigrej = 3.0, unsigrej = 3.0

The lower and upper side sigma clipping factors.

binwidth = 0.1

The histogram bin width in sigma used in estimating the median value.

resubtract = yes

Force recomputation and subtraction of the sky image even though it exists already ?

combine = "average"

The method used to create the sky images. The options are "average" and "median".

ncombine = 6

The default number of images used to create the sky images.

nmin = 3

The minimum number of images used to create the sky images.

nlorej = 0, nhirej = 0

The number of high and low side pixels to reject if combine is "average".

blank = 0.0

The value assigned to undefined output image pixels, i.e. those for which the corresponding sky image pixel is undefined.

skysub = "SKYSUB"

The sky subtraction processing keyword which is written to the output image when processing is complete.

holes = "HOLES"

The homes mask name keyword which is written to the output image if an output holes mask is created.

cache = yes

Cache the input images in memory if possible ?

verbose = yes

Print messages about the progress of the task ?

Description

RSKYSUB computes the average sky image for each image in the input image list inlist using a running mean or median technique and subtracts it from the input image to create the output sky subtracted images outlist. The input image list is assumed to be ordered by time of observation. If the input image masks list imasks 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 omasks and a list of holes masks hmasks.

The input masks imasks can be specified in a variety of ways as shown below.

       "" - 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

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 omasks 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 hmasks 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 inlist and stores it in the input image header keyword skyscale. If scale is "median" then the median of the input image pixels is computed using the input image masks imasks, the good data limits lower and upper, the clipping factors maxiter, lnsigrej, and unisgrej, and the histogram resolution parameter binwidth. The scaling factor is set to 1 / median. If scale is "none", "!<keyword>", or "@<file>" the individual scale factors are set to 1, read from the input image header keyword <keyword>, or from a file @<file> respectively. If rescale is yes and scale is "median" then the scaling computation is redone regardless of whether or not the skyscale 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 ncombine neighbor images using the algorithm specified by combine. If combine is average then the nlorej and nhirej 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 nmin 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 blank. The sky subtraction processing keyword skysub is written to the output image when sky subtraction is complete.

If cache is "yes" then RSKYSUB will attempt to buffer the active images in memory and will run significantly faster. If verbose = yes then the task prints messages about its actions as it goes along.

Examples

1. Sky subtract a list of 25 images without masking.

cl> rskysub @inlist @outlist maxiter=10 lnsigrej=5.0 unsigrej=5.0

2. Sky subtract the same list of 25 images with masking where the masks are assumed to be stored in the BPM keyword.

cl> rskysub @inlist @outlist imasks="!BPM" maxiter=10 lnsigrej=5.0 \
unsigrej=5.0

Time requirements

Bugs

See also

imcombine, imexpr