The simplest way to re-calibrate your data with the most appropriate reference files is to request the data from the archive again. However, to tailor the calibration to your individual preferences, it may be beneficial to run calstis yourself on your local machine, or to use tasks that improve the reference files or allow customized treatment of the data. The IRAF and PyRAF version of calstis, its constituent programs, and other STIS-specific tasks are available in the hst_calib.stis package in STSDAS.

To recalibrate your data, you will need to retrieve the reference files used by the different calibration steps to be performed. The names of the reference files to be used during calibration must be specified in the primary header of the input files, under the section “CALIBRATION REFERENCE FILES.” Note that the data headers will be populated already with the names of the reference files used during pipeline calibration at STScI.

Before running calstis, you will need to define an environment variable to indicate the location of the directory containing the needed calibration reference files. The names of the calibration files are preceded with the logical path name “oref$” in the STIS science headers. Ordinarily you would define this directory in an IRAF session to be, for example, “/data/vega3/stis/cal_ref/” using the set command:

Note the trailing slash (/). However, calstis and all of its modules are actually foreign tasks and as such do not access IRAF environment variables. Therefore, before invoking the cl, you will need to define an environment variable from the host command line (see below) that is appropriate to your host machine. For Unix systems, the appropriate command for the example above is:

To edit file headers in preparation for recalibration, use the STSDAS task chcalpar. The chcalpar task takes a single input parameter: the name(s) of the _raw data files to be edited. When you start chcalpar, the task automatically determines that the data are from STIS, determines the detector used and whether the observing mode was SPECTROSCOPIC or IMAGING, and opens one of four STIS-specific parameter sets (pset) that will load the current values of all the calibration related keywords. To edit the calibration keyword values:

1.

Start the chcalpar task, specifying a list of images in which you want to change calibration keyword values. If you specify more than one image (using wildcards, for example) the task will read the initial keyword values from the first image in the list. For example, you could change keywords for all STIS _raw science images in the current directory (with initial values from the first image), using the command:

After starting chcalpar, you will be placed in eparam—the IRAF parameter editor; from there you will be able to edit the set of calibration keywords. Change the values of any calibration switches, reference files or tables to the values you wish to use for recalibrating your data.

3.

Exit the editor when you are done making changes by typing “:q” two times. The task will ask if you wish to accept the current settings. If you type “y”, the settings will be saved and you will return to the IRAFcl prompt. If you type “n”, you will be placed back in the parameter editor to redefine the settings. If you type “a”, the task will abort and any changes will be discarded.

It is also possible to use hedit to update the input file keywords. The example below illustrates how to turn on the bias correction switch and update the name of the bias image reference file for all STIS _raw images in the current directory that begin with the characters “o3y.”

The flags listed in Table 3.5 as controlling the basic calibration will usually be set to PERFORM, whether or not the data is fully calibrated. For data not fully calibrated by OTFR, some or all of the flags in the last column of Table 3.5 will be set to OMIT. To fully calibrate such data, the user can reset these flags in the primary extension header of the _raw file to PERFORM, and then run the calstis task with this _raw file as input. It is also possible to reset the necessary flags in the _flt or _crj file and then run calstis with this file as input to complete the steps that were omitted by the original calibration.

If WAVECORR is set to PERFORM, an appropriate STIS line lamp image should be named in the WAVECAL header keyword. This can be either the _wav file supplied with the dataset, or if a GO specified wavecal is used, the file name of the raw wavelength calibration lamp image should be put into this keyword.

The default calibration assumes that the target was centered in the aperture along the dispersion direction. If this is not correct, the wavelength scale will be incorrect, and this offset will apply the wrong sensitivity calibration at each wavelength. In such a case it may be better to perform only the basic 2-D calibrations using the calstis task, and to then perform the spectral extraction or rectification by running the x1d or x2d tasks independently, and taking the offset in the dispersion direction into account when running those tasks (see Section 5.5.2).

