Instrument Science Report STIS 96-026
STIS Pipeline Testing III:
2-D Image Rectification
S.R. Keener, S. Hulbert, and P. Hodge
July 26, 1996
ABSTRACT
The calstis-7 functions heliocentric velocity correction and 2-D distortion correction
were tested successfully with full-frame, subarray, binned, and unbinned test MAMA and
CCD images. Testing of flux correction by the task was only partially successful. Some
mismatches between output image values and hand calculated values were found. The
incorrect calculation of the inverse sensitivity function by the task should be fixed in future
reworks, which may solve the mismatch problem. A problem when running flux correction
with 2-D distortion correction needs to be tracked down, but may be due to a faulty test
distortion file.
1. Introduction
CALSTIS is a set of procedures that process raw STIS data into a collection of calibrated products. One aspect of this processing is to remove instrumental distortions from
the 2-D spectroscopic data–this processing is carried out by calstis-7. This task takes
as input, raw “distorted” data and produces a rectified 2-D image that is linear in wavelength and spatial position. The key to the processing is the distortion function that maps a
raw pixel position to a corresponding wavelength and slit position.
2. Description of 2-D Distortion Tables
The 2-D distortion reference table specifies the mapping between linearized wavelength and spatial position of the output image and the raw coordinates of the input image.
The individual rows of the table are unique for a particular aperture, central wavelength,
and spectral order. For each of these configurations the WCS information for the output
image (NPIXn, CRPIXn, CRVALn, CDELTn where n=1,2) and the distortion functions
(specified by NCOEFFn and COEFFn where n=1,2) are included. The distortion coefficients belong to low order Chebyshev polynomial fits to the following functions:
1
( x, y ) = fx(λ, s)
( x, y ) = fy ( λ, s )
To generate the template for one of these tables we followed the following set of operations in the IRAF environment:
1) Use the TABLES task, TCREATE, to create a blank table with properly defined columns. The columns are defined by:
Table 1. Definition of 2-D Distortion Table Columns
Column
Datatype
Display Format
Units
APERTURE
CH*12
%12s
CENWAVE
I
%6d
ORDER
I
%5d
NPIX1
I
%5d
pixel
NPIX2
I
%5d
pixel
CRPIX1
D
%8.1f
pixel
CRPIX2
D
%8.1f
pixel
CRVAL1
D
%25.16g
angstrom
CRVAL2
D
%25.16g
arcsec
CDELT1
D
%25.16g
angstrom/pixel
CDELT2
D
%25.16g
arcsec/pixel
NCOEFF1
I
%5d
NCOEFF2
I
%5d
coeff1
D[11]
%25.16g
coeff2
D[11]
%25.16g
angstrom
To modify the WCS information for the output image we merely used the TABLES
task, TEDIT.
To generate a distortion mapping we followed the following set of operations in the
IRAF environment:
1) Create an ascii table of three columns: wavelength, spatial position, and detector
axis 1 pixel
2) Run the STSDAS task, XYZTABLE, to fit a surface to the ascii table from 1).
2
3) Use the TABLES task, TCREATE, to convert the output from XYZTABLE, namely
the set of Chebyshev coefficients, to a SDAS binary table with a single column. The column is defined by:
Table 2. Definition of Chebyshev coefficient column
Column
Datatype
Display Format
COEFF1
D
%25.16g
Units
4) Use the TABLES task, TAINSERT, to insert the new coefficients into a copy of the
distortion table (the copy was made using the TABLES task, TCOPY).
5) Repeat step 1) - 4) for detector axis 2.
3. Testing
Since the input images to the calstis-7 task will be the output from calstis-1
(2-D image reduction) the test images were first run through calstis-1 (see STIS ISR
96-022 for a description of calstis-1 testing). Full-frame, subarray, binned, and
unbinned MAMA and CCD images were used in the calstis-7 testing. The images
contained either a constant value or a pattern of zero and non-zero valued pixels. The patterns used included single non-zero pixels scattered at various intervals, vertical and
horizontal strips of non-zero pixels, and blocks of non-zero pixels. Beginning testing of
the calstis-7 task included running test images through the task using a 2-D distortion
table (keyword DISTNTAB = distn.fits) that would map directly from raw coordinates to
WCS (i.e. no distortion). This would insure that the task ran correctly and that header keywords were updated. The next level of testing included checking the heliocentric velocity
correction (keyword HELCORR = PERFORM) with the no-distortion table. The third
level of testing was used to check real distortions with and without a heliocentric velocity
correction. The final level of testing was to include checking the flux correction.
The various test images were run through the task with X2DCORR = PERFORM
using the no-distortion table. There were no problems with this first level of testing. The
header keywords were correctly updated from the values in the distortion table. The input
image was directly mapped to the output image with no distortion.
Heliocentric Correction
For the next level of testing, the heliocentric velocity correction switch was set to
PERFORM. This switch corrects for the effect of the Earth’s velocity around the Sun on
the wavelength axis of the spectrum. The value of this additional velocity depends on what
3
time of the year it is during the observation and on what the RA and DEC of the target are.
The following formula can be used to figure out the resulting change in wavelength:
∆λ = (v/c)λ.
Several values of target RA and DEC were tried. The largest change in wavelength
occurred when the RA of the target was 90˚, its DEC was 23.5˚, and the date of the observation was March 21, the spring equinox. The correction performed by the task matched
the values calculated with the above equation.
Real Distortion
The distortion file contains the values of the header keywords CDELT1 and CDELT2.
These keywords are used by the WCS to define the distance in the x-direction and in the ydirection between any two pixels in the output file. The values of these keywords were
changed in the distortion file to 0.9 of their original values. First, CDELT1, which effects
the x-axis, was changed. When a patterned input image was used, the output image
showed ‘smearing’ in the x-direction as expected. This ‘smearing’ was a product of the
smaller distance between output pixels; pixels on the edge of non-zero values were made
partly from zero value pixels and partly from non-zero value pixels. When CDELT2 was
changed, ‘smearing’ in the y-direction was noted. When both CDELT1 and CDELT2 were
changed to 0.9 of their original values, the ‘smearing’ affect was present in both directions. Calculated output image pixel values matched those from the calstis-7 task.
The test were run with the ‘real’ distortion files when HELCORR was set to PERFORM
and to OMIT. The heliocentric velocity correction was performed correctly, as was the real
distortion.
The distortion file also contains the values of the header keywords CRPIX1 and
CRPIX2. These keywords define where the center of the aperture lies in pixel space. The
first extension keywords TARGPSA1 and TARGPSA2 define the target position in pixel
space. These four keywords, plus OFFSET1&2 (MAMA dither), are used by the calstis-7 task to create a mask. When the difference between CRPIXn and TARGPSAn
(where n=1, 2) is large enough, the spectrum edges can be cut off because they fall beyond
the edges of the aperture. Delta(CRPIXn,TARGPSAn) was set to zero, as well as positive
and negative values. A non-zero delta in the positive x-direction caused the spectrum to be
shifted by the same amount of pixels in the negative x-direction and vice versa with a nonzero delta in the negative x-direction. This was as expected. A non-zero delta along the yaxis caused no change in the y-direction, although a change should have been produced.
This needs to be examined in future reworks of the task.
Flux Correction
When the FLUXCORR switch is set to PERFORM, the calstis-7 task makes an
absolute flux and aperture throughput correction to the input image. In order to test that
4
the calstis-7 task was correctly performing this step, several different aperture
throughput and photometry reference tables were used. Tests were run with aperture
throughput and absolute flux correction as constant functions, with the aperture throughput correction as constant while the absolute flux correction was a simple function, and
with the aperture throughput as a simple function while absolute flux correction was constant. All these test cases were run with a no-distortion file (one-to-one mapping) and with
a real distortion file. The heliocentric velocity correction switch was not set to PERFORM
for these particular tests.
The version of calstis-7 which was tested used the following equation to perform
the flux correction:
1
counts 1
FluxCorrection = ----------------- ⋅ --- ⋅ -----------time S m ⋅ w
where counts is the science data value of a pixel, time is the exposure time of the
image, 1/S is the point source inverse sensitivity for the instrument configuration, m is the
image plate scale (CDELT2 converted to arcsec), and w is the slit width. The task also calculates the conversion factor between a point source and an extended source and writes
that value into the keyword DIFF2PT. DIFF2PT is equal to mw/T, where T is the aperture
throughput. The flux correction equation was used to hand calculate expected output values. These calculations were compared with the numbers output by the calstis-7 task.
The value of the DIFF2PT keyword was also compared to its hand calculated value. Table
3 and Table 4 show values obtained during FLUXCORR testing.
When CDELTn (where n=1,2) was 1, the distortion file was 1-to-1, and various values
were used for T and 1/S, the values output by the task matched those calculated by hand.
However, the values output by the task when the CDELTn keywords were given various
values did not match those calculated by hand. There was also a problem testing the real
distortion file in conjunction with FLUXCORR. It is assumed that the problem is in the
distortion file itself since the file has proven particularly troublesome to produce; if this is
not so, the problem will need to be tracked down. Also, the FLUXCORR calculation itself
needs to be slightly modified since the task does not compute the value of 1/S correctly.
5
Table 3. Values from FLUXCORR testing using a 1-to-1 distortion file, CDELT1,2 = 1,
and various values for T and 1/S.
Switch in
addition to
X2DCORR
Desc. of T and
1/S
Output Values
FLUXCORR off
----
35.5
T and 1/S are
constant
4.287E-8
T is a constant;
1/S is a simple
function
4.287E-9 to
4.287E-7
T is a simple
function; 1/S is
constant
4.287E-8
FLUXCORR on
Table 4. Values from FLUXCORR testing using a 1-to-1 distortion file, constant values
for T and 1/S, and various values for CDELT1,2.
Switch in
addition to
X2DCORR
Output Value
FLUXCORR off
35.5
FLUXCORR on
4.287E-8
FLUXCORR off
17.75
FLUXCORR on
2.144E-8
FLUXCORR off
8.875
FLUXCORR on
2.144E-8
FLUXCORR off
17.75
FLUXCORR on
4.287E-8
CDELT values
CDELT1,2 = 1
CDELT1 = 0.5;
CDELT2 = 1.0
CDELT1,2 = 0.5
CDELT1 = 1.0;
CDELT2 = 0.5
4. Conclusions and Open Issues
Performance was nominal for most of the calstis-7 functions which were tested.
Heliocentric velocity correction and 2-D distortion correction were tested successfully
alone and together using full-frame, subarray, binned, and unbinned test MAMA and CCD
images. Flux correction testing showed a mismatch between values output by the calstis-7 task and those calculated by hand. This problem may be due to the task’s
incorrect calculation of the inverse sensitivity function. Finally, it should be confirmed that
a problem running flux correction with 2-D correction is due to a faulty distortion table.
6