NAME

basic2d -- Performs two dimensional image reduction on STIS data.

USAGE

basic2d input output

PARAMETERS

input

Input image to be processed through basic2d.

output

Name of output processed file.

(outblev = "")

Name of output text file that will contain the bias level subtracted at each pixel position.

(dqicorr = "perform")

Update the data quality array from the bad pixel table. Has to be set to PERFORM for all CCD and MAMA raw input images.

(atodcorr = "omit")

Perform analog-to-digital correction on CCD images only. This step is currently not performed.

(blevcorr = "omit")

Subtract the bias form the overscan region in CCD images only.

(doppcorr = "omit")

Convolve reference files with the Doppler smoothing function before being these files applied.

(lorscorr = "perform")

Convert high resolution images to low resolution images. Valid for MAMA images only.

(glincorr = "perform")

Check for non-linearity in the MAMA detector. Valid for MAMA images only.

(lflgcorr = "perform")

Check for non-linearity in the MAMA detector. Valid for MAMA images only.

(biascorr = "perform")

Subtract the bias reference file image from CCD input science images only.

(darkcorr = "perform")

Subtract the dark reference file image from both CCD and MAMA input science images.

(flatcorr = "perform")

Multiply the flat field reference file image to both CCD and MAMA input science images.

(shadcorr = "perform")

Correct for shutter shading. Valid for CCD images only.

(photcorr = "omit")

Update photometric keywords in the primary header of the CCD and MAMA images.

(darkscale = "")

Scale factor(s) to override default dark scaling. This is a list of scale factors delimited by either blank spaces or commas.

(statflag = yes)

Compute statistics on the images and update the respective extension headers?

(verbose = no)

Print verbose time stamps.

DESCRIPTION

The task basic2d provides routine calibration for STIS data. The task performs a 2 dimensional image reduction. Only the steps specified as PERFORM in the input paramaters are performed. If all input parameters are set to OMIT then all steps will be performed.

INPUT AND OUTPUT IMAGES

The input STIS images are contained in extensions in FITS files, with three extensions in a set: science (EXTNAME=SCI), error (ERR), and data quality (DQ). There may be multiple sets (or groups) in the input file, and if so BASIC2D will read each group, calibrate it, and write the resulting three-extension group to the output FITS file.

Input files to this task depend on which steps are set to PERFORM in the input parameter switches. If dqicorr and blevcorr are set to PERFORM, then the input files should be the _raw.fits files.

REFERENCE FILES and PROCESSING STEPS

Reference file images are expected to cover the entire illuminated portion of the detector (except mixed illuminated and overscan pixels for binned CCD data). The reference image need not be binned the same as the uncalibrated data, but if they differ, the reference image must be more finely binned. (The one exception is the low-order flat file, which must be binned and can be binned more than the uncalibrated data.) If the uncalibrated image is a subimage or is binned more than the reference image, the matching subset of the reference image will be extracted to a scratch array and binned down to match the uncalibrated data. This is done for the bias, dark, and flat field data. The binning is done by averaging the pixel values in a rectangular box. The errors are combined by taking the square root of the sum of the squares of the errors in the box, then dividing by the number of pixels in the box.

The names of the reference files (images and tables) to be used by BASIC2D (and consequently by all the other processing tasks) are specified in the primary header of the input image, under the section CALIBRATION REFERENCE FILES.

For the CCD, a row is selected in the CCD parameters table based on an agreement between image header keywords and table columns. These are CCDAMP, CCDGAIN, CCDOFFST, BINAXIS1, and BINAXIS2. Once the correct row is found, the values of the columns ATODGAIN, CCDBIAS, READNSE, and SATURATE are read. CCDGAIN is the commanded value of gain, while ATODGAIN is the actual value, in electrons per dn. CCDBIAS is the estimate of the bias in dn which would be used by the on-board software for target-acquisition. This is also used for bias level subtraction (BLEVCORR) for lines that do not have enough good pixels in the overscan regions. READNSE is the readnoise in electrons. The primary header of the output image is then updated with the values of ATODGAIN and READNSE. For the MAMA, the gain is set to one, and the bias and readnoise are set to zero. (Note: The current situation is that the selection ignores CCDOFFST, BINAXIS1, and BINAXIS2; column SATURATE is not read.)

A preliminary step (not controlled by a header keyword) is to compute and assign values to the error array (see donoise.c). This is done if all values in the input error array are zero. The error (in dn) is computed by:

	error = sqrt ((I - bias) / gain + (readnoise / gain)^2) 