It is also possible to impose a wavelength offset by setting the WAVECORR keyword in the primary extension header to COMPLETE, and then setting the desired values for the SHIFTA1 and SHIFTA2 keywords in all science extension headers of the input image before running calstis. See the description of the WAVECORR task (Section 3.4.23) for an explanation of the SHIFTA1 and SHIFTA2 keywords. However, in the absence of a valid wavecal exposure, there is no straightforward way to determine what these values should be. In general they will be non-zero even in the absence of target offsets.

When running the calstis task itself, the calibration steps are controlled by setting the values of the calibration step keywords discussed in Section 3.4. These are set in the input data file’s primary extension header. However, when running the individual standalone tasks (e.g., basic2d or x1d), the calibration steps need to be turned on or off using the input parameters of each of the standalone tasks. The values of the calibration keywords in the data file’s header are usually ignored, unless they are set to COMPLETE. Most standalone tasks will not apply a correction if the header marks it in this way as already done.

However, regardless of whether calstis or one of the stand alone tasks is being used, all reference file names must be appropriately specified in the corresponding header keywords in the input data file’s primary extension header.

Selected portions of the pipeline can be executed with special tasks in the STSDASstis package. The tasks that can be simply used in this fashion are listed in Table 3.6 below. See also Table 3.1 for the association between basic2d, ocrreject, wavecal, x1d, and x2d and the components of the calstis pipeline. See Chapter 5 for further information about some of these tasks. When you run these tasks individually, the calibration parameters usually read from the reference file must be entered either as command line arguments or via epar; however, most corrections will not be applied if the corresponding header keyword is already set to COMPLETE (see the Appendix of ISR STIS 98-26 and Section 6 of ISR STIS 98-10 for details).

The inttag task for TIME-TAG data will accumulate selected events from the raw event table, writing the results as one or more image sets (imsets) in a single, output FITS file. You can optionally specify an explicit starting time, time interval, and number of intervals over which to integrate, and the collection of imsets will be written to the output file, simulating a REPEATOBS ACCUM observation. Breaking the data into multiple, short exposures can be useful not only for variables but also to improve the flat fielding when the Doppler shift is significant. Once the new raw images have been created, it is straightforward to process them with calstis and to analyze the output image or spectra, as appropriate.

Radiation damage creates hot pixels in the STIS CCD Detector. Some of these hot pixels recover spontaneously. Many more have been repaired monthly by warming the CCD from its normal operating temperature to the ambient instrument temperature for several hours. Despite this annealing procedure, the number of permanently hot pixels has been increasing with time. The development of hot pixels is documented at:

Because the set of hot pixels changes continually, it is important to use the dark reference file prepared for the week of your observation. You should use the corresponding bias reference file, which corrects hot columns. If you requested your data close to the time of the observation, you should check whether new reference files applicable to your data have been made available since. If so, you may want to request your data from the archive again for automatic recalibration with the current reference files, since dark and bias correction occur so early in the calibration sequence.

The standard dark file subtracted from STIS data is based on a combination of several long dark files taken over an entire week. They usually don’t do a perfect job of subtracting hot pixels, both because the hot pixels can change on short time scales, and because some of the hotter pixels may have been saturated in the long dark images. It will therefore often be useful to construct a customized dark image for that particular day using short darks taken on the same day as your science image. Procedures for doing this are described at:

Even using a daydark will not give perfect removal of all bad pixels. There is no routine available that will automatically find and fix the bad pixels. It will often be necessary to identify them by hand and create a bad pixel mask. Once such a mask has been made, the IRAF routine fixpix may be useful. This task interpolates over bad pixels, and allows the bad pixel mask to be defined with a text file rather than a fits image. For data taken on the same day, most of the bad pixels will be in the same place in each image. It is therefore probably best to find the bad pixels in the _crj file, use fixpix to adjust the _crj fluxes and errors, and then run subsequent calibration and reduction programs on the corrected _crj file. For spectroscopic images of unresolved sources, interpolation within the spatially undersampled point spread function along the slit will be inaccurate, so fixpix should be used to interpolate along rows rather than along columns.

