3.4 Descriptions of Calibration Steps

In this section we provide a more detailed description of the algorithms applied by calstis. As always, a given step will be performed on your data if the corresponding calibration switch in the global header of the input data was set to PERFORM (see Chapter 2). The algorithms below are described according to the major component of the calstis pipeline in which they are used, namely:

• Two-dimensional image reduction, including basic 2-D reduction, cosmic ray rejection and image co-addition.
• Processing of the contemporaneously obtained wavecal.
• Two-dimensional rectification and one-dimensional spectral extraction, with flux and wavelength calibration.

Within each component, the individual steps are listed alphabetically, because the order in which they are performed can change for different types of data (e.g., CCD or MAMA, spectroscopic or imaging, CR-SPLIT or not).

More detailed descriptions can be found in a series of Instrument Science Reports (ISRs) that discuss the pipeline. Be aware, however, that while these reports describe the original design of the pipeline and the associated algorithms in detail, they do not always contain information concerning later modifications.

3.4.1 ATODCORR: Analog to Digital Conversion Correction

• Reference file: ATODTAB

This step is part of 2-D image reduction and applies only to CCD data. Ground test results show that this correction is not currently needed, so the ATODCORR switch and the ATODTAB reference file keywords are omitted from FITS file headers. An analog to digital correction would be applied if the CCD electronic circuitry that performs the analog to digital conversion were biased toward the assignment of certain DN (data number) values.

3.4.2 BACKCORR: 1-D Spectral Background Subtraction

• Reference file: XTRACTAB

This step is a part of spectral extraction and applies to one-dimensional extraction only. If the calibration switch BACKCORR is PERFORM, the background is calculated and subtracted from the extracted spectrum. The background is extracted from regions above and below the spectrum on the detector. The size and offsets of these two background regions are specified by the BK1OFFST, BK2OFFST, BK1SIZE, and BK2SIZE columns in the XTRACTAB reference table.

For most first order spectral modes, the default background parameters, as implemented in the XTRACTAB reference table, specify background regions 5 pixels wide located ±300 pixels away from the center of the spectral extraction region. Exceptions are made for special aperture positions. For the E1 and E2 positions which are located at row 900 of the CCD, both background regions are offset below the spectral trace. For the FUV MAMA D1 aperture positions, which are located near the bottom of the FUV MAMA detector, below the region of enhanced dark current, (see Section 4.1.3), the background regions are only ±30 pixels from the trace. The assumption is that most observations specifying the D1 position will be of very faint point source targets, where measuring an accurate local background is critical. See Table 3.1 for a summary of the default background extraction parameters implemented in the XTRACTAB reference table.

Table 3.1: Default Background Parameters

The background extraction is done one column at a time, with the average background values (in counts/sec/pixel) calculated (with 3σ clipping) from each background bin, accounting for fractional pixel contributions. The background in each region is then smoothed with an algorithm that depends on the mode in use.

For CCD data, the raw background, after 1-D extraction, is smoothed by a running window low-pass filter (i.e. boxcar smoothing) with a 9 pixel window, then fitted by an nth degree polynomial. The value of the bksmode parameter defines the boxcar smoothing function to be either a median or average within the running window. The polynomial degree is defined by the bksorder task parameter. The default value for the bksorder parameter is 3, and this is what is used in the pipeline.

For MAMA first order data, the 1-D extracted background is fitted by an nth degree polynomial, and the background is replaced by the fitted curve. The data are not filtered before the polynomial fit, and so for MAMA first order data, the result is the same whether bksmode is set to median or average. The polynomial degree is defined by the bksorder task parameter. For the G140L/M first order gratings, the regions around Lyman α and the 1300 Angstrom O I line are not smoothed.

The background vectors for the two background regions are then combined, either by simply taking the average value at each wavelength (backord=0), or by linear interpolation between the upper and lower regions values (backord=1). The parameter backord is read from the XTRACTAB reference table. The total background at each pixel in the output spectrum is then written to the output data table.

In general, the background or sky is not aligned with the detector pixels. To accommodate this misalignment, the definition of the background extraction apertures includes not only a length and offset (center-to-center) but also a linear tilt to assist in properly subtracting the background. This tilt is taken into account when calculating the average background in the background extraction boxes. The coefficients describing this tilt are given in the BKTCOEFF column of the XTRACTAB table.

For echelle data, the default is to determine the background as part of the SC2DCORR calibration step. However, the background can optionally be determined by direct measurement in a background region by setting SC2DCORR to OMIT, and this simpler background subtraction is needed in any case in the early stages of the SC2DCORR procedure. When the background subtraction is done in this way for echelle observations, the measured background is smoothed twice with a 31 pixel wide boxcar window.

3.4.3 BIASCORR: Small Scale Bias Subtraction

• Reference file: BIASFILE

This step is part of basic 2-D image reduction and is performed only for CCD data, removing any two-dimensional additive stationary pattern in the electronic zero point of each CCD readout. To remove this pattern, a bias reference image is subtracted. The bias reference file is a full format superbias image created from many bias frames to assure low noise. Separate bias files are used for different values of binning and for different values of gain. The bias image has an associated data quality image extension; bad pixels in the bias image are flagged in the science data quality image.

3.4.4 BLEVCORR: Large Scale Bias & Overscan Subtraction

• Reference file: none

This step is part of basic 2-D image reduction and is performed only for CCD data. This step subtracts the electronic bias level for each line of the CCD image and trims the overscan regions off of the input image, leaving only the exposed portions of the image. Thus, the BLEVCORR corrects the large scale bias (a plane), while BIASCORR corrects the small scale (pixel by pixel) bias.

Because the electronic bias level can vary with time and temperature, its value is determined from the overscan region in the particular exposure being processed. A raw STIS CCD image taken in full frame unbinned mode will have 20 rows of virtual parallel overscan in the AXIS2 (image y) direction, which is created by over-clocking the readout of each line past its physical extent, and 19 leading and trailing columns of serial physical overscan in the AXIS1 (image x) direction, which arise from unilluminated pixels on the CCD. Thus the size of the uncalibrated and unbinned full frame CCD image is 1062 (serial) × 1044 (parallel) pixels, with 1024 × 1024 exposed science pixels.

The virtual overscan region is screened to identify and reject outliers that may be caused by hot columns. The median of those values in the virtual overscan region, but not in the parallel overscan region is taken. Then the quantity MAD is defined to be the median of the absolute values of the deviations from the median, and sigma is defined to be the square root of the sum of the squares of the differences between values and the median, ignoring any value that differs from the median by more than 4.5*MAD. The value blev_clip is the value taken from the appropriate row of the CCD parameters table. An outlier is then taken to be any value that is greater than median + blev_clip * sigma. These outliers are then replaced with the median of the values in the same row that are within ±10 pixels of the outlier, although if an outlier is closer than 10 pixels to the left (or right) edge, then the median of the 21 values adjacent to the right (or left) edge is taken instead.

Both the serial (physical) and virtual (parallel) overscans are used for the overscan bias level determination. A line-by-line subtraction is performed in the following way. An initial value of the electronic bias level, or overscan, is determined for each line of the image, using the serial and parallel overscans, and a function, currently a straight line, is fit to these values as a function of image line. This determines the slope of the bias level across the image at each line. The actual overscan value subtracted from an image line is the value of the linear fit at that image line. The initial value for each line is found by taking the median of a predetermined subset of the trailing serial overscan pixels. Currently, that region includes most of the trailing overscan region, however the first pixel and last three pixels are skipped, as they have been shown to be subject to problems; pixels flagged as bad in the input data quality flag are also skipped. The region used changes as a function of the binning or sub-array (see Table 3.2). The mean value of all overscan levels is computed and the mean is written to the output SCI extension header as MEANBLEV.

In addition to subtracting the electronic bias level, the BLEVCORR step also trims the image of overscan. The sizes of the overscan regions depend on binning and whether the image is full frame or a subimage. The locations of the overscan regions depend on which amplifier was used for readout. The number of pixels to trim off each side of the image (before accounting for readout amplifier) is given in Table 3.3. The values of NAXIS1, NAXIS2, BINAXIS1, and BINAXIS2 are obtained from image header keywords. Because the binning factor does not divide evenly into 19 and 1062, when on-chip pixel binning is used the raw image produced will contain both pure overscan pixels, overscan plus science pixels, and science pixels. The calstispipeline will only calibrate pixel binnings of 1, 2, and 4 in either AXIS1 or AXIS2.