For the MAMA detectors, if doppcorr is PERFORM, then keywords EXPSTART, DOPPZERO, DOPPMAG, and ORBITPER are read from the SCI extension header. These are used in computing the Doppler shift with which some reference files will be convolved. These files are the bad pixel table, the dark image, and the flat fields.

The calibration steps will depend on which calibration switches are set to PERFORM form the input para,eters. The acceptable input values for each switch are (PERFORM | OMIT | COMPLETE). COMPLETE has the same effect as OMIT. In the output image, those keywords which were set to PERFORM in the input image and for which processing was succesfully performed, are set to COMPLETE. The calibration steps for each detector are:

For the CCD detector:

       1. Get information from the CCD parameters table
       2. Assign values to error array
       3. Analog-to-digital correction (\fIatodcorr\fR)
       4. Update data quality array from bad pixel table (\fIdqicorr\fR)
       5. Subtract bias from overscan regions (\fIblevcorr\fR)
       6. Subtract bias image (\fIbiascorr\fR)
       7. Subtract dark image (\fIdarkcorr\fR)
       8. Multiply by flat field image (\fIflatcorr\fR)
       9. Correct for shutter shading (\fIshadcorr\fR)
      10  Update photometry keywords (\fIphotcorr\fR)
      11. Compute statistics, and update extension headers (\fIstatflag\fR)

For the MAMA detector:

       1. Assign values to error array
       2. Update data quality array from bad pixel table (\fIdqicorr\fR)
       3. Convert from high-res to low-res (\fIlorscorr\fR)
       4. Check for nonlinearity (\fIglincorr\fR and \fIlflgcorr\fR)
       5. Subtract dark image (\fIdarkcorr\fR)
       6. Multiply by flat field image (\fIflatcorr\fR)
       7. Update photometry keywords (\fIphotcorr\fR)
       8. Compute statistics, and update extension headers (\fIstatflag\fR)

ATODCORR

This step is currently not performed; if it were, it should only be done for the CCD.

DQICORR

Update the data quality arrays of the input images from the bad pixel table. The name of the bad pixel table must be provided in the keyword BPIXTAB.

LORSCORR

Convert the input high resolution MAMA image to a low resolution image. The binning of the uncalibrated image is determined from the LTM1 and LTM2 keywords in the SCI extension header. LTMi = 1 implies the reference pixel size, low-res, and LTMi = 2 means high-res. In this step, if either or both axes are high-res, they will be binned down to low-res. The binning differs from binning reference files to match an uncalibrated image in that in this step the pixel values are summed rather than averaged.

GLINCORR and LFLGCORR

Check for nonlinearity of the MAMA detectors in MAMA images only. The name of the MAMA linearity correction table must be provided in the keyword MLINTAB.

BLEVCORR

Subtract bias from oversan regions in science CCD images only. The resulting image will be smaller than the input due to trimming off the physical and virtual overscan regions. If the data are binned, the pixels that are partly overscan and partly illuminated will also be removed. The CRPIXi and LTVi keywords are updated in the output; these change due to the offset from removing the overscan. The overscan level is determined for each image line and subtracted, independently of other lines. The algorithm to find the bias level is described below. Parallel (virtual) overscan lines are ignored. When processing a given line, if the overscan regions contain a sufficient number of good pixels, the mean is subtracted from each pixel in the line, and the error array is updated by adding the overscan error in quadrature. If there are fewer than three good overscan pixels, a default value is subtracted (ccdbias from the CCD parameters table), and each pixel in the output data quality is flagged as having a calibration defect (512). If an output text file for overscan values was specified, the value subtracted from the current line is printed to that file. The mean value of all overscan levels is computed, and the mean is written to the output SCI extension header as MEANBLEV.

BIASCORR

Subtract the bias reference image from the CCD science image only. If removing cosmic rays from input images, it is recommended to do it (i.e. task CRREJECT) before the bias image subtraction to keep from adding in the bias image errors more than once into the science error array. See below in the EXAMPLES section for the recommended order for processing the uncalibrated images. The name of the bias reference image must be provided in the keyword BIASFILE.

DARKCORR