We have recommended that observers bypass the difficulties of calibrating hot pixels by using dither patterns that move the target by a few pixels from one exposure to the next. (See Section 11.3.5 in the STIS Instrument Handbook.) Spuriously high fluxes in hot pixels can then be rejected like cosmic rays when they are compared to normal fluxes in exposures made with offsets. See the following section (Section 3.5.4) for a discussion of aligning dithered images in preparation for cosmic ray rejection and for general information on handling and checking cosmic ray rejection.

For CCD datasets, calstis first runs the equivalent of basic2d with dqicorr, blevcorr, and biascorr set to PERFORM to initialize the ERR and DQ arrays, to trim the overscan regions and subtract the bias level measured there, and to subtract the bias image. It then performs cosmic ray rejection by running the equivalent of ocrreject. Next, the equivalent of basic2d is run with darkcorr and flatcorr set to PERFORM to perform dark subtraction and flat fielding. You can instead run basic2d just once on the raw data to perform all of its relevant tasks, then run ocrreject on the resulting _flt file, but this ordering of the tasks does not provide the optimum rejection of cosmic rays. The cosmic ray rejection is based on a "noise model." Part of that model is that the detected number of photons will follow a Poisson distribution. In order to compute the expected variation in detected photons at a pixel, i.e. to evaluate the noise model, you need a reasonable value for the number of electrons at that pixel. That estimate could be based on the median (for example) of the counts at that pixel in all the images that are to be combined. Because that value should reflect the number of detected photons, the bias level and bias image must first be subtracted from the images, because the electronic bias is an arbitrary offset. The data should not be corrected for dark counts or flat field, however. Dark counts do contribute to Poisson noise. The number of electrons to use for computing the Poisson distribution is the number that were actually detected, not the number corrected for variations in sensitivity. See ISR STIS 98-22 for further information on cosmic ray rejection. (Calstis was changed to perform the tasks in the order described here in July 1998, after the ISR was published.)

In cosmic ray rejection, one wants to strike a balance between failing to identify cosmic rays and clipping real flux from the target. The former lets spurious flux into the _crj image; the latter depresses the flux by systematically excluding values that are relatively high for that pixel because of noise fluctuations or small shifts of the target on the detector. Default values of cosmic ray rejection parameters to be used by calstis, or its component task ocrreject, are taken from the CRREJTAB reference file. If your _crj images still have many pixels affected by unrejected cosmic rays, you may want to try running ocrreject on the _flt files with different values for the rejection parameters, which will override the values taken from the CRREJTAB. Use crmask=yes to flag CRs in the input DQ images.

The optimum values of the cosmic ray rejection parameters depend on many factors, including the number of exposures to be combined, exposure time, signal-to-noise level, source structure, and the magnitude of the misalignment of the exposures due to drift of the target on the detector. (See ISR STIS 98-22.) For example, a small spatial misalignment of two exposures made with very high signal-to-noise may require one to increase the value of the parameter crsigmas (for a higher rejection threshold in sigmas) to avoid the systematic rejection of real flux. For a direct image or spectral image with only gradual spatial or spectral changes in flux from pixel to pixel, it may be possible to lower the rejection threshold to catch more cosmic rays without rejecting real flux. One may also need to change the value of crthresh, which sets a more stringent rejection level for the pixels surrounding a pixel that failed the crsigmas test. (e.g., for crthresh=0.5 and crsigmas=7, rejection occurs for surrounding pixels at a level of 0.5 * 7 sigma = 3.5 sigma out to a radius of crradius.)

To see if real flux is being rejected by ocrreject, one can compare the _crj image to a summed image and look for systematically lower fluxes in the _crj image. Problems will tend to occur where the pixel-to-pixel flux changes are the greatest. For a direct image, examine the pixels near the centers of point sources. For a spectral image, examine the peak rows in the spectral image. One can also examine the DQ extensions of the _flt files after they have been flagged by ocrreject (crmask = yes). Systematic problems due to spatial misalignment are especially conspicuous in the DQ extensions of the _flt files of spectral images. Improperly flagged spectral images will have strings of DQ=8192 running along a row near the spatial peak of the spectrum, since that row will be less well centered on the target in one exposure than in another. (Remember to examine the DQ extension of the _flt files instead of the _crj file, since pixels in the latter will not be flagged for cosmic rays if their flux was computed from cosmic-ray-free pixels in any of the input exposures.)