The keywords CRPIXi (giving the pixel coordinates of the reference pixel) and LTVi (giving the pixel coordinates of the subsection start) are updated in the output. These depend on the offset due to removal of the overscan.

Table 3.2: Raw Image Pixels Used to Determine Line by Line Bias Level

Table 3.3: Pixels Trimmed During CCD Bias Level Correction for Amp D

3.4.5 CRCORR: Cosmic Ray Correction

• Reference files: CRREJTAB & CCDTAB

CRCORR step is applicable only to CCD data: it is applied by the ocrreject task partway through the basic 2-D reduction process as described at the beginning of Section 3.2. For STIS, the recommended procedure for observations longer than several minutes is to obtain two or more identical exposures so that an anti-coincidence technique can be used in the data calibration pipeline. For this reason, the CCD exposures are split into multiple associated exposures, specified by the number of iterations NRPTEXP or CRSPLIT parameters, with roughly the same exposure times. The CRCORR step sums the individual CRSPLIT exposures in an associated dataset, producing a single cosmic ray rejected file (rootname_crj.fits).

The CRCORR contains the following steps:

• Forms a stack of images to be combined (the CRSPLIT or NRPTEXP exposures in the input file).
• Forms an initial guess image (minimum or median).
• Forms a summed CR-rejected image, using the guess image to reject high and low values in the stack, based on sigma and the radius parameter that signifies whether to reject pixels neighboring cosmic ray impacts.
• Iterates, using different (usually decreasing) rejection thresholds to produce a new guess image at each iteration.
• Produces a final cosmic ray rejected image (_crj), including science, data quality, and error extensions, which is the sum of the input images. Then updates various header keywords.
• Flags the data quality arrays of the individual (non-CR-rejected) input files to indicate where an outlier has been found (pixels that were rejected because of cosmic ray hits can be identified by looking for data quality bit = 14 in the _flt file).

Note that the _crj image is the sum of the input CR-SPLIT images. For each pixel in the _crj image, the sum has been scaled to reflect any cosmic ray rejections in the individual images contributing to that sum; thus, the counts in every _crj pixel correctly reflect the total exposure time (TEXPTIME) of the CR-SPLIT images. For example, if CRSPLIT=3, and one of the 3 input pixels contributing to a given pixel in the _crj file is rejected during CRCORR, that pixel in the _crj file will be the sum of the 2 good input pixels, scaled by 3/2.

If skysub=mode, a sky value is calculated as the mode in all pixels for each input image and subtracted from each pixel value prior to the identification of cosmic rays; afterwards, it is restored. If sky=none, no background is subtracted.

The method for forming the initial guess image is controlled through the parameter initguess, which takes the median or minimum pixel value to indicate which of these in the stack, at each pixel, is to be used. Only input pixels whose data quality flags are not set to the badinpdq parameter are used to form the guess. The bad pixel masking takes place prior to forming the initial guess image, which prevents bad data in a single input image from contaminating the output product.

The cosmic ray rejected image is created by setting the value at each pixel to the sum of the values of all good pixels in the stack whose values are within ±crsigmas*NOISE of the initial guess image. Deviant (out of range) stack pixels are flagged as cosmic ray impacted by setting their stack data quality flags to 2¹³ = 8192 in the input file.

The value of $//<![CDATA[ \begin{array}{l}NOISE\end{array} //]]>$ (in DN) is computed as:

where:

• $//<![CDATA[ \begin{array}{l}DN\end{array} //]]>$ = the data number of the stack pixel value in counts.
• $//<![CDATA[ \begin{array}{l}READNSE\end{array} //]]>$ is the read noise in electrons, read from the value of the primary header keyword READNSE.
• $//<![CDATA[ \begin{array}{l}ATODGAIN\end{array} //]]>$ is the calibrated conversion from electrons to DN, read from the primary header keyword ATODGAIN.
• $//<![CDATA[ \begin{array}{l}scalense\end{array} //]]>$ is an input parameter, read from the CRREJTAB ­calibration ­reference file.

The crsigmas parameter is a string, e.g., crsigmas = "4,3", read from the CRREJTAB calibration reference file. The number of entries in the string dictates the number of iterations to be performed (in this example two) and the values in the string indicate the value of crsigmas for each iteration. In this example, stack values that deviate from the guess image value by more than 4*NOISE in the first iteration are considered to be outliers and are excluded from the average on the first iteration when an improved guess image is formed. A second iteration is then performed in which crsigmas is set to 3 and good stack values disparate by more than ±3*NOISE from the guess image are excluded when determining the average. In each iteration, if crradius is not INDEF, then pixels neighboring rejected pixels will be subjected to a more stringent rejection test. Most CR impacts affect more than one pixel. For this reason, the mechanism is designed to permit neighboring pixels to be examined as separate cases with more stringent rejection thresholds to exclude cosmic rays (see STIS ISR 98-11).

The scalense parameter is a string containing a multiplicative factor in the noise relation, linearly proportional to the signal level. This allows for the treatment of extra noise due to other factors, such as image motion (e.g., a bright star in one pixel moving to the next could erroneously get flagged as a CR). If scalense = “2.0”, then the term 0.02*value is added in quadrature to the noise. This term accounts for multiplicative effects that would be expected if this rejection were applied to flat-fielded data. The scalense parameter allows well exposed regions to be used (such as the centers of stars, where jitter from the telescope may slightly change the pointing from image to image), rather than incorrectly rejecting such regions as cosmic rays.

The combination of the individual CRSPLIT or NRPTEXP exposures into a single cosmic ray rejected frame is performed early in the calstis flow. The cosmic ray rejection is performed after each exposure has had its data quality file initialized (DQICORR), the overscan bias level subtracted (BLEVCORR), and the bias frame subtracted (BIASCORR), but prior to subtraction of a dark frame (DARKCORR) and flat fielding (FLATCORR). The CR-rejected image is then passed through the remainder of the two-dimensional image reduction to produce a flat-fielded, CR-rejected image (rootname_crj.fits). This CR-rejected flat-fielded image is then passed through the subsequent processing steps in calstis. If EXPSCORR is set to PERFORM (see below), then the individual flat-fielded but not cosmic ray rejected exposures are also produced.

The strategy for optimizing the CR rejection parameters for the STIS pipeline is explained in detail in STIS ISR 98-22.

3.4.6 CTECORR: Correction for Charge Transfer Inefficiency Losses

• Reference files: CCDTAB & PCTAB

Extracted one-dimensional fluxes for first order CCD spectra are corrected for losses due to imperfect charge transfer efficiency (CTE) using an empirical algorithm described in STIS ISR 2006-03 and Goudfrooij et al. (2006, PASP, 118, 1455). The CTECORR processing is done only for STIS CCD spectra, and only as part of the FLUXCORR step in the x1d (calstis6) task. A separate CTECORR flag is available that allows this correction to be turned off when FLUXCORR is set to PERFORM. No CTE correction is applied to the flux calibration for two-dimensional rectified spectra (x2d task or calstis7). This empirical correction algorithm was designed to be used with full frame CCD data, and so for data taken using sub-arrays, the pipeline sets CTECORR to OMIT, although users recalibrating spectral data themselves may choose to apply the CTE correction; in this case, the CTE calculation is done by treating the sub-array as the appropriate piece of a full frame image. The correction also assumes that the standard 7 pixel high extraction box for CCD first order spectra is used, and that standard background regions were specified. If the gross flux in a pixel in an _x1d or _sx1 table is ≤ 0, then the CTE correction is not applied to that flux and the DQ value for that pixel includes the value 16384.

The CTE correction factor applied to the flux is 1/(1-CTI)(^1025-Y), where Y is the position on the detector of the center of the spectrum at that wavelength, and CTI is the fractional charge loss per transfer. The CTI (charge transfer inefficiency) is calculated separately for each wavelength bin of the detector.

The formula for the CTI is

where:

$//<![CDATA[ \begin{array}{l}G\end{array} //]]>$ = Gross electrons per pixel per exposure in the extraction region for that wavelength bin,

