B Description of the CCDPACK routines

 B.1 General considerations
 B.2 Alphabetic list of CCDPACK routines.
 B.3 Complete routine descriptions

In this Appendix a more exhaustive catalogue of the capabilities and parameters of the CCDPACK routines are given. Do not read it if the previous descriptions have met your present needs. Read it only if they don’t. Remember that help is available at any time in the XREDUCE Help menus, from the programs by returning a ‘?’ in response to a prompt, or by entering the on-line or hypertext help systems after starting CCDPACK.

B.1 General considerations

Throughout the following descriptions various methodologies exist which are worthy of discussion as topics. They cover such aspects of data processing as the control of, saturation values, data types and data combination.

B.1.1 Data saturation

CCDPACK allows you to flag data values above a given limit as saturated. It performs this task using one of two methods, either setting the pixels BAD (often referred to as invalidating or setting to a magic value), in which case the future processing is transparent if applications which can accommodate BAD values are used, or alternatively by setting all such pixels to a defined value (this option may be necessary if the destination analysis programs cannot handle BAD values). In this latter case care is required because future operations to the data can easily modify the values, so that unintentional differentiation of the saturated data may occur. This will only happen in such situations as flatfielding where the pixels are modified singly, global operations such as subtraction, multiplication etc. by a constant will preserve the saturated value dataset, although modifying the actual saturation value.

If you process saturated data using a specified value within CCDPACK then a CCDPACK extension item is created and the saturation value is written to it. Future work within CCDPACK will then stop modification of these saturated values (the routines CALCOR and FLATCOR do this). In general if you can safely use BAD values this is by far the better option. If you are determined to mark saturated data using a specific value then it is recommended that calibration (dark, flash and flat) frames are processed using BAD values as the combination processes do not support saturated value preservation. If the resultant master calibration frames contain BAD values then replacement (by the value 1 or by the mean) of these can be performed in KAPPA (SUN/95: SETMAGIC).

B.1.2 Data types and sizes

The CCD data frames given to CCDPACK can be of any non-complex HDS (SUN/92) numeric type (e.g. they could be of type _WORD or _UWORD - Fortran INTEGER*2, _REAL, _INTEGER or even _DOUBLE). CCDPACK usually processes the data using this type. On occasion, however, frames, such as the master flatfield, will not be returned in their original type. This is because normalising to a mean of one precludes data storage of a precision less than _REAL. However, the flatfield correction routine FLATCOR will return the data in your input type regardless of the flatfield type so types are preserved in the longer term.

If your input frames are of a mixed data type CCDPACK will preserve the data type of each individual frame. However, if you are combining mixed data types into a calibration master of some kind, CCDPACK will choose the least precise type which represents best all the input data types.

In the routines MAKEBIAS, MAKECAL and MAKEFLAT input images which have different physical sizes (because they have been previously sectioned, for some reason) will be padded to a common size before processing. This is so that no calibration data is lost.

The corrective routines (CALCOR, DEBIAS and FLATCOR) trim the data down to the size which contains the smallest dataset. The trimming processes occur separately for each input image. The most efficient method of processing is to keep the input data files of the same type and size, as this avoids costly trimming, padding, and mapping/unmapping of the data (CCDPACK always attempts to minimize the amount of re-mapping of calibration frames when processing lists of images).

The MAKEMOS application is specially designed to deal with datasets which may have very small regions in common and which produce large output mosaics.

B.1.3 Image combination techniques

CCDPACK supports many different methods of data combination:

The aim is to provide you with a fairly exhaustive list of ways in which you can combine your data. The methods include the most efficient (mean) and the most robust (median) estimators and a range of options in between these ideals. A description of the basis of the methods follows:

MEAN
a weighted mean.
WEIGHTED MEDIAN
a weighted median. The weighted average of the values nearest to the half weight value. A more even handed estimator than the ordinary median which takes no account of the errors in the individual measurements.
TRIMMED MEAN
Alpha trimmed mean. The final estimate is the mean of the values excluding the alpha (a fraction between 0 and 0.5) upper and lower values.
MODE
a maximum likelihood mean. This is essentially an iteratively sigma (the standard deviation) clipped mean, where values outside of a given number of sigmas of the mean value are rejected on each pass until convergence is achieved. The standard deviation is always based on the variation of the data contributing to each output value.
SIGMA CLIPPED MEAN
the mean of the values left after rejecting those outside of a given number of standard deviation of the initial mean. The standard deviation is derived from data variances if available, otherwise a standard deviation based on the variation of the data is used.
THRESHOLD CLIPPED MEAN
the mean of the values after rejecting values above and below defined thresholds. Note this usually applies to the output data range if some internal normalisation is performed (MAKEBIAS and MAKEFLAT).
MINIMUM AND MAXIMUM EXCLUSION MEAN
the mean after the
minimum and maximum values are rejected.
BROADENED MEDIAN
the median if the number of input data values is less than five. The mean of the central few values if the number of inputs is larger.
SIGMA CLIPPED MEDIAN
the weighted median of the values left after rejecting those outside of a given number of standard deviations of the initial mean. The standard deviation is derived from data variances if available, otherwise a standard deviation based on the variation of the data is used.
UNWEIGHTED MEDIAN
an unweighted median. A simple median of the data values. No weighting is taken into account. This is significantly faster than the weighted median, but takes no account of the known errors in the measurements.
DRIZZLE
or variable-pixel linear reconstruction, maps weighted input data into pixels in a subsampled output image. In order to avoid convoluting the output image with the large input pixel size, the input pixels are shrunk before it is averaged into the output image.

All of these methods, support variance propagation, provided that the input data errors have an approximately normal distribution.

In general if the input data comprise less than 5 datasets and spurious values are expected to be present, it is very difficult to perform better than the median, and this is the normal default.

B.2 Alphabetic list of CCDPACK routines.

ASTEXP Exports coordinate system information from images. 131

ASTIMP Imports coordinate system information into images. 135

CALCOR Performs dark or flash count corrections. 139

CCDALIGN Aligns images graphically by interactive object selection. 143

CCDCLEAR Clears global parameters. 147

CCDEDIT Edits the CCDPACK extensions of images. 148

CCDFORK Creates a script for executing CCDPACK commands in a background process. 156

CCDNDFAC Accesses a list of images, writing their names to a file. 157

CCDNOTE Adds a note to the log file. 159

CCDSETUP Sets up the CCDPACK global parameters. 160

CCDSHOW Displays the current values of any CCDPACK global parameters. 165

DEBIAS Debiasses lists of images either by bias image subtraction or by interpolation – applies bad data masks – extracts a subset of the data area – produces variances – applies saturation values. 166

DRAWNDF Draws aligned images or outlines on a graphics device. 175

DRIZZLE Resamples and mosaics using the drizzling algorithm. 180

FINDCENT Centroids image features. 185

FINDOBJ Locates and centroids image features. 189

FINDOFF Performs pattern-matching between position lists related by simple offsets. 194

FLATCOR Performs the flatfield correction on a list of images. 199

IDICURS Views and writes position lists interactively. 203

IMPORT Imports FITS information into CCDPACK extensions. 207

MAKEBIAS Produces a bias calibration image. 211

MAKECAL Produces calibration images for flash or dark counts. 216

MAKEFLAT Produces a flatfield image. 219

MAKEMOS Makes image mosaics by combining and normalising. 223

MAKESET Writes Set header information to images. 232

PAIRNDF Aligns images graphically by drag and drop 237

PLOTLIST Draws position markers on a graphics display. 243

PRESENT Presents a list of images to CCDPACK. 246

REDUCE Automatic CCD data reduction facility (command-line version) 252

REGISTER Determines transformations between lists of positions. 253

SCHEDULE Schedules an automated CCDPACK reduction. 260

SHOWSET Outputs image Set header information. 264

TRANLIST Transforms lists of positions. 267

TRANNDF Transforms (resamples) images. 274

WCSEDIT Modifies or examines image coordinate system information. 278

WCSREG Aligns images using multiple coordinate systems. 282

XREDUCE Starts the automated CCD data reduction GUI. 285

B.3 Complete routine descriptions

The CCDPACK routine descriptions are contained in the following pages.