Detailed descriptions of the STIS tasks (normspflat, mkfringeflat, defringe, and prepspec) for using contemporaneous flat field images to remove IR fringing from STIS G750L and G750M spectra are given in STIS ISR 98-29. Note that this ISR was written before pixel-to-pixel flats were routinely subtracted from STIS spectroscopic data in the OTFR pipeline, and, as a result, includes some steps that are no longer always necessary.

The IR fringe flats may be taken with a variety of apertures. For point source fringe flats taken at or near a standard aperture position near the center of the detector, the best alignment between science image and fringe flat will usually be for fringe flats taken using the 0.3X0.09 aperture. For extended targets, or point sources located elsewhere along the slit, e.g., at the E1 aperture location near row 900, it will be necessary to use a long slit fringe flat, e.g, 52X0.1.

Fringe flat images taken with G750L include not only the IR fringing at wavelengths greater than 7500 Angstroms, but also some fringes at wavelengths less than 6000 Angstroms due to an order-sorter filter. Since these order-sorter fringes are already included in the sensitivity function, they should not be included in the fringe flat, and so these columns should be set to unity in the normalized fringe flat. This can easily be done by using the IRAFimcalc task to create a temporary array, and to then use the imcopy task to replace the appropriate columns in the fringe flat.

To use an exposure other than the default wavecal, the user can either (1) put the name of the raw exposure file of the lamp image to be used into the WAVECAL keyword in the primary header of the _raw science image, make sure that the WAVECORR keyword is set to PERFORM, and then run calstis as normal, or (2) use the stis task wavecal, to measure the offset of the wavelength calibration image and populate the SHIFTA1 and SHIFTA2 keywords in the science file’s extension headers. For example, if o8mi02010 is the science observation and o8mi02ovq a corresponding wavelength lamp calibration image, the command would be

This will update the SHIFTA1 and SHIFTA2 keywords and set WAVECORR to complete. The modified science image file can then be processed with calstis and/or one or more of the stand alone STIS tasks, e.g.,

Note that the wavecal task is meant to update the headers of spectral images, prior to running the x1d or x2d tasks. It should not be used on images or tables (e.g., _sx1, _sx2, _x1d, or _x2d files) that have already had wavelengths assigned to individual pixels.

The orientation of spectral traces on the STIS detectors has been found to rotate slowly over time. Additionally, there is a small random offset in the orientation each time the MSM is positioned. The time-dependent component of the orientation has been calibrated for the most commonly used grating/central-wavelength combinations: G140L/1425, G230L/2376, G230LB/2375, G430L/4300, G750L/7751, G750M/6581, G750M/6768, and G750M/8561. Calstis has been modified to apply time-dependent rotation to spectral traces, and the evolutionary parameters for these modes were included in SPTRCTAB reference files that were delivered in August and October 2006. For other L and M modes with uncalibrated trace rotation, the PyRAF task mktrace can be used to generate a SPTRCTAB with accurately rotated traces for a specific science image. The task can also be applied to data taken with the calibrated modes to correct for the random offset in orientation due to the positioning of the MSM.

The mktrace task computes the trace of the science target using the default aperture location or accepting an input location. A linear fit is made to this trace. The user can choose to exclude portions of the trace from the fit because of velocity structure, low signal-to-noise, etc. A calibration trace is interpolated from the traces at the nearest rows in the SPTRCTAB, and a linear fit is made using the same ranges of columns selected for the fitting of the science trace. Image files of the target trace and calibration trace and of the linear fits are generated to assist the user in selecting the portions of the spectrum to include in the fits. The difference in the angle of the two linear fits is the correction that must be applied to the SPTRCTAB traces. A new SPTRCTAB is generated, applying this correction to all of the traces for that grating/cenwave combination, thus covering the entire detector. The keyword SPTRCTAB in the primary header of the science image is changed to the name of the new trace file, so that subsequent processing by calstis, x1d, or x2d will use the new file.