$//<![CDATA[ \begin{array}{l}B^\prime\end{array} //]]>$ = Total background in electrons per pixel per exposure $//<![CDATA[ \begin{array}{l}(DARK + SKY + SPURCHARGE)\end{array} //]]>$.

If $//<![CDATA[ \begin{array}{l}B^\prime < 0\end{array} //]]>$, then the factor $//<![CDATA[ \begin{array}{l}\exp{(CTIBGFAC \cdot ((B^\prime + HALOFAC \cdot HALOPAR) / G)^{CTIBGPOWER})}\end{array} //]]>$ is replaced by unity.

The coefficients $//<![CDATA[ \begin{array}{l}CTINORM\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}CTIGPOWER\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}CTIREFMJD\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}CTITIMFAC\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}CTIBGFAC\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}HALOFAC\end{array} //]]>$, and $//<![CDATA[ \begin{array}{l}CTIBGPOWER\end{array} //]]>$ are taken from the CCDTAB. EXPSTART is the exposure start time from the extension header.

The $//<![CDATA[ \begin{array}{l}SKY\end{array} //]]>$ is the background in electrons per exposure per pixel as measured by the BACKCORR procedure, while the $//<![CDATA[ \begin{array}{l}DARK\end{array} //]]>$ is taken from the MEANDARK keyword, put into the extension header by the DARKCORR calibration step, multiplied by the gain to convert to units of electrons. The spurious charge is taken from the SPURCHARGE column of the CCDTAB reference table.

For gratings other than G750L and G750M, $//<![CDATA[ \begin{array}{l}HALOPAR\end{array} //]]>$ is defined to be zero. For G750L and G750M,

The encircled energy fractions tabulated in the PCTAB reference table are used to compute $//<![CDATA[ \begin{array}{l}FRACHALO\end{array} //]]>$, which is defined to be the fraction of the PSF above the default extraction box of 7 pixels. The value of $//<![CDATA[ \begin{array}{l}HALOMINFRAC\end{array} //]]>$ is taken from the CCDTAB, and the $//<![CDATA[ \begin{array}{l}NET\end{array} //]]>$ is the net electrons per exposure in each individual wavelength bin.

A stand-alone pixel-based CTI correction script has been developed to model the detector level physics of CTI effects, and then correct each pixel to the proper counts. The script can be found at: http://www.stsci.edu/hst/instrumentation/stis/data-analysis-and-software-tools/pixel-based-cti. The pixel-based algorithm iteratively relocates counts on the detector to nearby pixels and has been demonstrated to help remove trails and other artifacts caused by CTI effects on the CCD detector (see STIS ISRs 2015-04 and 2015-05 for details). Please note that only one type of CTE correction should be applied to an image, i.e., if the pixel-based correction will be used, then the empirical correction should be turned off by setting the CTECORR flag to OMIT.

3.4.7 DARKCORR: Dark Signal Subtraction

• Reference files: DARKFILE & CCDTAB

The DARKCORR step is part of basic 2-D image reduction and removes the dark signal (count rate created in the detector in the absence of photons from the sky) from the uncalibrated science image. If the science image is a sub-array or was binned, the relevant section of the dark reference image must be selected and binned to match the science image. If the Doppler correction was applied onboard for the science data (i.e., if DOPPON = T, or, in the case of TIME-TAG data, if DOPPON = F and DOPPMAG > 0), the Doppler smearing function is computed and convolved with the dark image (if DOPPCORR=PERFORM) to account for the contributions of various detector pixels to a particular image pixel. This is done before binning the dark image and applies only to MAMA data taken with the first order medium resolution gratings or in the echelle gratings. The science data quality file is updated for bad pixels in the dark reference file.

The mean of the dark values subtracted is written to the SCI extension header with the keyword MEANDARK. For CCD data, the dark image is multiplied by the exposure time and divided by the ATODGAIN (from the CCD parameters table) before subtracting.

CCD Darks

After the failure of the primary (Side-1) STIS electronics in July 2001, STIS began operating using the redundant Side-2 electronics. Side-2 does not have a functioning temperature sensor for the CCD, and so a constant current is applied to the CCD thermoelectric cooler. This leads to variations in the detector temperature and corresponding variations in the dark current. Although the temperature of the CCD itself can no longer be measured directly, there is a sensor that can measure the temperature of the CCD housing, and this appears to be a good surrogate for tracking the CCD temperature and dark current variations. The dark current is typically observed to increase by about 7% per degree C for the average pixel, however, there have been minor fluctuations in this value over the history of Side-2 observing. See STIS ISR 2001-03 and 2018-05 for further details.

Before being subtracted from the science data, Side-2 CCD darks are scaled by the factor 1+DRK_VS_T·(OCCDHTAV-REF_TEMP), where OCCDHTAV is the average CCD housing temperature in degrees Celsius, DRK_VS_T is the slope of the dark scaling relation given as a keyword in the dark reference file header, and REF_TEMP is the reference temperature used to derive that slope, also found as a keyword in the dark reference file header.

For some Side-2 CCD observations, _epc (Engineering Parameter Calibration) files are available from the archive which tabulate the housing temperature values as a function of time during the observation. If _epc files are available for the observation being processed, the values tabulated in the _epc file are evaluated to give the appropriate time average temperature for each exposure. The average temperature from the _epc file is used to update the OCCDHTAV header keyword prior to scaling the darks.

Hot pixels, caused by radiation damage, also occur in the STIS CCD. Annealing of hot pixels is performed by raising the temperature of the CCD from its normal operating temperature (-83 °C) to the ambient value of 5 °C. Analysis of the on-orbit data has shown that this process is successful in removing 73.1% of the transient pixels hotter than 0.1 e¯/sec/pix for Side-1 and 49.1% of the transient pixels hotter than 0.1 e¯/sec/pix for Side-2. While post-pipeline calibration using appropriate STIS reference superdarks allows one to subtract most hot pixels correctly, the best way to eliminate all hot pixels is by dithering (making pixel-scale positional offsets between individual exposures).

MAMA Darks

The NUV dark current is believed to be primarily due to phosphorescent glow from impurities in the detector window. Over short time scales, this glow varies exponentially with detector temperature, as the metastable states responsible are more easily de-excited at higher temperatures. Over longer time scales the behavior becomes more complex, as the population of these metastable states changes over time in response to both the previous thermal history and the incident high energy particle flux.

To correct for the dark current changes, the NUV dark reference image specified in the DARKFILE keyword is scaled by a factor based on the NUV dark time correction table (TDCTAB) reference file. For NUV-MAMA data obtained prior to the HST Servicing Mission 4 (SM4) on May 2009, the scale factor is

where $//<![CDATA[ \begin{array}{l}T\_Dark = MAX(\texttt{OM2CAT}, \texttt{T_MIN})\end{array} //]]>$. OM2CAT is the NUV-MAMA detector amplifier temperature in units of degrees Celsius; it appears as a keyword in the science extension header of each image. $//<![CDATA[ \begin{array}{l}SCALE\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}NORM\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}T\_MIN\end{array} //]]>$, and $//<![CDATA[ \begin{array}{l}THERMCST\end{array} //]]>$ are tabulated as a function of observation date in the NUVTDCTAB. In practice, only $//<![CDATA[ \begin{array}{l}NORM\end{array} //]]>$ and $//<![CDATA[ \begin{array}{l}T\_MIN\end{array} //]]>$ change as a function of time. $//<![CDATA[ \begin{array}{l}SCALE\end{array} //]]>$ = 1.805 × 10²⁰ and $//<![CDATA[ \begin{array}{l}THERMCST\end{array} //]]>$ = 12211.8 K for all entries. $//<![CDATA[ \begin{array}{l}T\_MIN\end{array} //]]>$ varies between 31.5 ˚C and 35.2 ˚C, and $//<![CDATA[ \begin{array}{l}NORM\end{array} //]]>$ is of order unity.

For NUV-MAMA data obtained after the SM4, an updated relation has been derived to account for both long-term and short-term variations (see STIS ISR 2013-01 for details). The average dark count rate at a given date and detector temperature is estimated as