Subtract the dark refrence image. The dark reference image (possibly a subset or binned down to match the uncalibrated data) will be scaled and subtracted from the uncalibrated data. The mean of the dark values subtracted will be written to the SCI extension header with the keyword MEANDARK. For CCD data, the dark image will be multiplied by the dark time (see below) and divided by the atodgain (from the CCD parameters table) before subtracting. For MAMA data, the dark image will be multiplied by the exposure time before subtracting; it will also be convolved with the Doppler smoothing function if DOPPCORR is PERFORM. For CCD data, the dark time is longer than the exposure time by an amount which depends on the location on the detector and which amplifier was used for readout. The dark time is the sum of the exposure time, the time since the line was flushed before the exposure, and the time to read out the line following the exposure. The name of the dark reference image must be provided in the keyword DARKFILE.

The darkscale parameter represents the scaling factors applied to the input dark file before the simple multiplication by the exposure time as an alternative to the default temperature dependent dark scaling formula. A separate scaling factor can be specified for each IMSET in the input image. The darkscale parameter accepts a list of floating point values delimited by commas or blank spaces. Each floating point number in the string will be used in place of the temperature dependent factor that would otherwise be calculated for the corresponding IMSET in the input file. If there are more IMSETs than numbers specified in the darkscale parameter string, then the last number in the string will be used as the scaling factor for the extra IMSETs. If there are more values than IMSETs, the extra values are ignored.

FLATCORR

Multiply the flat field image(s) specified in the primary header of the input science images. The flat field correction uses from one to three reference images, the keywords for which are PFLTFILE, DFLTFILE, and LFLTFILE. Any combination of one or more of these files may be used. To indicate that a file is not to be used, set its keyword name to blank. The PFLTFILE and DFLTFILE are interchangeable as far as CALSTIS is concerned. They must both be binned the same, or they can both be unbinned. The LFLTFILE, however, must be binned. The PFLTFILE and DFLTFILE, if they were specified, are read into memory and multiplied together. The SCI extension values are multiplied pixel by pixel, and the ERR extension values are added in quadrature. The LFLTFILE, if it was specified, is read into memory, "unbinned" by bilinear interpolation, and multiplied by the product of the PFLTFILE and DFLTFILE. The factor by which to expand the LFLTFILE in each axis depends on whether we have a PFLTFILE or a DFLTFILE. If either of those files does exist, we expand the LFLTFILE to the size of the product of those files. If not, we expand the LFLTFILE to the size of the uncalibrated data, and we determine the factor by comparing the LTM1 and LTM2 keywords in the LFLTFILE and the uncalibrated data. For MAMA data, the product of the flat field images will be convolved with the Doppler smoothing function if DOPPCORR is PERFORM. After taking the product of all the flat fields that were specified, a subset is taken and binned if necessary to match the uncalibrated image, and the uncalibrated data is then multiplied by the binned subset.

SHADCORR

Perform the shutter shading correction in CCD images only. This step is currently not performed. The shutter shading correction is based on a reference image. The name of the reference image should be provided in the keyword SHADFILE. The uncalibrated image is corrected pixel by pixel as follows:

	corrected = uncalibrated * EXPTIME / (EXPTIME + SHADFILE) 

PHOTCORR

Update the photometry keywords in the primary header of the output image. The name of the reference table must be provided in the keyword PHOTTAB. The columns DETECTOR, OPT_ELEM, CCDAMP, CCDGAIN, NELEM, WAVELENGTH, and THROUGHPUT are read from the photometric throughput table to find the row for which the values of DETECTOR and OPT_ELEM are the same as in the input image header. If the detector is the CCD, CCDAMP and CCDGAIN are also compared with the header keywords. For the matching row, the number of elements NELEM is read, and the WAVELENGTH and THROUGHPUT arrays are read. The synphot routine phopar is then called to determine the inverse sensitivity, reference magnitude (actually a constant), pivot wavelength, and RMS bandwidth. These are written to keywords in the primary header.

DATA QUALITY FLAG VALUES

The DQF pixel values provide an estimate of the "quality" of each pixel in the image with which the DQF is associated. These flags will be set and examined during the course of calibration, and may likewise be interpreted and used by downstream analysis applications. The DQ flags for STIS are listed in the table below. Each flag occupies one bit in a 16-bit signed integer word. Bit 0 is the least significant bit.

 0  Reed-Solomon decoding error
 1  Data replaced by fill values
 2  Bad detector pixel
 3  Data masked by occulting bar or beyond aperture
 4  pixel affected by large dark rate
 5  pixel affected by large flatfield blemish
 6  <reserved>
 7  <reserved>
 8  pixel saturated
 9  bad pixel in reference file
10  pixel affected by small flatfield blemish 
11  extracted flux affected by locally uncertain background
12  extracted flux affected by bad input data
13  data rejected during image combination
14  <reserved>

