NAME

calwfp -- Perform routine calibration of Wide Field/Planetary Camera images.

USAGE

calwfp rootname

DESCRIPTION

The `calwfp' task is the calibration code used in both the Routine Science Data Processing (RSDP) and in STSDAS. This task performs a standard sequence of processing steps on individual WFPC camera observations, listed below, which remove most of the known instrumental signature.

    1) Perform the A-to-D fixup 
    2) Subtract global bias level 
    3) Subtract bias image 
    4) Subtract preflash image, or perform CTE fixup 
    5) Subtract superpurge residual image (not usually performed 
       by RSDP: see below) 
    6) Subtract the scaled dark image 
    7) Apply normalized flat field correction 
    8) Populate header keywords with statistical and photometric 
       information

The input data quality file (DQF) is updated with pixels found to be saturated, the DQF of known bad pixels (static mask), and with the DQFs of any images used in the processing sequence. Histograms of the input data, the data following A-to-D correction, and the output data are generated. The steps performed by this task are specified by setting keywords in the input image header.

INPUT FILES

The input WFPC image should be in the form provided by the Post Observation Data Processing System (PODPS). This task is specific to WFPC data and requires a large number of keywords (see below) obtained from the WFPC image header. The first two input images listed below are always required, the others may be required depending upon the options selected. The paragraphs below describe the various files used by `calwfp'.

.D0H (the input image)

The input WFPC image in GEIS (also known as STF) format. This image can contain from 1 to 4 groups. The image header should conform to the standard WFPC header format. Keywords in the header are used to select the various processing steps and to specify the names of the necessary reference files. The image must be of type integer for the ATODCORR and DOSATMAP steps to be meaningful.

.Q0H

The input WFPC data quality file (DQF) in GEIS format. This file must consist of short integers and have the same number of dimensions and groups as the input image (the .D0H file). Each pixel indicates the quality of the corresponding pixel in the input image. Zero valued pixels indicate "good" pixels in the input image; any pixel that is not zero flags a problem with the corresponding pixel.

.X0H

The input WFPC Extracted Engineering Data file (in GEIS format). This file contains the two engineering columns and, for FULL mode, the 12 columns of overclocked pixels. It is required when the `BIASCORR' keyword is selected (see below).

.Q1H

The input WFPC Extracted Engineering Data DQF. It is required when the `BIASCORR' option is selected (see below).

.SHH

The Standard Header Packet. This file is not currently used by `calwfp'. It is part of the standard WFPC data set, and contains a large amount of engineering data.

OUTPUT FILES

Each output file is a two-dimensional GEIS format image containing the same number of groups as the input image. The following extensions are appended to the input file's root name.

.C0H

The processed output image. This image is in REAL format (with an option to provide FITS-like scaling to short or long integers---see the `DATATYPE' keyword description below). Extreme values resulting from input data values outside of the range of the WFPC A-to-D converter (0 to 4095) are edited to limit the range of values in the output image. These pixels are flagged in the DQF (i.e., the .C1H file described below).

.C1H

The DQF for the processed output image. This contains the result of a bitwise AND operation of the input DQF and all DQFs associated with reference files used in the processing of the input image.

.C2H

The histograms of the "good" (i.e, not DQF-flagged) pixel values. This image consists of three rows and the same number of groups as the input image. The first row contains the histogram of the pixel values in the input image. The second row contains the histogram following the A-to-D correction step. The third row contains the histogram of the output (.C0H) image. The creation of this file is controlled by the keyword `DOHISTOS' in the input image header.

.C3H

The map of saturated and missing pixels. The information in this file is redundant to that in the .C1H, and is not produced by the RSDP. The creation of this file is controlled by the keyword `DOSATMAP' in the input image header.

PROCESSING STEPS AND REFERENCE FILES

Unlike most IRAF and STSDAS tasks, the steps to be performed by `calwfp' are controlled by setting several keywords in the science data header, rather than by task parameters. In addition, the names of the calibration reference files are contained in keywords in the science data header. This is done to accomodate the needs of the rigidly configured RSDP environment, but this approach also provides the means by which the calibration history is recorded for each image.

The steps performed are in the order given below, and selection of certain processing steps may require that other keywords in the input image header contain necessary information (e.g., the name of a reference file). These keywords can be changed most easily using the `ctools.chcalpar' task. A more complete description of the algorithms employed can be found in the "STSDAS Calibration Guide". The acceptable input values are (YES | NO | DONE). "DONE" has the same effect as "NO". In the output image (`.C0H'), those keywords which were set to YES in the input image and for which processing was successfully performed, are set to "DONE".

MASKCORR

Include the static bad pixel mask in the output DQF. The name of the static bad pixel mask must be provided in the keyword `MASKFILE' and must be in the same format as the DQF.

ATODCORR

Replace each pixel with the appropriate value from the A-to-D correction lookup table. The name of the lookup table must be provided as the value of the `ATODFILE' keyword. The A-to-D file may consist of multiple lookup tables, whereupon the table whose temperature is closest to the value of the input image header keyword `BAY3TEMP' is selected.

BLEVCORR

