Instrument Science Report STIS 98-14
The Calstis IRAF Calibration Tools for
STIS Data
Rocio M. Katsanis and Melissa A. McGrath
and the STIS Pipeline Block: Stefi Baum, Ivo Busko, Jennifer Christensen, Paul Goudfrooij, Jin-Chung Hsu, Phil Hodge, Steve Hulbert, and Richard Shaw.
April 26, 1998
ABSTRACT
This document describes the calstis software tools developed for the IRAF/STSDAS environment to calibrate STIS data. The calstis individual tools and their usage are briefly
described, and general examples that explain their functionality are presented.
1. Introduction.
STIS data can be of several types: clear or filtered images, slitted spectroscopy of first
order or echelle from two types of detectors (CCD or MAMA) with response ranging from
the far UV through the near IR (2500-10000A), slitless spectroscopy, time integrated
image data (TIME-TAG mode), binned data, or subarray data. Due to this wide diversity
of data types, robust software is needed to properly calibrate all the STIS data. The calstis
software is used by the STScI calibration pipeline to calibrate STIS data that are later
available to the user through the HDA (Hubble Data Archive). The calstis software is also
available to the user to perform recalibration as needed. The software consists of the general calibration program (calstis), and the stand alone routines (modules) that execute
different parts of the complete calibration pipeline. The source code of the software has
been written in ANSI-C, but the calstis modules, including the general program (calstis),
have been made available as iraf tasks for the IRAF/STSDAS environment through CL
scripts interfacing with the source code executables.
The calibration pipeline at STScI is automated, performing all the calibration steps set
to “PERFORM” in the calibration switches of the raw files, using associated wavecals and
current calibration reference files. However, there will be instances where recalibration
might be needed. For instance, the pipeline does not correct G750L or G750M spectra for
the effect of fringing using contemporaneous flats. Another example might be that the user
1
may prefer to choose to extract 1-d spectrum using user input extraction and background
boxes. Yet another example might be to combine several different crsplit datasets taken at
the same pointing. Yet another might be simply to recalibrate a dataset completely using
the latest available reference files. There are many reasons to perform recalibration of the
raw data (see section 21.5 in Data Handbook). The calstis tasks can be used to recalibrate
STIS data by including only certain steps of the calibration process, or adding extra steps
not available in the nominal pipeline.
This document presents an introduction to the calstis iraf tasks. The following section
explains the background needed to properly run the tasks. Then we provide an explanation
of each of the calstis tasks, followed by examples using astronomical data to demonstrate
the capabilities of the software.
2. Background information to properly run calstis.
The CALSTIS iraf tasks can be found in the STSDAS package stsdas.hst_calib.stis.
Table 1 describes briefly each calstis module and what they do.
Table 1. CALSTIS Iraf tasks
Task
Description
basic2d
Performs basic 2-D image reduction (bias and dark subtraction, flatfielding,
etc.)
ocrreject
Combines images, rejecting cosmic rays.
wavecal
Processes wavecal images to determine spectral and spatial shifts
x1d
Extracts 1-D spectrum.
x2d
Rectifies and wavelength and flux calibrates 2-D spectroscopic data.
calstis
“Wrapper” program that calls each of the tasks above according to calibration switch values set in the primary header of the input files.
Calstis has been designed to read all the input calibration parameters from calibration
switches and from reference files whose values and names are indicated in the primary
header of the input files. The values of the calibration switches are specified under the section CALIBRATION SWITCHES; and the names of the reference files are specified under
the section CALIBRATION REFERENCE FILES. The reference files used by the calibration pipeline, as well the as recommended current reference files, can be retrieved along
with the data from the Hubble Data Archive (HDA). A general characteristic of most of
the calstis tasks is that they can override some of the nominal switch settings and calibration reference file parameters using the input parameters of the specific task.
2
Input parameters for the calstis tasks
The input parameters of each calstis task are equivalent to the entries in the corresponding calibration switches in the primary header of the input files, and the column
entries in the corresponding reference file tables. All the input parameters included in each
task will overwrite their corresponding values in the switches and/or in the reference files.
Input parameters that correspond to calibration switches have names that end in
‘corr’ and can take the values of “PERFORM”, “COMPLETE”, or “OMIT”.
“COMPLETE” has the same effect as “OMIT” since it indicates a particular calibration
step has already been performed, and does not need to be repeated. Input parameters that
correspond to reference table values usually have names that are similar to the reference
table column name (e.g. “badinpdq’ in ocrreject which corresponds to the column of similar name in the corresponding reference table). If any of these parameters are left to their
default values (i.e null or INDEF), the entry will be read from the corresponding reference file table which is read from the header file keyword in the science header. If the
calibration reference file is missing, the task will fail and display an appropriate error message indicating which reference files are missing.
The output file primary header contain HISTORY keywords that contain general information about the calibration steps performed and the reference files used to perform these
steps. Also, the input parameters that were set to “PERFORM” and that are executed by
the tasks, are set to “COMPLETE” in the respective primary header keywords of the output files.
Environment Variables and oref
If an environment variable is needed (such as an alias or link to point to ‘oref’, the
actual directory location of any calibration reference file), it has to be defined prior to running the tasks. Be aware that the setup of environment variables is not similar to the setup
of regular iraf environment variables because the calstis tasks are not native iraf tasks. To
properly set environment variables for calstis, refer to Running calstis in IRAF in section 21.5.1 of the Data Handbook.
Wildcarding for input and output files
The calstis tasks can take wildcard file names for input and output. The standard IRAF
notation for wildcarding is supported, including * and @lists. Some examples of using
wildcards are:
•
To calibrate all files in the current directory whose names end with “_raw.fits”:
3
cl> calstis *_raw.fits
•
To perform basic-2D image reduction specifying the name of the output files by using
the same rootname as the input file but appending the suffix _flt instead:
cl> basic2d *_raw.fits *%_raw%_flt%.fits
•
To perform image rectification, where the code itself will generate the output file
names:
cl> x2d *_crj.fits ““
•
The following examples include explicit lists with input and output filenames. Both
the input and output list should contain the same amount of filenames:
cl> x1d abc1.fits,abdc2.fits,abc3.fits \
xyz1.fits,xyz2.fits,xyz3.fits verb+
cl> x1d
@in
@out verb+
Input and output files for each calstis task
Table 2 lists the possible input and output file combinations for each of the
calstis tasks. The file suffixes listed in this table are the standard nomenclature currently
used by the pipeline. The user may supersede the standard output file naming conventions
with his/her as desired. Table 2 is self explanatory. We also caution the user that cosmic
ray rejection is performed prior to bias and dark subtraction, and flatfielding in the
pipeline.
Table 2. Input and Output files for each calstis task
Task
Possible Input Files
Default Output Files
basic2d
_raw
_flt (for both CCD and MAMA)
_crj (CCD only cosmic ray rejected image)
ocrreject
_flt, _tmp_flt (CCD images that have had their
err and dq arrays initialized, the overscan bias
region subtracted)
_tmp_crj (cosmic ray rejected CCD image. This file
should go through a second pass of basic2d for bias
and dark subtraction, and flatfielding)
wavecal
_flt, _crj (flatfielded science spectra)
_wav (associated raw wavecal)
_flt, crj (keywords updated with MSM offsets calculated from wavecal and template spectrum)
x2d
_flt, _crj (flatfielded science image.
_x2d, _sx2 (rectified 2-D spectral image)
x1d
_flt, _crj (flatfielded science spectra)
_x1d, _sx1 (extracted 1-D spectra table)
calstis
_raw
Depending on calibration switch settings, output
files can be any or all of the above.
4
If an output file name already exists, the tasks will not overwrite it; instead, they will
stop running and print an appropriate message indicating that the output file already exists.
Calstis messages during execution
During the execution of any of the calstis tasks, messages are written to the standard
output where the task is being executing. We recommend paying careful attention to these
messages. They give information about the status of the task, its input and output files, the
reference files used while the task is executing, and general information pertinent to the
task (e.g. for x1d, the extraction parameters used, etc.). These messages are equivalent to
the content of the file rootname_trl.fits, messages written by calstis during pipeline
calibration. To obtain a complete information during the execution of a task, we recommend to set the input parameter “verbose” to “yes” by either setting verbose=yes or
verb+ in the respective task. The messages can be saved by directing them into an ascii
file when executing a task, using the direction sign >. For example, the following statement directs the output messages written by the task calstis while processing all the input
files, to the file “calstis.log”. We have turned on the verbose capability of the task to
include all possible messages:
cl> calstis *_raw.fits verb+ > calstis.log
3. The calstis tasks.
3.1 basic2d: basic 2-D Image Reduction.
basic2d performs two dimensional image reduction (see the description of calstis-1 in
ISR STIS 98-??). The possible input parameters are the same as the calibration switches in
the primary header keywords of the input files that control two dimensional image reduction in the standard pipeline processing. basic2d initializes the err and dq arrays and
completes basic 2D calibration: dark subtraction and flatfielding of the input images. For
MAMA images, extra steps are included such as checking for the nonlinearity of the data,
and converting the input high resolution data to output low resolution. For CCD images
the extra steps included are update of the CCD keywords in the primary header, subtraction and trimming of the bias overscan region, and subtraction of the bias file. The
standard pipeline runs basic2d twice during calibration for CCD data (see Figure 21.5 in
the Data Handbook): once to initialize the err and dq arrays of the corresponding input
files, and to subtract the bias overscan region in the sci image (dqicorr and blevcorr set to
“PERFORM”); later, after performing cosmic-ray rejection, to continue with the 2-D
image standard reduction: bias and dark subtraction, and flatfielding (biascorr, darkcorr,
and flatcorr set to “PERFORM”). To calibrate MAMA images, the task can be run just
5
once, with all the necessary input parameters set to “PERFORM”. During calibration, the
task will only read those input parameters that apply to the current input data detector (e.g.
“biascorr” is only applicable for CCD data; therefore when calibrating MAMA data the
task will ignore the entry in ‘biascorr’). Table 3 describes the input parameters to the task.
Table 4 lists the reference files needed to perform basic 2D calibration.
Table 3. Input parameters to basic2d accessible via eparam.
Parameter
Description
outblev
name of ascii file that will contain information about the bias level subtracted at each pixel position. It is valid for CCD data only and if ‘dqicorr’ is set. Can take wildcards as previously specified.
dqicorr
updates the data quality array of the input images with information taken from the bad pixel table
BPIXTAB.
atodcorr
Performs analog-to-digital correction on CCD images only. Step currently not performed.
blevcorr
Subtracts the bias from the overscan region in CCD images only.
doppcorr
<need a good explanation for this process, only knows that it applies for MAMA>
lorscorr
Converts high resolution MAMA images to low resolution images.
glincorr
Checks for non-linearity in the MAMA detector.
lflgcorr
Flags pixels for local and global non-linearity. For MAMA images only.
biascorr
Subtracts the bias reference file image from CCD input images only. If set, the name of the bias
file has to be specified in the primary header keyword BIASFILE.
darkcorr
Subtracts the appropriately scaled dark reference file image. If set, the name of the dark file has
to be specified in the primary header keyword DARKFILE.
flatcorr
Performs flatfielding of the data. If set, the names of the flat field files (if available) have to be
specified in the primary header keywords PFLTFILE, DFLTFILE, and LFLTFILE.
shadcorr
Corrects CCD images for shutter shading. Step not currently performed.
photcorr
Updates photometric keywords in the primary headers of the output images. For observations of
type imaging only. The name of the photometric table has to be specified in the primary header
keyword PHOTCORR.
statflag
Computes statistics of the output images and updates the respective extension header keywords
with this information.
6
Table 4. Reference files (keywords in primary header) used by basic2d .
Keyword
Description
BPIXTAB
Bad pixel table. To initiliaze dq array.
CCDTAB
CCD calibration parameters table. For CCD only.
BIASFILE
Bias image file name. For CCD only.
DARKFILE
Dark image file name.
PFLTFILE
Pixel-to-pixel flat field file name.
DFLTFILE
Delta flat field file name.
LFLTFILE
Low order flat field name.
APERTAB
Aperture throughput table. For both images and spectra.
PHOTTAB
Photometric throughput table. For images only.
3.2 ocrreject: Cosmic Ray Rejection
ocrreject generates a STIS CCD image free of cosmic rays from multiple exposures of
the same field (see the description of calstis-2 in ISR STIS 98-11, Shaw et. al.). The task is
similar to the STSDAS task crrej used for WFPC2 data. ocrreject combines a series of
separate CRSPLIT exposures to produce a single summed image, where discrepant input
pixel values (different by some number of sigma from the guess value) are discarded in
forming the output image. The input parameters for this task are the same cosmic ray
rejection parameters available in the cosmic ray rejection reference file CRREJTAB. ocrreject is the only task that can be executed without reading parameters from the reference
file if all the input parameters are included.
The standard pipeline runs ocrreject after DQ initialization and overscan subtraction,
but before bias and dark subtraction, and flatfielding. However, the task can be run directly
on flatfielded images to produce cosmic ray cleaned images that could continue through
the other calibration steps (x1d or x2d) if applicable.
ocrreject can take wildcards to specify all the input and output filenames. The input
parameter “all” controls if all the input files should be summed into one output file, or if
an output file should be created for each input filename.
Table 5 explains the input parameters for ocrreject.
The input images may have different exposure times. The SCI extension (e.g. [sci,n]
extensions) keyword EXPTIME should contain the exposure time for each input image.
The final combined SCI image has an effective exposure time equal to the sum of exposure
7
times of all input images. This value is written in the primary header keyword TEXPTIME. For pixels free from cosmic rays, the final pixel value is simply the sum of all input
pixel values. For pixels having one or more CR in their input stacks, the final pixel value is
the sum of the good pixels, normalized to the total exposure time of all input images. If all
pixels are bad, the output pixel value is 0.
The final ERR extension image values are proportional to the square-root of the output
SCI image, but smaller by a factor that depends upon the square-root of the number of
non-rejected input values used to compute the SCI pixel values.
The final DQ extension image is formed as the boolean AND of all input data quality
flags and the “badinpdq” parameter. The output dq image would be flagged with the CRbit (8192) if all input SCI values are rejected; this condition can happen only when a
neighboring pixel has been affected by cosmic rays, and the “crradius” and
“crthresh” parameters are different from zero.
Information about the rejection parameters used by the task are written in the primary
header keywords of the output file under the section COSMIC RAY REJECTION ALGORITHM PARAMETERS. The keyword CRCORR in the output primary header is set to
COMPLETE by ocrreject.
8
Table 5. Input parameters to ocrreject accessible via eparam.
Parameter
Description
all
A boolean parameter which indicates whether or not the input files should be summed into 1 output file. Valid entries are ‘yes’ and ‘no’.
crrejtab
Name of input cosmic-ray rejection parameters table. If given, it will overwrite the value of
CRREJTAB in the primary header keyword of the input files.
scalense
Multiplicative scale factor in percent applied to the noise. It is equivalent to the entry
SCALENSE in the CRREJTAB reference table.
initgues
Method for estimating the initial image values. Allowed values are "min", and "med". It is equivalent to the entry INITGUES in the CRREJTAB reference table.
skysub
Sky subtraction method. Allowed values are “mode” and “none”. It is equivalent to the entry
SKYSUB in the CRREJTAB reference table.
crsigmas
A single or a list of comma separated sigma values used in cosmic ray rejection for successive
iterations. If a list is included, the process will be done in iteration. For example, crsigmas="4,3"
will perform 2 iterations, the first one with a 4-sigma rejection, the second one with a 3-sigma
rejection. It is equivalent to the entry CRSIGMAS in the CRREJTAB reference table.
crradius
A real number that represents the rejection propagation radius in pixels. It is equivalent to the
entry CRRADIUS in the CRREJTAB reference table.
crthresh
A real number that represents the rejection propagation threshold to discard neighboring pixels.
It is equivalent to the entry CRTHRESH in the CRREJTAB reference table.
badinpdq
A positive integer number that represents the data quality flag bit to reject. Allowed values are all
the powers of 2 from 0 (1) to 14 (16384) or their combinations. See Data Quality Flagging on
section 20.5 of the Data Handbook for a list of all the STIS predefined data quality flags. It is
equivalent to the entry BADINPDQ in the CRREJTAB reference table.
crmask
A boolean parameter which indicates whether or not the input data quality files should be
updated to flag cosmic rays from their respective science images. Allowed values are “yes” and
“no”. It is equivalent to the entry CRMASK in the CRREJTAB reference table.
3.3 wavecal: Wavecal Processing.
wavecal determines the MSM offsets from a wavecal image and writes these offsets
values to the respective science header of the associated science image (see the description
of calstis-4,7,11 & 12 in ISR STIS 98-12, Hodge et. al.). The input files to the task are a
calibrated science image and its full associated raw wavecal image. The ‘output’ image is
the same input science image with updated information about the spectral shift calculated
from the wavecal. This information is stored in the extension header keywords SHIFTA1,
SHIFTA2, CRPIX1, and CRPIX2. If the option “save_w2d” is selected, the calibrated 2-D
rectified wavecal image with the offsets written in its header is not deleted. The output science image can continue calibration either through x2d or x1d.
9
The reference files used by wavecal are the files used to calibrate the raw wavecal
image (basic 2D and rectification), and the calibration template lamp spectrum
LAMPTAB, the lamp spectrum used as reference template to measure the shifts from.
3.4 x2d: 2-D Rectification.
x2d performs 2-D rectification of calibrated observations (see the description of calstis-7 in ISR STIS 98-13, McGrath et. al.). For imaging data, x2d performs geometric
correction. For spectroscopic data, x2d rectifies the data to produce a linear spectrum in
both the wavelength and spatial directions. Currently it is used to rectify spectroscopic
data only since we do not have appropriate reference files to rectify images yet. The input
parameters are similar to the calibration switches that control the 2-D rectification in the
primary header keywords of the input files. Table 6 explains the input parameters for the
task.
Table 6. Input parameters to x2d accessible via eparam.
Parameter
Description
helcorr
Corrects the wavelengths to a heliocentric reference frame.
fluxcorr
Converts raw counts to absolute flux units. If is set, the output spectra will be converted to flux
units, but have not been background subtracted.
statflag
A boolean parameter which indicates whether or not statistics should be computed in the output
images to update the respective extension header keywords with this information. Valid entries
are ‘yes’ and ‘no’.
The output 2-D rectified image contains as many imsets as orders available, one imset
per order. The image size of each output imset depends on the original dimensions of the
input spectrum, being slightly larger in both the dispersion and spatial directions. If neither of the two input parameters ‘helcorr’ and ‘fluxcorr’ is set, the task will only rectify
the spectra. x2d does not perform background subtraction. The spectra obtained which can
be flux corrected, contain gross counts but in flux units.
x2d reads all the information necessary to perform 2-D rectification from 6 different
reference files tables. Table 7 lists all the reference files needed by the task.
10
Table 7. Reference files (keywords in primary header) used by x2d and x1d.
Keyword
Description
APDESTAB
Aperture Description Table (APD). This table contains the geometric description of the apertures, and their offsets (in arcseconds) from a reference aperture.
APERTAB
Aperture Throughput Table (APT). This table consists of wavelength dependent transmissions
for each aperture with respect to a reference aperture. It is used in conjunction with PHOTTAB to
convert observed counts to absolute flux.
SDCTAB
Spectrum Distortion Correction Table (SDC). This table consists of a set of world coordinate
information used to construct rectified, linearized 2-D spectra. One corrected image is produced
per spectral order.
SPTRCTAB
One-D Spectrum Trace Table (1DT). This table consists of displacements of spectra along Axis 2
for determining the location of a spectrum prior to extracting the 1-D spectrum.
INANGTAB
Incidence Angle Correction Table (IAC). This table contains coefficients to fits of the change in
two dispersion coefficients (the zero-point and the first-order terms) as a function of angular offset from the reference position. These corrections are applied to the default dispersion coefficients.
MOFFTAB
MAMA Offset Correction Table (MOC). This table contains coefficients to fits of the change in
the dispersion coefficients as a function of commanded offset from the reference position. These
corrections are applied to the default dispersion coefficients. Valid for MAMA observations only.
DIPSTAB
Dispersion Coefficients Table (DSP). This table contains the coefficients to the nominal dispersion solution to be applied to the extracted of 1-D spectra.
PCTAB
Photometric Correction Table (PCT). This table contains the throughput of the instrument
configuration as a function of wavelength assuming a fixed height extraction aperture centered on
the spectrum of the point source. In x2d, it is used to calculate the value of the keyword
DIFF2PT. In x1d it is used to calculate the flux level of the 1-D extracted spectra.
PHOTTAB
Photometric Conversion Table (PHT). This table contains the throughput of the instrument
configuration for a point source as a function of wavelength assuming an infinite aperture centered on the detector.
3.5 x1d: 1-D Spectral Extraction.
x1d extracts 1-D spectra from ACCUM spectroscopic calibrated data (see the description of calstis-6 in ISR STIS 97-02, Hulbert et. al.). The input image to x1d is generally
the spectroscopic 2-D image after it has been passed through basic2d (and ocrreject for
CCD data). The input image cannot be the 2-D rectified image because the x1d routines
trace the spectrum, following a non-linear function, along the spatial axis. The spectra is
extracted along a narrow band, summing in the cross-dispersion direction, and subtracting
nearby background values to produce a 1-D array of fluxes for each spectral order. The
data are not resampled in the dispersion direction; instead, an array of wavelengths is generated. Each output spectrum is written to a separate row of FITS binary table, together
11
with the wavelength, net, gross, and background arrays. The output table also contains
arrays for error and dq values, both associated to the flux array.
The input parameters are the same calibration switches that control the 1-D spectral
extraction in the primary header keywords, and the input parameters available in the 1-D
extraction parameter table XTRACTAB which control the extraction algorithm. Table 8
explains in detail each input parameter.
x1d reads parameters from 9 different reference tables. It uses all the tables used by
x2d (see Table 7), with the exception of the spectrum distortion correction table (SDC),
and the information of an additional table, the 1-D Extraction Parameter Table (1DX),
which contains information about the extraction apertures (or ‘boxes’) and methods used
to perform 1-D spectral extraction.
3.6 calstis: The wrapper program that calls each of the calstis tasks as needed
according to the switches set in the primary header of the input files.
calstis processes STIS data through the different steps of the STIS Pipeline calibration as described before for each of the calstis tasks (see the description of calstis-0 in ISR
STIS 98-10, Hodge et. al.). Calstis is the task to be used to simply recalibrate data fully in
the exact sequence used by the pipeline. The calibration steps are controlled by the calibration switches in the primary header of the input files. See the Data Handbook for a list
of all the calibration switches available for calstis. calstis allows entering the name of a
wavecal in the input parameter ‘wavecal’ if this is not an associated one. If this parameter
is not provided, it will read the wavecal name from the primary header keyword
WAVECAL provided that the calibration switch WAVECORR is set to PERFORM. If a
wavecal is not provided and WAVECORR is set, the task will stop running displaying an
appropriate message. Intermediate calibrated files can also be saved if the parameter
‘savetmp’ is set. Finally, an optional parameter for output rootname is available in ‘outroot’. All these optional parameters can accept wildcards.
The steps specified for each of the individual calstis tasks can be globally executed by
calstis . Be aware that calstis calibrates each input dataset and produces a respective output for each of them, reading all the calibration parameters from appropriate reference
files.
12
Table 8. Input parameters to x1d accessible via eparam.
Parameter
Description
backcorr
Specifies if a background value will be subtracted from the extracted spectrum.
dispcorr
Assigns wavelengths using dispersion coefficients from the reference table DISPTAB.
helcorr
Corrects the wavelengths to a heliocentric reference frame. If ‘helcorr’ is selected, then ‘dispcorr’ has to be selected as well.
fluxcorr
Converts raw counts to absolute flux units (erg/cm2/sec/A).
sporder
Spectral order to extract. For first order spectra, this entry should be 1. For echelle, it will depend
on which order is being extracted; however, if left INDEF it will extract all echelle orders
according to specifications in the reference table. It is equivalent to the entry SPORDER in the
XTRACTAB reference table.
center
Location of the spectrum in the spatial direction. This location must be measured in the input file
of x1d . It is the central spatial location in pixel units at the center of the spectrum in the dispersion direction.
search
Range for searching the brightest line at the vicinity of ‘center’. If the value of ‘center’ is precise
this entry can be set to 0 to allow the task to extract the spectrum at the ‘center’ position. If
left INDEF , it will read this parameter from MAXSRCH in the XTRACTAB reference table
which currently covers the whole detector region (1024 pixels).
size
Size of extraction box. The extracted spectrum will be the sum of this amount of lines around
‘center’. If ‘backcorr’ is set, then a background value will be subtracted from each summed pixel
along the spatial direction according to specifications given in ‘b1siz’, ‘b2siz’, ‘o1siz’, and
‘o2siz’. It is equivalent to the entry EXTRSIZE in XTRACTAB reference table.
b1siz
Size of first background region (in pixels) below the spectrum. Used only if ‘backcorr’ is set.
b2siz
Size of second background region (in pixels) above the spectrum. Used only if ‘backcorr’ is set.
o1siz
Offset (in pixels) from ‘center’ of first background region below the spectrum. Must be a negative value.
o2siz
Offset (in pixels) from ‘center’ of second background region above the spectrum. Must be a positive value.
bktilt
Tilt between background and the detector pixels. This angle must be measured in the input file of
x1d , if sky lines are strong enough and visible to measure their tilt with respect to the spatial
direction. If left INDEF , the value will be read from the entry in BKTCOEFF in the
XTRACTAB.
bkorder
Polynomial order to fit to background prior to background subtraction. Currently it can take two
values only: 0, to subtract an average of the two background regions, and 1, to make a linear fit to
the background regions. The total background at each pixel position in the output spectrum is
written to the output 1-D extracted spectrum table.
debug
Boolean parameter that specifies whether or not create a debug file. Valid entries are ‘yes’ and
‘no’.
dbgfile
File name for debug ascii file. The information written into this file consists of the X,Y centers of
the three extraction boxes (spectrum and backgrounds). The coordinates are written in physical
image pixels, so they can be directly plotted on top of the image display to aid in checking for the
correctness of the extraction. The task always appends the debug information into whatever file
with the same name; to start a fresh file, delete the former version before running the task.
13
4. Calibration examples.
We provide here two examples in which we make use of the different calstis tasks to
calibrate data. The first example shows how to effectively remove cosmic rays from different imaging datasets of the same field of view, by combining the images into 1 final image.
The second example explains step by step calibration of echelle data.
Imaging datasets
We have selected datasets from the STIS Parallel Data, where several datasets (both
imaging and spectroscopic) were taken of the same field of view. The datasets point to a
sparse field of faint galaxies located at a high Galactic latitude (declination > 60). Figure 1
shows one raw image of this area. The calibrated data, which is available through the HST
archive, includes cosmic-ray rejected images of each dataset. Figure 2 shows a pipeline
calibrated image, where the cosmic-ray rejection was performed on the original 2 images
of 1 dataset. To improve the photometric quality of the image, and to effectively remove
cosmic rays, more than 2 images of the same field of view have to be combined, if they are
available. We have found 4 datasets, taken almost consecutively on the field shown on figures 1 and 2, which comprise a total of 7 images. We have verified that the images are
registered by measuring the positions of 3 of the brightest objects in the raw images.
To recalibrate the data to produce one image from the 4 datasets, the tasks basic2d
and ocrreject will be handy. The calibration steps to perform are: initialization of the dq
array, subtraction and trimming of the bias overscan region, cosmic-ray rejection, bias and
dark subtraction, flatfielding, and population of the photometric keywords. Since we are
recalibrating the data, it will do much better to use the most updated reference files. The
steps to perform the recalibration are:
•
Initialize the dq array and subtract the bias overscan form the original raw data, the
task basic2d can be used:
cl> basic2d *_raw.fits *%_raw%_blev%.fits
dqicorr=”perform” dqicorr=”perform”
\
\
atodcorr=”omit” blevcorr=”perform” biascorr=”omit”
darkcorr=”omit” flatcorr=”omit” shadcorr=”omit”
\
\
photcorr=”omit” stat- verb+
Note that only the parameters pertinent to CCD data have been called when calling the
task. The output files will have the same rootname as the input files but with the extension _blev.
14
Figure 1: Raw image of field of view.
•
To perform cosmic-ray rejection, we used the current updated cosmic ray rejection
parameters table. Instead of editing the keyword CRREJTAB in the primary header
of the input files with the name of this file, we are going to call the table from the input
parameters of the task. The table is in the current directory:
cl> ocrreject *_blev.fits crj_tmp.fits
\
crrejtab=”i1e1558go_crr.fits” verb+
•
To continue with the rest of the 2D standard imaging calibration, again the task
basic2d is called. We have updated the corresponding header keywords with the names
of current bias, dark and flatfields as well:
cl> basic2d crj_tmp.fits crj.fits biascorr=”perform”
darkcorr=”perform” flatcorr=”perform”
\
\
photcorr=”perform” stat+ verb+
Note that the previous steps already performed (dqicorr and blevcorr) do not need to
15
Figure 2: Pipeline cosmic-ray rejected image, using 2 images.
be set to “omit” since the corresponding keywords in the primary header have already
been set to COMPLETE by the previous execution of basic2d. The task will understand that these steps were already performed.
Figure 3 shows the final calibrated image.
Echelle data
We have selected echelle data for star BD+75D325 from calibration proposal 7096.
This dataset had originally all the calibration switches set to “OMIT”, and did not contain
an associated wavecal but an engineering one; therefore, to properly calibrate the data, the
dataset has to be associated to its engineering wavecal. The pipeline only calibrated the
engineering wavecal. The calibration can be performed in two ways: using calstis once
making sure the calibration switches are set accordingly in the primary header keyword of
the input science image; or using the tasks basic2d, wavecal, and x1d in that order to
16
Figure 3: Recalibrated final image (7 images) using the stand alone tasks.
properly extract 1-D spectra. Again, before performing recalibration, we have updated the
reference files keywords in the primary header of both raw files (the science and its engineering wavecal).
Method 1: calstis
•
Set the appropriate calibration switches in the primary header of the science file. The
following keywords have been set to PERFORM:
To perform basic 2D calibration:
LORSCORR
DQICORR
GLINCORR
LFLGCORR
DARKCORR
FLATCORR
To calculate zero-point shifts:
WAVECORR
To perform 1-D spectral extraction: DISPCORR
HELCORR
17
FLUXCORR
X1DCORR
BACKCORR
•
Run calstis including the name of the lamp exposure as input parameter:
cl> calstis o3zx05vxm_raw.fits
\
wavecal=”o3zx05vvm_raw.fits” verb+
the files o3zx05vxm_flt.fits and o3zx05vxm_x1d.fits will be created
accordingly as each step is executed.
Method 2: basic2d, wavecal, x1d
•
The calibration switches will be set from each task. To perform the first calibration,
run basic2d:
cl> basic2d o3zx05vxm_raw.fits o3zx05vxm_flt.fits
\
dqicorr=”perform” lorscorr=”perform” \
glincorr="perform” lflgcorr=”perform” \
darkcorr=”perform” flatcorr=”perform” \
stat+ verb+
Note that only the parameters pertinent to MAMA data have been called when calling
the task.
•
To calculate and write the MSM offsets to the header of the science file, run wavecal:
cl> wavecal o3zx05vxm_flt.fits o3zx05vvm_raw.fits verb+
Information about the actual shifts are also written in the iraf screen. This task calibrates the raw wavecal, calculates the MSM shifts, and writes this information in the
extension header of the science image.
•
To extract 1-D spectra from the calibrated file, run x1d:
cl> x1d o3zx05vxm_flt.fits verb+
Figure 4 shows plots of one order of the 1-D extracted recalibrated echelle spectra.
5. Current status of the software and future plans.
The calstis software continues implementation as new characteristics of the STIS
instruments are understood. Most of the implementations will be in the refinement of the
algorithms. The general syntax to call each calstis task should remain the same.
18
Figure 4: Extracted 1D spectra using the calstis tasks.
6. References
Hodge, P. & Baum, S., 1995, STIS Instrument Science Report 95-07.
Shaw, R., Hsu, J.C., et. al., 1998, STIS Instrument Science Report 98-11.
Hodge, P. et. al., 1998, STIS Instrument Science Report 98-12.
Hulbert, S., Hodge, P., & Busko, I., 1997, STIS Instrument Science Report 97-02.
McGrath, M., Hodge, P., et. al., 1998, STIS Instrument Science Report 98-13.
Hodge, P. & Shaw, R., 1998, STIS Instrument Science Report 98-10.
19