EXAMPLES

1. To calibrate CCD observations in the data set with the rootname "o3yc02kbm" with multiple images per file (i.e. CRSPLIT > 1 or EXTEND > 3). In this case the reference files are in the same directory as the raw data (*_raw.fits) file: home$stdata. Create the file overscan.txt with the oversan values subtracted:

	 cl> set oref=home$stdata/ 
         cl> epar basic2d
        input = "o3yc02kbm_raw.fits" input FITS file
       output = "o3yc02kbm_blev.fits" output FITS file
     (outblev = "overscan.txt") output text file for bias levels
     (dqicorr = "perform")      Update dq array from bad pixel table
    (atodcorr = "omit")         Analog-to-digital correction (CCD)
    (blevcorr = "perform")      Subtract bias from overscan regions (CCD)
    (doppcorr = "omit")         Convolve reference files w/doppler smoothing function?
    (lorscorr = "omit")         Convert from high-res to low-res (MAMA)
    (glincorr = "omit")         Check for nonlinearity (MAMA)
    (lflgcorr = "omit")         Check for nonlinearity (MAMA)
    (biascorr = "omit")         Subtract bias image (CCD)
    (darkcorr = "omit")         Subtract dark image
    (flatcorr = "omit")         Multiply by flat field image
    (shadcorr = "omit")         Correct for shutter shading (CCD)
    (photcorr = "omit")         Update photometry keywords
    (statflag = no)             Compute statistics, update extension headers
     (verbose = yes)            Print verbose time stamps?
        (mode = "ql")           

Perform cosmic ray rejection in previos created file (3yc02kbm_blev.fits):

	cl> crreject o3yc02kbm_blev.fits o3yc02kbm_crj_tmp.fits

Continue calibration with bias and dark subtraction, flatfielding, update
photometric keywords, and perform image statistics:

	cl> epar basic2d
        input = "o3yc02kbm_crj_tmp.fits" input FITS file
       output = "o3yc02kbm_crj.fits" output FITS file
     (outblev = "")             output text file for bias levels
     (dqicorr = "omiy")      Update dq array from bad pixel table
    (atodcorr = "omit")         Analog-to-digital correction (CCD)
    (blevcorr = "omit")         Subtract bias from overscan regions (CCD)
    (doppcorr = "omit")         Convolve reference files w/doppler smoothing function?
    (lorscorr = "omit")         Convert from high-res to low-res (MAMA)
    (glincorr = "omit")         Check for nonlinearity (MAMA)
    (lflgcorr = "omit")         Check for nonlinearity (MAMA)
    (biascorr = "perform")      Subtract bias image (CCD)
    (darkcorr = "perform")      Subtract dark image
    (flatcorr = "perform")      Multiply by flat field image
    (shadcorr = "omit")         Correct for shutter shading (CCD)
    (photcorr = "perform")      Update photometry keywords
    (statflag = yes)            Compute statistics, update extension headers
     (verbose = yes)            Print verbose time stamps?
        (mode = "ql")           

	cl> set oref=home$stdata/ 
	cl> epar basic2d
	input = "o6yc03010_raw.fits" input FITS file
       output = "o6yc03010_flt.fits" output FITS file
     (outblev = "")             output text file for bias levels
     (dqicorr = "perform")      Update dq array from bad pixel table
    (atodcorr = "omit")         Analog-to-digital correction (CCD)
    (blevcorr = "omit")         Subtract bias from overscan regions (CCD)
    (doppcorr = "omit")         Convolve reference files w/doppler smoothing function?
    (lorscorr = "perform")      Convert from high-res to low-res (MAMA)
    (glincorr = "perform")      Check for nonlinearity (MAMA)
    (lflgcorr = "perform")      Check for nonlinearity (MAMA)
    (biascorr = "omit")         Subtract bias image (CCD)
    (darkcorr = "perform")      Subtract dark image
    (flatcorr = "perform")      Multiply by flat field image
    (shadcorr = "omit")         Correct for shutter shading (CCD)
    (photcorr = "perform")      Update photometry keywords
    (statflag = yes)            Compute statistics, update extension headers
     (verbose = yes)            Print verbose time stamps?
        (mode = "ql")        

TIME REQUIREMENTS

BUGS

REFERENCES

P. Hodge, March 1997, short memo.
ICD47, R. Shaw, April 1997.
Iraf task written by R. Katsanis.
BASIC2D routines written by P. Hodge.

SEE ALSO

calstis