The global bias level is determined from the extended register pixels in the Extracted Engineering Data (`.X0H') file and subtracted from each pixel in the input image. The name of this file must be provided in the keyword `BLEVFILE', and its corresponding DQF must be provided in `BLEVDFIL'. The global bias level is determined and subtracted separately for odd- and even-numbered columns in order to remove a somewhat time-dependent odd/even bias level.

BIASCORR

The Bias Image Reference File is subtracted from the input image. The names of the bias image and its DQF must be provided in the keywords `BIASFILE' and `BIASDFIL', respectively.

PREFCORR

If the keyword `PREFTIME' exceeds zero seconds, the preflash image reference file is scaled and subtracted from the input image. The preflash image is multiplied by the preflash lamp exposure time (obtained from the keyword `PREFTIME' in the input science image header, expressed in seconds) and then subtracted from the input image. If the value of `PREFTIME' is zero, the CTE fixup is applied. The names of the preflash or CTE image and its DQF must be provided in the keywords `PREFFILE' and `PREFDFIL', respectively.

PURGCORR

The names of the superpurge image and its DQF must be provided in the keywords `PURGFILE' and `PURGDFIL', respectively.

DARKCORR

The dark image reference file is scaled and subtracted from the input image. The dark image is multiplied by the total "dark" accumulation time (obtained from the keyword `DARKTIME' in the input image header and expressed in seconds) and then subtracted from the input image. The names of the dark image and its DQF must be provided in the keywords `DARKFILE' and `DARKDFIL', respectively.

FLATCORR

The input image is corrected for variations in gain between pixels by the application of a flat field image. The input image is multiplied by the flat field image. (The flat field reference files used in the RSDP will have been normalized and inverted in preparation for this step.) The names of the flat field image and its DQF must be provided in the keywords `FLATFILE' and `FLATDFIL', respectively.

DOSATMAP

Create a DQF flagging those pixels in the input image which saturated the A-to-D converter or for which data was lost in transmission. The information in this file, which has the extension `.C3H', is also contained in the `.C1H' file described above.

DOPHOTOM

Fill in the photometry keywords `PHOTFLAM', `PHOTZPT', `PHOTPLAM', and `PHOTBW' with values selected from the reference table line that matches the `PHOTMODE' keyword. The PHOTMODE keyword itself is constructed during `calwfp' processing from values of several other keywords which specify the camera, chip, and filter(s) used during the observation. The name of the photometry reference table must be provided in the keyword `PHOTTAB' if this option is selected.

DOHISTOS

Create an image of three rows containing histograms of the pixel values in the input image, following A-to-D correction, and in the output (`.C0H') image. This file has the extension `.C2H'.

DATATYPE

Select the data type of the output (`.C0H') image. The allowed values are "REAL", "SHORT", or "LONG" corresponding to real*4, short integer, and long integer pixels. FITS-like scaling is performed on output only if the `DATATYPE' is set to SHORT or LONG.

The following table associates the filename extensions for the various reference files. Note that the filenames specified for the reference files are prepended with something like: "wref$", or "wcal$". These are for use as IRAF logical pathnames, since it is often impractical to have all needed WFPC reference files in the same directory (or even the same disk) as the images to be calibrated. For example, type "show wcal" to display the current setting for the "wcal" environment variable, and "set wcal = home$" if the ".x0h" file is in your IRAF login directory. See the on-line help for "set" for further information.

	   Table 1.  Reference Header File Extensions

	Extension(s)	| Reference type(s)
	-------------------------------------------------
	.r0h		| Bad pixel mask 
	.r1h		| A-to-D Correction Lookup Table
	.r2h, .b2h	| Bias image & DQF
	.r3h, .b3h	| Preflash image & DQF
	.r4h, .b4h	| Superpurge residual image & DQF
	.r5h, .b5h	| Dark image & DQF
	.r6h, .b6h	| Flat-field image & DQF
        .r8h            | "Delta" flat-field files

DATA QUALITY FLAG VALUES

The DQF values indicate which, if any, pathologies apply to each pixel in the image with which the DQF is associated. The pathologies that are currently recognized by the WFPC software are bit-coded according to the following scheme, and the output DQF value is the sum of each value given below when it applies:

GOODPIXEL (value = 0)

Unflagged pixel. Only pixels with this Data Quality value are included when determining bias level and the statistics reported in the header of the output (`.C0H') image.

SOFTERROR (value = 1)

Reed-Solomon error in data transmission. This pixel is part of a packet of data in which one or more pixels may have been corrupted during data transmission.

CALIBDEFECT (value = 2)

Defect in a calibration file used in processing the image. If a pixel is flagged bad in any of the calibration files applied to the image (e.g., dark or flat), this flag is set for that pixel.

STATICDEFECT (value = 4)

Recognized long term defect in the WFPC camera. A DQF of static defects is maintained in the CDBS data base and includes such defects as blocked columns and dead pixels.

ATODSAT (value = 8)

The A-to-D converter was saturated. The actual signal in the pixel is unrecoverable but known to be greater than or equal to the A-to-D full scale value.

DATALOST (value = 16)

Missing data. The pixel was lost during readout or data transmission.

BADPIXEL (value = 32)

Generic bad pixel. This value flags a bad pixel which does not fall into one of the above classifications.

PARAMETERS

inname [string]

The rootname of the input WFPC data set. The input filenames consist of this rootname and the extensions that are discussed in the input and output file sections below.

outname [string]

The rootname of the output WFPC data set. The output filenames consist of this rootname and the extensions that are discussed in the input and output file sections below.

EXAMPLES

1. Calibrate the WFPC observation in the data set with the rootname of "w00ug201t", and use the same rootname for the output files. In this case, the engineering data (.X0H) file is in the same directory as the raw data (.D0H) file: home$wfdata.

    cl> set wcal=home$wfdata/
    cl> calwfp w00ug201t w00ug201t

REFERENCES

This task was designed and coded by J. MacKenty (STScI), and follows the calibration strategy developed by the WFPC IDT, as described in the paper by T. Lauer (PASP, 101, 445, 1989). It has been substantially modified in response to in-flight experience by J. MacKenty, R. Shaw, and J.C. Hsu (STScI).

SEE ALSO

checkwfpc, chcalpar

Type "help wfpc opt=sys" for a higher level description of the `wfpc' package. Type "help geis" for a general description of GEIS-format images.