rctcom - Combining the images listed in a file

Usage:

rctcom rctcom_parfile

Rctcom consists of a number of different program units designed to combine (e.g., average) a number of images. Typically it would be used to produce a calibration image by averaging a list of flatfield or bias exposures.

There are two independent versions of software to which the command rctcom may refer:

1. One is the IRAF-based set of scripts consisting of the short Perl script rctcom.pl and the IRAF shell script rctcom.cl. The purpose of rctcom.pl is to provide a user interface to rctcom.cl, which actually performs the combining operations. In this case, rctcom is analogous to (and uses) the IRAF task imcombine. To run this version of rctcom, it is best to create a symbolic link called rctcom which points to rctcom.pl. 2. The alternative is a FITSIO-based fortran program called rctcom.f which, when compiled, creates the executable rctcom. It is used in the same way as the IRAF version, but might not be as forgiving. The fortran version is used if the IRAF version does not work.

Whichever version is used, rctcom takes the name of a parameters file as its argument. One of the parameters set in this file supplies the name of a file which lists the images to be combined. Rctcom performs the following operations: 1) if requested, each input image is scaled by a factor so that its count level is comparable to the other images in the list, 2) if requested, pixels whose values are higher or lower in some manner relative to the values of the same pixels in the other images on the list are rejected, 3) the images are combined by taking their average or median, and 4) the combined image may be normalized so that its mean is 1. The parameters file (a simple text file) can exist in the user's current directory or anywhere else on the system if the full pathname is given. The 13 parameters, in the order they appear in the parameters file, are as follows:

1. indir

(the input directory) is the name of the directory containing the images to be reduced. It must be either a full pathname or the string './' if rctcom is to be invoked while in the input directory.

2. infiles

is the name of a file that lists the names of the FITS images to be combined. The image names are given one per line in this file. There should be no blank lines in this file and only simple filenames (not full pathnames) should be given. Be wary of blank lines at the end of this file!

3. outdir

(the output directory) is the name of the directory where the combined image is to be written. Like indir, this parameter must be either a full pathname or the string './'.

4. outfile

is the name of the output (combined) image. It should be a simple filename (not having a full pathname). If a file by this name already exists, rctcom will quit and not overwrite it.

5. scaletype

is the method used to find factors that are used to scale pixel values in the individual images before deviant pixels are rejected and the images combined. The allowed values are 'none', 'median' and 'mean'. If you're using the IRAF version of rctcom, there's the additional value of 'mode'. If scaletype is set to something other than 'none', scaling factors are calculated so that each scaled image will have the same mode, median, or mean.

6. combtype

is the method used to combine the images. It is either 'average' or 'median'.

7. rejtype

is the method used to reject deviant pixels in a group of images before combining them. Pixel rejection is done after the images have been scaled. The allowed values are 'none', 'minmax', and 'sigclip'. If minmax rejection is chosen, a specific number of the highest and lowest valued pixels in the list of images is rejected. The number of highest and lowest pixels to be rejected are given by the parameters numhigh and numlow. The user is responsible for ensuring that the number of pixels rejected does not equal or exceed the total number of images being combined. If sigclip rejection is chosen, the standard deviation of values for each pixel is found for the images in the list. Pixels which deviate from the mean by an amount greater than a certain factor times the standard deviation are rejected. These factors are given by the parameters lowsigma and highsigma for deviations less than or greater than the mean, respectively.

8. numlow

is an integer giving the number of lowest-valued pixels to be rejected if rejtype is set to 'minmax'. A value must be supplied no matter what setting rejtype has.

9. numhigh

is an integer giving the number of highest-valued pixels to be rejected if rejtype is set to 'minmax'. A value must be supplied no matter what setting rejtype has.

10. lowsigma

is a factor to be multiplied by the standard deviation of each pixel in the image list to find a threshold for deviant pixel rejection. Any pixel whose value is less than the mean by an amount greater than this threshold is rejected. A value must be supplied no matter what setting rejtype has.

11. highsigma

is a factor to be multiplied by the standard deviation of each pixel in the image list to find a threshold for deviant pixel rejection. Any pixel whose value is greater than the mean by an amount greater than this threshold is rejected. A value must be supplied no matter what setting rejtype has.

12. normalize

is set to 'yes' or 'no' telling the script "yes", normalize the combined image to have a final mean value of 1 or "no", do not do this.

13. document

is set to 'yes' or 'no' telling the script "yes", document the steps taken in combining images in the image header of the output (combined) image.

An example parameters file for rctcom is given below:

/archive/021215/
flatsU.dat
/home/everett/data/flats/
flatU.fits
mean
average
minmax
1
1
2.5
2.5
yes
yes

A good way to create this parameter file is to use a companion script to rctcom called setcom, which will help to ensure the proper format.