where $//<![CDATA[ \begin{array}{l}D\end{array} //]]>$ is the Julian date of the observation, $//<![CDATA[ \begin{array}{l}DATE0\end{array} //]]>$ is the Julian starting date of each “segment” (the currently used TDCTAB is divided into three segments with starting dates of Aug 6, 2009, Sep 9, 2009, and Nov 16, 2010), and $//<![CDATA[ \begin{array}{l}TEMP0\end{array} //]]>$ is the reference temperature set to 38 ˚C. $//<![CDATA[ \begin{array}{l}A1\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}A2\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}D1\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}D2\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}TA\end{array} //]]>$, $//<![CDATA[ \begin{array}{l}TB\end{array} //]]>$, and $//<![CDATA[ \begin{array}{l}TC\end{array} //]]>$ are the fit parameters that are listed in the TDCTAB along with $//<![CDATA[ \begin{array}{l}DATE0\end{array} //]]>$ and $//<![CDATA[ \begin{array}{l}TEMP0\end{array} //]]>$. Once the $//<![CDATA[ \begin{array}{l}count\_rate\end{array} //]]>$ is calculated for a given exposure using the equation above, the scale factor is determined by dividing $//<![CDATA[ \begin{array}{l}count\_rate\end{array} //]]>$ by the mean dark rate of the dark reference image (DARKFILE). The resulting scale factor is then applied to the DARKFILE before the dark subtraction is performed.

3.4.8 DISPCORR: Apply Dispersion Solution

• Reference files: DISPTAB, INANGTAB, & APDESTAB

This step is a part of spectral extraction or rectification. Wavelengths are assigned to pixels in extracted spectra using dispersion coefficients from the reference table DISPTAB when the calibration switch DISPCORR is PERFORM; if DISPCORR is OMIT, no wavelengths are assigned. The pipeline performs DISPCORR for _x2d files whether or not DISPCORR is set to PERFORM, using interpolation to produce a linear wavelength scale. More details on the DISPCORR calibration step are given in STIS ISR 99-03 (for x1d) and STIS ISR 98-13 (for x2d).

The DISPTAB table contains dispersion solutions for a defined reference aperture. For L and M modes and the PRISM, solutions are given at numerous Y positions that span the detector. For the L, M, and E modes, the dispersion solution has the following form:

where

• $//<![CDATA[ \begin{array}{l}\lambda\end{array} //]]>$ is the vacuum wavelength in Angstroms.

• $//<![CDATA[ \begin{array}{l}s\end{array} //]]>$ is the detector AXIS1 position.
• $//<![CDATA[ \begin{array}{l}m\end{array} //]]>$ is the spectral order.
• $//<![CDATA[ \begin{array}{l}A_i\end{array} //]]>$ are the dispersion coefficients.

For the PRISM, used with the NUV-MAMA detector, the dispersion relation gives wavelength as a function of pixel position as follows:

Offsets introduced by using apertures other than the reference aperture are removed using coefficients (IAC_COEFF) in the INANGTAB reference table. The A₀ parameter in the dispersion relation is modified as follows: $//<![CDATA[ \begin{array}{l}A_0^\prime = A_0 + IAC\_COEFF \times \Delta x\end{array} //]]>$, where $//<![CDATA[ \begin{array}{l}\Delta x\end{array} //]]>$ is the x offset between the apertures in pixels, determined from the APDESTAB.

Offsets due to MSM shift determined from wavecal exposures are corrected for by applying a linear offset after all other corrections have been made. For all modes, small offsets occur because of non-repeatability in the positioning of the MSM and thermal drift (see Section 3.4.23). Additionally, for MAMA L and M modes, and for echelle modes until August 2002, offsets of the projection of the spectrum onto the detector in both the spectral and spatial directions have been deliberately introduced by offsetting the Mode Select Mechanism (grating wheel) tilts. This has been done approximately monthly to assure a more uniform charge extraction from the micro-channel plate over time. Determination of these induced offsets is included in the wavecal processing, and they are subtracted along with the random MSM offset.

In x1d, for grating spectra, the Newton-Raphson method is applied to the first dispersion relation given above to solve for the wavelength, while for PRISM data the wavelength is computed directly from the second dispersion relation. The x2d task linearizes the wavelength scale and solves for pixel number as a function of wavelength (and spectral order). For grating spectra, the first equation is evaluated directly, and for prism data the pixel number from the second equation is found using binary search.

3.4.9 DOPPCORR: Correct Reference Files for Doppler Shift

• Reference files: none

This step is part of basic 2-D image reduction and is performed only for spectroscopic data taken with the MAMA detectors (the correction is not significant for CCD spectroscopy, which is at lower resolution). When MAMA data are taken in ACCUM mode in the first order medium (M) gratings or the echelle modes, the MAMA flight software corrects the location of each photon for the Doppler shift induced by the spacecraft motion, prior to updating the counter in the ACCUM mode image being produced. In this case, the flat field and dark reference files should be convolved with the Doppler smearing function, because the counts on a single image pixel were actually detected at different (Doppler shifted) detector pixel locations. Therefore, during basic two-dimensional image reduction of the MAMA data, the darks and flats must be processed with the same Doppler smoothing as the science data prior to application of the reference image. Because this is not an independent routine, but a modifier for the steps DQICORR, DARKCORR and FLATCORR, the DOPPCOR flag is never set to COMPLETE.

The first step is to compute an array containing the Doppler smearing function. The expression below gives the computed Doppler shift, where the time t begins with the value of the header keyword EXPSTART and is incremented in one second intervals up to EXPSTART + EXPTIME inclusive. At each of these times, the Doppler shift in unbinned pixels is computed as:

where DOPPMAG is the Doppler shift amplitude in high res pixels, DOPPZERO is the time when the Doppler shift was zero and was increasing (i.e., near when the HST was closest to the target) and ORBITPER is the orbital period of the HST in seconds. DOPPMAG, DOPPZERO and ORBITPER are all SCI extension header keywords. If a photon hits detector location (X,Y), then pixel (X+shift,Y) in the image would have been incremented. Therefore, a positive shift means that the reference files (dark and flat) should be shifted to the right before being applied. The value of shift, estimated from the above equation, is rounded to the nearest integer.

In TIME-TAG mode with the medium or high resolution echelles, this correction is not applied onboard, but is done by Generic Conversion when making an ACCUM image from the TIME-TAG table. The Doppler corrected coordinates are then written in a new column in the TIME-TAG table (rootname_tag.fits). When the TIME-TAG data are integrated in time (in Generic Conversion or by using inttag) to produce an uncalibrated accumulated science image (rootname_raw.fits), it is the Doppler corrected positions that are used.

3.4.10 DQICORR: Initialize Data Quality File

• Reference file: 

The DQICORR step is part of basic 2-D image reduction. This routine takes the initial data quality file output for the science data and performs a bitwise OR with the values in the bad pixel reference file table (BPIXTAB) to initialize the science data quality file for propagation through subsequent steps in calstis. If DOPPCORR=PEFORM, calstis will combine data quality information from neighboring pixels to accommodate Doppler smearing prior to performing the OR operation with the (unsmeared) science input data quality image. The DQICORR step also appropriately combines data quality flags in neighboring pixels if the images are binned.

For CCD data, this step also includes a check on saturation, comparing the science data values with the saturation level read from the CCD parameters table (CCDTAB). It also flags the regions of the CCD beyond the edge of the aperture to prevent problems with sky level computation and cosmic ray rejection. When a large fraction of the image is not illuminated, the computation of the sky level can be seriously affected. The aperture size is read from the APER_FOV keyword.

3.4.11 EXPSCORR: Retain Individual CR-SPLIT Exposures

• Reference file: none

The EXPSCORR step is a part of basic 2-D image reduction, for CCD data only. If the EXPSCORR calibration switch in the header is set to PERFORM, the pipeline will also process the SCI extensions in the _raw files as individual exposures through calstis, outputting an intermediate product, rootname_flt.fits. This file contains the individual flat-fielded CRSPLIT exposures in successive imsets of a single file. This file will not be passed through the subsequent calibration steps (e.g., spectroscopic reduction), but will be retained as an intermediate data product, to allow users to see exactly which pixels were excluded from the summed, cosmic ray rejected image.

3.4.12 FLATCORR: Flat Field Correction

• Reference files: PFLTFILE, DFLTFILE, & LFLTFILE

The FLATCORR step is part of basic 2-D image reduction and corrects for pixel-to-pixel and large scale sensitivity gradients across the detector by dividing the data by a flat field image. The flat field image used to correct the data is created from three flat field reference files:

• PFLTFILE - This flat is a configuration (grating, central wavelength and detector) dependent pixel-to-pixel flat field image, from which any large scale sensitivity variations have been removed (i.e., it will have a local mean value of unity across its entirety). Such configuration dependent flats are produced infrequently.
• DFLTFILE - This file is a delta flat that gives the changes in the small scale flat field response relative to the pixel-to-pixel flat (PFLTFILE). Delta flats are not currently used.
• LFLTFILE - This flat is a subsampled image containing the large scale sensitivity variation across the detector. It is usually grating- and central wavelength-dependent (for spectroscopic data) and aperture (filter) dependent for imaging data.

To flat field science data, calstis creates a single flat field image from these three files^[1] as described below and then divides the science image by the flat so created. The pixels of the science data quality file are updated to reflect bad pixels in the input reference files, and the errors in the science data are updated to reflect the application of the flat. Blank and “N/A” values of PFLTFILE, DFLTFILE, or LFLTFILE in the science data’s header indicate that type of flat is not to be used.

To create the single combined flat field file, calstis first expands the large scale sensitivity flat (LFLTFILE) to full format, using bilinear interpolation. The pixel-to-pixel flat, delta flat, and expanded low order flat are then multiplied together. For MAMA data, the product of the flat field images will be convolved with the Doppler smoothing function if DOPPCORR=PERFORM. If a sub-array or binning was used, 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 are then divided by the binned subset.

The error and data quality arrays in the calibrated file are updated to reflect the error and data quality from the flat field (i.e., the errors are rescaled by the flat field, and the errors associated with the flat field are added in quadrature). If Doppler convolution is applied, a correction is also applied for the loss of counts at the image edges due to flight software’s “effective sub-array” (see STIS ISR 98-05 for details).

3.4.13 FLUXCORR: Conversion to cgs Flux

• Reference files: APERTAB, GACTAB, PHOTTAB, PCTAB & TDSTAB

This step is part of spectral extraction (X1DCORR) and spectral image rectification (X2DCORR) if FLUXCORR is PERFORM. (See also Section 3.4.6 for CTECORR, which is used in the extraction of point sources from full frame CCD spectral images.) Counts in _flt or _crj images are corrected to flux (erg cm^-2 sec^-1 Å^-1) in the _x1d file or to surface brightness (erg cm^-2 sec^-1 Å^-1 arcsec^-2) in the _x2d file. The flux calibration used in one-dimensional extraction is correct for a point source only, since it applies slit width and extraction height corrections appropriate for a point source. The surface brightness calibration used in the production of rectified spectral images is appropriate for diffuse sources, since no correction is made for slit losses.

Execution of this calibration step requires that wavelengths have been assigned previously by DISPCORR. Corrections for vignetting and echelle blaze are handled within the PHOTTAB reference files.
The conversion to absolute flux for a point source is calculated as:

where:

• $//<![CDATA[ \begin{array}{l}F_\lambda\end{array} //]]>$ is the calibrated flux at a particular wavelength. This quantity is also multiplied by the ATODGAIN if the data were obtained with the CCD.
• $//<![CDATA[ \begin{array}{l}h\end{array} //]]>$ is Planck’s constant.
• $//<![CDATA[ \begin{array}{l}c\end{array} //]]>$ is the speed of light.
• $//<![CDATA[ \begin{array}{l}g\end{array} //]]>$ is the detector gain, which is unity for MAMA observations. For the CCD, this is the conversion from counts to electrons, the value of which is given in the header keyword ATODGAIN.
• $//<![CDATA[ \begin{array}{l}H\end{array} //]]>$ is a correction factor accounting for the finite extraction box height (EXTRSIZE) used to extract the spectra; it is the ratio of throughput for an infinite extraction box height divided by the throughput for the extraction box height used to extract the spectrum, where the throughputs are taken from the PCTAB (*_pct.fits) reference table. Note that in the PCTAB, the throughput vector for the default extraction box size of a given mode is defined to be unity at all wavelengths, while the infinite extraction box throughput curve (labeled as extraction height = 600 in the PCTAB) will have throughput greater than unity at all wavelengths. So when an extraction is done using the default extraction box, the correction applied will be greater than unity, even though the PCTAB row for the default extraction box itself is equal to 1 at all wavelengths.
• _{$//<![CDATA[ \begin{array}{l}C_\lambda\end{array} //]]>$} is the net count rate (counts/sec) at a particular wavelength.
• $//<![CDATA[ \begin{array}{l}A_{HST}\end{array} //]]>$ is the area of the unobstructed HST primary mirror (45238.93416 cm²).
• $//<![CDATA[ \begin{array}{l}R_\lambda\end{array} //]]>$ is the wavelength dependent integrated system throughput, given in the PHOTTAB for individual optical elements.
• $//<![CDATA[ \begin{array}{l}T_\lambda\end{array} //]]>$ is the aperture throughput at a particular wavelength.
• $//<![CDATA[ \begin{array}{l}\lambda\end{array} //]]>$ is the wavelength in Angstroms, which is converted to cm by the factor of 10⁸ in the numerator.
• $//<![CDATA[ \begin{array}{l}\Delta \lambda\end{array} //]]>$ is the dispersion (Å/pixel) at a particular wavelength.
• $//<![CDATA[ \begin{array}{l}f_\mathrm{TDS}\end{array} //]]>$ is the correction for time-dependent sensitivity (given in TDSTAB).
• $//<![CDATA[ \begin{array}{l}f_\mathrm{T}\end{array} //]]>$ is the correction for temperature-dependent sensitivity (given in TDSTAB).
• $//<![CDATA[ \begin{array}{l}f_\mathrm{GAC}\end{array} //]]>$ is the grating/aperture (GACTAB) throughput correction.

The FLUXCORR step includes corrections for time dependent sensitivity (TDS) changes. The coefficients to calculate these corrections are taken from the TDSTAB reference file. The coefficients specify the rate of change of the sensitivity with time (units of %/year), over a grid of time and wavelength values. These slopes are used to construct a piece wise linear throughput correction factor as a function of time at each wavelength. This is interpolated to each wavelength of the observation and used to correct the final flux. TDS corrections are applied to the final flux values for both one- and two-dimensional spectra (calstis6 and calstis7). For imaging modes, the TDS calculation is used to correct the throughput curve before calculating the photometric keywords. In practice, for each detector, the TDS trends measured with the low dispersion modes are assumed to apply to all modes (See STIS ISR 2004-04 and STIS ISR 2017-06 for descriptions of how these trends were measured). The one exception to this is the NUV-MAMA PRISM, which has its own TDS determination (STIS ISR 2005-01).

Temperature-dependent corrections to the sensitivity are also made using two columns in the TDS file. The column REFTEMP contains a single value for each optical element. The column TEMPSENS uses the same wavelength grid as already defined by the TDS corrections so that the temperature correction can be allowed to vary as a function of wavelength. The correction factor to the extracted flux is (1 + TEMPSENS * (T-REFTEMP)), where T is given by the science extension header keywords: OM1CAT for the FUV-MAMA detector, OM2CAT for the NUV-MAMA detector, and OCCDHTAV for side-2 electronics CCD data. No correction is made for Side-1 electronics CCD data, since the detector temperature was stable under Side-1 operations.

The STIS spectroscopic flux calibration was set up under the assumption that the grating and aperture throughputs could be determined independently and then simply multiplied together. This turns out not to be true, especially for G430L and G750L modes, which contain a Lyot stop. The GACTAB reference file contains the needed correction vector (THROUGHPUT) at the nominal position of the aperture as a function of wavelength for given OPT_ELEM/APERTURE/CENWAVE combinations. e.g., a vector for aperture 52X0.1E1 is appropriate for a target centered at the E1 aperture position, high on the CCD detector. The correction vector for a 52X2 observation at the standard central position is assumed to have a value of unity. The correction vector for a given mode is applied when a spectrum is extracted.

Blaze Shift

For echelle data, the flux correction also includes a blaze shift correction. The blaze functions are known to shift with respect to the wavelength scale depending on the time of observation and the location of the spectrum on the detector. This shift is necessary because depending on the location and time of the observation, the blaze function shifts differently compared to the wavelength scale. The shift is calculated as a linear function of location (x and y) on the detector (SHIFTA1 and SHIFTA2) and as a function of time. In particular, it has been found that the coefficients of the “spatial” component of the blaze shift only depend on the grating, while the coefficients of the “temporal” component and zero point depend on the grating, order, and side of operation (Side-1 or Side-2).

The blaze shift corrections have been updated and recalibrated multiple times during STIS's history, including when the monthly offsets of the Mode Select Mechanism were still being routinely performed for echelle data (see Section 7.6.2 of the STIS Instrument Handbook). Because of this, not all of the echelle orders currently falling on the detector for a given grating/cenwave combination have well-calibrated blaze shift corrections. These echelle orders do not have entries in the PHOTTAB and RIPTAB reference files and will not be present in the resulting _x1d files when FLUXCORR is set to PERFORM. STIS ISRs 2007-01 and 2012-01 document which echelle orders are affected.

3.4.14 GEOCORR: Geometric Distortion Correction

• Reference files: IDCTAB

Geometric correction is part of secondary 2-D image reduction and is applicable to all ACCUM and TIME-TAG mode imaging data. The method used is similar to 2-D rectification of spectroscopic data (see Section 3.4.25). For each pixel in the output rectified image, the corresponding point is found in the input distorted image. Bi-linear interpolation in the input image is used to get the data value to assign to the output. The output pixel value is the weighted sum of the values of the four nearest pixels in the input image. The weights depend on distances of that particular pixel from each of the four pixels, with the sum of the weights normalized to unity (see STIS ISR 98-13). Note that such distances are determined from the centers of the pixels. Mapping from an output pixel back into the input images is specified by a two-dimensional power series polynomial. The distortion coefficients and their implementation in the IDCTAB are fully described in ACS ISR 2000-11. The errors are interpolated using the same weights as for the science data, except that the errors are combined in quadrature. The distortion coefficients for the STIS detectors are given in STIS ISRs 2001-02, 2004-02 and 2018-02. The plate scale of the geometrically corrected output image is given in the SCALE column of the IDCTAB.

3.4.15 GLINCORR and LFLGCORR: Nonlinearity Corrections

• Reference file: MLINTAB

These steps are part of basic 2-D image reduction and are performed only for the MAMA detectors. The MAMAs are photon counting detectors. At high photon (pulse) rates, the MAMA response becomes nonlinear due to four effects:

• Pore paralysis in the micro-channel plates arises when charge cannot flow rapidly enough to replenish channels whose electrons have been depleted due to high local photon rates. This depletion produces a local non-linearity. The local count rate is roughly linear up to ~200 counts/sec/pixel and then turns directly over, showing an inverted V shape. Thus, it is not possible to reliably correct for or flag pixels that have exceeded the local linearity limit in the pipeline (because the relation is bi-valued).
• The electronic processing circuitry has a dead time of roughly 350 nano seconds between pulses; thus at global count rates (across the detector) of 300,000 counts (pulses) per second, the electronic circuity counts roughly 90% of the pulses.
• The MAMA Interface Electronics (MIE) and flight software can process at most 300,000 pulses per second (i.e., it is matched to the expected global count rate performance of the electronic circuitry). At count rates higher than this, the MIE will still count only 300,000 pulses per second—this represents a hard cutoff beyond which no information is available to allow correction to the true count rate. In practice, at count rates approaching 270,000 counts/sec the flight software begins losing counts due to the structure of its data buffers.
• For sub-arrays, the hard cutoff limit of the MIE electronics and software will differ from that for full frame processing, but will still be dependent on the total global rate in addition to the rate within the sub-array.

The local and global count rates that lead to nonlinearity are both above the screening limits for MAMA observations, so under normal circumstances, these nonlinearities are unimportant. However, if a brighter than allowed target is inadvertently observed without shuttering the detector, these linearity corrections are important.

The global count rate (across the entire detector) is determined as part of the bright object protection sequence and is passed down with the exposure as a header keyword, GLOBRATE, in the science header. Calstis also computes GLOBRATE and updates the value in the header. If either GLINCORR or LFLGCORR is PERFORM, the global count rate will be checked; a correction for global non-linearity is applied if GLINCORR is PERFORM, using the parameters GLOBAL_LIMIT, LOCAL_LIMIT, TAU, and EXPAND read from the MLINTAB reference table.

If the value of the SCI extension header keyword GLOBRATE is greater than GLOBAL_LIMIT, the keyword GLOBLIM in the SCI extension header will be set to EXCEEDED, with no change made to the data. Otherwise, GLOBLIM will be set to NOT-EXCEEDED, and a correction factor will be computed and multiplied by each pixel in the science image and error array. The correction factor is computed by iteratively solving GLOBRATE = X * exp (-TAU * X) for X, where X is the true count rate. This algorithm has not yet been updated to account for the linearity effects from the flight software data buffer management.

If LFLGCORR is PERFORM, each pixel in the science image is also compared with the product of LOCAL_LIMIT and the exposure time EXPTIME. That count rate limit is then adjusted for binning by dividing by the pixel area in high res pixels. If the science data value is larger than that product, that pixel and others within a radius of EXPAND high res pixels are flagged as nonlinear. Because our understanding of the MAMA processing electronics is currently incomplete, accurate fluxes (global linearity) at count rates exceeding 285,000 counts/sec cannot be expected from the calstis pipeline.

3.4.16 HELCORR: Correction to Heliocentric Reference Frame

• Reference file: none

This step is part of spectral extraction or rectification. The correction of wavelengths to a heliocentric reference frame is controlled by calibration switches HELCORR and DISPCORR — if both switches are set to PERFORM then the correction is made. The functional form of the correction (shown below) requires the calculation of the heliocentric velocity (ν) of the Earth in the line of sight to the target.

where:

• $//<![CDATA[ \begin{array}{l}\lambda_\mathrm{helio}\end{array} //]]>$ is the heliocentric vacuum wavelength.
• $//<![CDATA[ \begin{array}{l}\lambda_\mathrm{obs}\end{array} //]]>$ is the wavelength observed, prior to heliocentric correction.
• $//<![CDATA[ \begin{array}{l}v\end{array} //]]>$ is the component of the velocity of the Earth away from the target.
• $//<![CDATA[ \begin{array}{l}c\end{array} //]]>$ is the speed of light.

The derivatives of low precision formulae for the Sun’s coordinates described in the Astronomical Almanac are used to calculate the velocity vector of the Earth in the equatorial coordinate system of the epoch J2000. The algorithm does not include Earth-Moon motion, Sun-barycenter motion, nor light-time correction from the Earth to the Sun. This value for the Earth’s velocity should be accurate to ~0.025 km/sec during the lifetime of STIS. (Note that the uncertainty of 0.025 km/s is much less than the ~2.6 km/s resolution obtained with the STIS high dispersion echelle gratings.) The value of heliocentric velocity, ν, is written to the HISTORY record in the primary header of the output spectrum file. It is also written to the V_HELIO keyword in the SCI extension header, regardless of the value of the HELCORR keyword.

3.4.17 LORSCORR: Conversion to Native Format MAMA Pixels

• Reference file: none

This step is part of basic 2-D image reduction and is performed for MAMA data only. MAMA data are, by default, taken in high resolution mode (2048 × 2048 pixels), in which the individual micro-channel plate pixels are subsampled by the anode wires. This mode produces an image with improved sampling but with appreciably worse flat fielding properties (see Chapter 11 of the STIS Instrument Handbook for more details). If LORSCORR is set to PERFORM, calstis simply adds the counts in pairs of adjacent pixels to produce images in the native format (or so called reference format) of the MAMA detectors, with 1024 × 1024 pixels.

The binning of the uncalibrated image is determined from the LTM1_1 and LTM2_2 keywords in the SCI extension header of the _raw data file. LTMi_i = 1 implies the reference pixel size, and LTMi_i = 2 means the pixels are subsampled into high res format. In this step, if either or both axes are high res, they will be binned down (summed) to low res.

Most MAMA raw files will be in the high resolution (2048 × 2048 pixel) format, but the default calibration settings will produce calibrated files that use the lower resolution format. Thus MAMA _flt files will normally be 1024 × 1024 pixels. Note also that MAMA auto wavecal images (_wav.fits files) will usually also be in the lower resolution format.

3.4.18 PHOTCORR: Populate Photometry Header Keywords

• Reference files: PHOTTAB, APERTAB, TDSTAB & IMPHTTAB

This step is part of basic 2-D image reduction and is applicable only for OBSTYPE=IMAGING data. For image mode, the total system throughput is calculated from the reference files. Throughputs are corrected for time dependent changes to the time of the observation using information from the TDSTAB. The IMPHTTAB reference file contains computed inverse sensitivity, reference magnitude, pivot wavelength, and RMS bandwidth; these four quantities are written to the primary header keywords PHOTFLAM, PHOTZPT, PHOTPLAM, and PHOTBW, respectively.

3.4.19 RPTCORR: Sum Repeated MAMA Observations

• Reference file: none

This step is part of secondary 2-D image reduction and is applicable only for MAMA data. If the number of repeat exposures is greater than one, then calstis will sum the flat-fielded data in the case of image mode data (producing an _sfl file) or the two-dimensionally rectified data (producing an _sx2 file) in the case of long slit data. RPTCORR just applies a straight pixel-to-pixel addition of the science values, bitwise ORs the data quality files, and determines the error as the square root of the sum of the squares of the errors in the individual exposures.

3.4.20 SC2DCORR: Echelle Scattered Light Correction

• Reference files: CDSTAB, ECHSCTAB, EXSTAB, RIPTAB, 
HALOTAB, TELTAB, SRWTAB

This step is part of spectral extraction. It can only be used with STIS echelle data. If SC2DCORR is set to PERFORM, calstis iteratively constructs a two-dimensional model of the scattered light present in the _flt image. After 3 iterations, this scattered light model is (virtually) subtracted from the _flt data and spectral extraction proceeds using this background-subtracted version of the _flt image as input to the normal x1d extraction with algorithm = unweighted, described in Section 3.4.24; however, as the background has now been subtracted by the SC2DCORR algorithm, the background subtraction normally done as part of the unweighted extraction is omitted.

This scattered light correction procedure has been used since 2000-Dec-21 to process all HST archive requests for STIS echelle data, regardless of when the observations were performed, unless use of an unsupported mode prevents spectral extraction. Two-dimensional scattered light subtraction may be suppressed either by setting SC2DCORR to OMIT in the _raw file and reprocessing the entire association with calstis, or more directly by running the x1d task with the _flt file as input and the extraction algorithm parameter of the x1d task set to unweighted instead of sc2d.

Note that since the x1d task is used for both first order and echelle data, the default value of the algorithm parameter in the x1d task is set to unweighted. Users recalibrating echelle data by running the x1d task directly on the _flt image will normally want to be sure that the x1d algorithm parameter is set to sc2d. Alternatively, the user may run the calstis task using the _flt file as input, as calstis will use the value of the SC2DCORR keyword in the _flt file header to determine which extraction algorithm to use.

3.4.21 SGEOCORR: Small Scale Distortion Correction

• Reference file: SDSTFILE

This step would be part of spectral extraction or rectification and apply only to MAMA data, but it is not presently implemented. If SGEOCORR were PERFORM, a correction would be applied for the small scale geometric distortions in the MAMA detectors. The corresponding reference file, SDSTFILE, would contain the distortion offsets for each pixel in the MAMA image.

3.4.22 SHADCORR: CCD Shading Correction

• Reference file: SHADFILE

This step is part of basic 2-D image reduction and applies only to CCD data, but it is not currently performed. It is designed to correct for shading by the CCD shutter in very short integration time exposures. The STIS CCD shutter is specified to produce exposure non-uniformity less than or equal to 5 milliseconds for any integration time: the shortest possible STIS CCD exposure time is 100 milliseconds. Ground testing has shown that this step is not currently required. However, if SHADCORR were needed, a SHADFILE reference would need to be created to use this module.

3.4.23 WAVECORR: Wavecal Correction

• Reference files: LAMPTAB, APDESTAB, WCPTAB, DISPTAB, INANGTAB, SPTRCTAB, SDCTAB

This step is a part of wavecal processing and applies only to spectroscopic data. The purpose of wavecal processing is to determine the shift of the image on the detector along each axis owing to uncertainties in positioning by the Mode Select Mechanism (MSM) and to thermal motions. It requires one or more contemporaneous wavecal (line lamp) observations, taken without moving the MSM from the setting used for the science data.

Basic two-dimensional image reduction is first applied to the wavecal. For CCD data taken with the HITM system prior to 1998-Nov-9, the external shutter was left open during wavecal exposures, so the detector was exposed to radiation from both the science target and the line lamp. In this case, the next step is to subtract the flat-fielded science image from the wavecal, after scaling by the ratio of exposure times and by the ratio of gains.

For first order data, two-dimensional rectification is then applied to the flat-fielded (and possibly science subtracted) wavecal. The result is a temporary file that will normally be deleted after processing. For prism or echelle data, the 2-D rectification step is not done.

Because wavecal data are not CR-SPLIT, cosmic rays must be identified and eliminated by looking for outliers within columns, i.e., in the cross-dispersion direction. Because the data have been rectified, values within a single column are all at the same wavelength and hence, are fairly consistent in their brightness for a line lamp exposure. Cosmic rays will stand out above this brightness level. The image can then be collapsed along columns to get a long slit integrated spectrum or along rows to get an outline of the slit (in the cross-dispersion direction).

In removing cosmic rays from a wavecal, a different cosmic ray rejection function has been added to calstis4. This function is called if the SCI extension SDQFLAGS (serious data quality flags) includes 8192. The logic here is that if SDQFLAGS does not include 8192 (DATAREJECT), the bit used to flag cosmic rays, then the cosmic rays are not considered “serious”. Therefore, when a pixel is identified by calstis4 as being affected by a cosmic ray hit, it is flagged by including 8192 in the DQ array for that pixel. This procedure is explained in detail in STIS ISR 98-12.

The shifts in the dispersion and cross-dispersion directions are determined differently for first order grating, prism, and echelle data. First-order grating data are 2-D rectified before being passed to calstis4. This is done so the image can be collapsed along columns or rows to make 1-D arrays that are then cross correlated with a template spectrum or a template of the slit illumination to get the shift in the dispersion or cross-dispersion direction, respectively. For a long slit, the features that are used to locate the image in the cross-dispersion direction are the occulting bars, but the cross correlation is not done directly between the slit illumination and a template. The slit illumination pattern is first normalized and inverted, so it is nominally zero where there is light, and it is unity within the occulting bars; this is then cross correlated with a template of the slit that is normalized the same way.

Prism data are handled by calstis4 in nearly the same way as first order grating data. The differences are that the data are not rectified first: when collapsing along columns to make a 1-D spectrum, only the middle 224 pixels are used to reduce the effect of any tilt in the spectral lines, and when collapsing along rows the spectral trace (SPTRCTAB) is applied to account for spatial distortion. The reason for working with the flat-fielded but not rectified data is that the dispersion for the prism is highly nonlinear, and the shift is in pixel space, not wavelength space.

For echelle data, calstis4 computes a 2-D cross correlation between the flat-fielded wavecal image and a template image. The offset of the peak in the cross correlation gives the shift in both axes. This works because the aperture is small in both dispersion and cross-dispersion directions.

The shifts are written to the extension header of the 2-D rectified wavecal in the keywords SHIFTA1 (the shift in pixels along AXIS1, or dispersion direction) and SHIFTA2 (the shift in pixels along AXIS2, or spatial direction) although this image is not saved unless wavecal is run with save_w2d=yes. The SHIFTA1 and SHIFTA2 keyword values are also copied from the 2-D rectified wavecal file to the flat-fielded (_flt or _crj) science extension header. SHIFTA1 and SHIFTA2 are always given in units of unbinned CCD pixels or lo-res MAMA pixels, regardless of the binning of the CCD exposures. This is the final step performed on the science data prior to 2-D rectification or 1-D extraction of the science data in the pipeline.

Either or both the wavecal file and science file can contain multiple exposures, and the image can drift across the detector over time due to such things as thermal effects, so it is necessary to select the most appropriate wavecal exposure for each science exposure. If there are multiple wavecal exposures, the shifts are linearly interpolated at the time of a given science exposure to get the shifts that will be used for that science exposure. There is also an option to use the wavecal that is nearest in time to the given science exposure.

If it is necessary to use a wavecal exposure that differs from the default exposure in the header, this can be done either by substituting the new file name in the WAVECAL keyword value in the science exposure’s primary data header before processing the file with calstis, or by using the stistools.wavecal task to update the SHIFTA1 and SHIFTA2 keywords in the image extension headers.

3.4.24 X1DCORR: Locate and Extract 1-D Spectrum

• Reference files: SPTRCTAB, XTRACTAB, SDCTAB

This step is part of spectral extraction. If X1DCORR is PERFORM, calstis will locate and extract a one-dimensional spectrum, as explained below, and in more detail in STIS ISR 99-03.

Locate the Spectrum

The shapes of spectral traces are contained in the spectrum trace table, SPTRCTAB. For each mode (OPT_ELEM, CENWAVE) of the first order gratings, this table contains many traces at arbitrary Y positions spanning the detector. For each echelle mode, it contains one trace at a default position for every spectral order (SPORDER). The Y position (A2CENTER) of a trace on the detector at the central column (A1CENTER) is given in CCD or MAMA lo-res pixels. (A1CENTER is 513; A2CENTER is non-integer.) The shape of each trace is stored as an array (A2DISPL) consisting of offsets in pixels in the AXIS2 direction relative to A2CENTER. The spectral traces of some of the first order modes have been observed to rotate slowly as a function of observation date. For the most commonly used modes, the column DEGPERYR gives this rotation rate in degrees per year, and the column MJD gives the date for which the unrotated trace is valid. This information is used to correct the spectral traces to the observing date. (See Section 3.5.7.)

For the echelle modes, an initial estimate of the location of each spectral order in the science image is obtained as the sum of the A2CENTER value in the SPTRCTAB for that order and the value of SHIFTA2 in the science data header. SHIFTA2 is the Y-offset from the nominal placement of the image on the detector due to differences in the setting of the MSM, measured as described in Section 3.4.23. For the first order modes, the entire height of the detector will be searched for the brightest spectrum, so an initial estimate of the position of the spectrum on the detector is not needed. (To extract fainter spectra at other locations, see Section 5.5.2.)

The location of the spectral order or first order spectrum in the science image is determined by performing a cross-correlation between a spectral trace and the science image. For the echelle modes, the single trace for each spectral order is used in the vicinity of the initial estimate of the location of that order. The search is restricted to a few pixels along the cross-dispersion direction (±n pixels, where n is read from the MAXSRCH column in the XTRACTAB table), in order to avoid confusion due to the simultaneous presence of many orders on the detector. For the first order modes, the shape of the lowest trace on the detector for that mode in the SPTRCTAB is used for a search of the entire detector.

The search for the spectral order or first order spectrum is conducted at integer pixel steps, starting at A2CENTER+SHIFTA2 for the given spectral order or for the lowest first order trace. A sum of the counts along the trace is formed by adding the value of one pixel’s worth of data from each column. The "pixel" in each column generally includes a fractional contribution from two pixels, which are weighted by the fractional area. Quadratic refinement using the Y position with the highest sum and its two nearest neighbors is then used to locate the spectrum to a fraction of a pixel. For the first order modes, the shape of the trace at the initially measured position replaces the shape of the lowest trace on the detector for the quadratic refinement.

For first order spectra, the final position of the spectrum is A2CENTER+SHIFTA2+CRSCROFF, where A2CENTER is that of the lowest trace on the detector for that mode and CRSCROFF is the offset found during the cross correlation. If the cross correlation fails, the value of CRSCROFF is set to zero, a warning message is written to the output, and the nominal position A2CENTER+SHIFTA2 is used as the location of the spectrum. For echelle data, the final position of the spectral order is A2CENTER+SHIFTA2+CRSCROFF, where A2CENTER is the value given for that order in the SPTRCTAB. If the cross correlation fails for an order, then the average value of CRSCROFF found for the other orders is used instead and that value is written in the final output header.

In rare cases, the x1d task will give unexpected results such that the final extracted spectrum represent the noisy background. This is due to the cross-correlation algorithm incorrectly locating the local maximum at hot pixels or cosmic rays not properly rejected by the CRCORR step. Detailed discussion and workaround for this issue are provided in Chapter 5.5.2

Extract the 1-D Spectrum

Once the spectrum location has been identified, the spectrum is extracted. For the first order modes, the extraction of the spectrum is performed by using a trace interpolated from the two traces in the SPTRCTAB with the A2CENTER values bracketing the final spectral position A2CENTER+SHIFTA2+CRSCROFF. (For some modes, the traces are rotated, as described above.) For echelle data, the final trace is simply the only trace available in the SPTRCTAB for that spectral order, shifted to the final position A2CENTER+SHIFTA2+CRSCROFF.

The extraction of the spectrum is defined by a triplet of extraction boxes found in the reference table, XTRACTAB; one extraction box is used for the spectrum, and the other two are used for the background. The background regions may be tilted with respect to the image axes, but the spectral region is not tilted, to avoid interpolation. For each pixel in the dispersion direction, calstis sums the values in the spectrum extraction box. The extraction box is one pixel wide and has a height determined from the EXTRSIZE column in XTRACTAB, centered on the spectrum. The extraction height can be overridden by the extrsize parameter in x1d. Each end point of the extraction box may include a fractional part of a pixel. In the case of a fractional pixel, calstis will scale the counts in the given pixel by the fraction of the pixel extracted. Thus, each pixel in the output spectrum consists of the sum of some number (or fraction) of pixels in the input image.

Calstis has been designed to allow for unweighted or optimal extraction of the spectrum, although the latter option has not been implemented. The extraction algorithm is determined by the value of the parameter XTRACALG in the XTRACTAB reference file, currently always set to unweighted. (This is not to be confused with setting the parameter algorithm to unweighted in x1d. This parameter in x1d is relevant to scattered light correction for echelle data. See Section 3.4.20.) This parameter is written to the header of the output spectrum data file. At the end of the 1-D extraction step, a spectrum of gross counts/sec is produced.

3.4.25 X2DCORR: Produce Rectified 2-D Spectral Image

• Reference files: DISPTAB, INANGTAB, APDESTAB, SPTRCTAB

This step is part of two-dimensional rectification. If X2DCORR is PERFORM, a two-dimensional rectified spectral image will be produced for spectroscopic data. The two-dimensional rectified output image (_x2d or _sx2) will have a linear wavelength scale and uniform sampling in the spatial direction. The dispersion direction is the first image axis (AXIS1). The size of the rectified image is made somewhat larger (the increase can be substantial for sub-arrays) than the input in order to allow for variations in heliocentric correction and offsets of the spectrum on the detector. The binning of the output image will be approximately the same as the input. For each pixel in the output rectified image, the corresponding point is found in the input distorted image, and bi-linear interpolation is used on the four nearest pixels to determine the value to assign to the output.

Mapping from an output pixel back into the input image makes use of the dispersion relation and one-dimensional trace table. The dispersion relation gives the pixel number as a function of wavelength and spectral order. The one-dimensional trace is the displacement in the cross-dispersion direction at each pixel in the dispersion direction. Both of these can vary along the slit, so the dispersion coefficients and the one-dimensional trace are linearly interpolated for each image line. Corrections are applied to account for image offset, binning, and sub-array. The spectrum can be displaced from its nominal location on the detector for several reasons, including Mode Select Mechanism (MSM) uncertainty, deliberate offsets for distribution of charge extraction for MAMA data, and the aperture location relative to a reference aperture. These offsets are corrected by modifying the coefficients of the dispersion relations and by adjusting the location of the one-dimensional trace. See also DISPCORR and FLUXCORR for algorithmic details. The process of dispersion solution, spatial rectification, and wavelength calibration is similar for one-dimensional extractions and two-dimensional spectral images. However, the flux calibration and error estimates are somewhat different for the two cases (see STIS ISR 98-13).

¹The rationale for maintaining three types of flat field reference files rather than a single integrated reference file is described in detail in STIS ISR 95-07.