HST Data Handbook for COS

3.7 Reference Files

---

This section contains a description of the COS reference files. See Figure 3.1 - Figure 3.5 for which modules use these files and Section 3.4 for explanations of how their contents are applied by those modules.

3.7.1 BRSTTAB: Burst Parameters Table

• File Suffix: _burst

The BRSTTAB file provides the parameters needed to identify bursts. It consists of a primary header extension and a binary table extension with the columns listed in Table 3.5. Details of the burst rejection routine are given in Section 3.4.2.

Table 3.5: BRSTTAB table contents

Column Name	Data Type	Description
SEGMENT	String	Segment name, FUVA or FUVB
MEDIAN_N	Double	Factor above the median count rate for a time interval to be identified as a burst
DELTA_T	Double	Normal sampling time for large burst detection (s)
DELTA_T_HIGH	Double	High count rate sampling time for large burst detection (s)
MEDIAN_DT	Double	Time interval used to search for localized bursts (s)
BURST_MIN	Double	Minimum threshold rate for small bursts (counts/s)
STDREJ	Double	Number of standard deviations above background noise for small bursts
SOURCE_FRAC	Double	Minimum factor small bursts must be above source counts.
MAX_ITER	Long	The maximum number of iterations used to re-evaluate the median to detect a localized burst
HIGH_RATE	Double	Total count rate threshold to use DELTA_T_HIGH instead of DELTA_T (counts/s)

3.7.2 BADTTAB: Bad Time Interval Table

• File Suffix: _badt

The BADTTAB reference file lists the start and end times of known bad time intervals. It is used by the BADTCORR calibration module to flag events in TIME-TAG events lists which occur during a bad time interval. In later processing the flagged events will be removed from the final calibrated data, and the exposure time header keyword, EXPTIME, updated. The bad time interval table consists of segment, start, and end columns (see, Table 3.6). The segments columns can be populated with either FUVA, FUVB or ANY. The start and end columns are in Modified Julian Date.

Table 3.6: BADTTAB table content

Column Name	Data Type	Description
SEGMENT	String	Detector segment, FUVA, FUVB or ANY
START	Double	Bad time interval start time in MJD
END	Double	Bad time interval end time in MJD

3.7.3 PHATAB: Pulse Height Discrimination Table

• File Suffix: _pha

The PHATAB reference file is only valid for FUV data, and is applied during the PHACORR step of calcos to filter non-photon events. The file consists of two extensions, the first being the primary header, and the second a binary table (see Table 3.7). The table lists the lower and upper thresholds for valid individual pulse heights in TIME-TAG mode. In Time-Tag mode, each detector event has an associated pulse-height of 5 bits with values ranging from 0 to 31, The table also gives the minimum and maximum values for the location of the mean value of the pulse height distribution used in ACCUM mode. In ACCUM mode, a pulse height distribution histogram is generated for the whole exposure and downloaded as part of the science data file. The histogram includes all the digitized events for each segment independently of the currently defined subarrays. Note in ACCUM mode the pulse height is a 7 bit number with values ranging from 0 to 127.

Table 3.7: PHATAB table contents

Column Name	Data Type	Description
SEGMENT	String	Segment name, FUVA or FUVB
LLT	Long	Lower limit threshold (TIME-TAG)
ULT	Long	Upper limit threshold (TIME-TAG)
MIN_PEAK	Float	Lower limit for location of mean (ACCUM)
MAX_PEAK	Float	Upper limit for location of mean (ACCUM)

3.7.4 BRFTAB: Baseline Reference Frame Table

• File Suffix: _brf

The BRFTAB reference file is only applicable to FUV data and is used during pipeline processing in the TEMPCORR module to apply the thermal distortion correction. The FUV detector does not have physical pixels like a CCD. Instead, the x and y positions of detected photon events are obtained from analog electronics, which are susceptible to thermal changes. Electronic stim pulses are normally commanded during integration and are used as physical position reference points. To return the FUV data to a known physical space, the BRFTAB defines the stim positions.

The BRFTAB file consists of a primary header extension and a binary table extension. The table lists the stim locations, stim search regions, and the active detector areas (Table 3.8).

Table 3.8: BRFTAB table contents

Column Name	Data Type	Description
SEGMENT	String	Segment name, FUVA or FUVB
SX1	Double	X pixel coordinate (zero indexed) of stim11
SY2	Double	Y pixel coordinate (zero indexed) of stim1
SX2	Double	X pixel coordinate (zero indexed) of stim22
SY2	Double	Y pixel coordinate (zero indexed) of stim2
XWidth	Long	Half width of search region for stims
YWidth	Long	Half height of search region for stims
A_Left	Long	X pixel of left side of active region
A_Right	Long	X pixel of right side of active region
A_Low	Long	Y pixel of lower side of active region
A_High	Long	Y pixel of upper side of active region

1Stim 1 is located in the upper left corner 2Stim 2 is located in the lower right corner

3.7.5 GEOFILE: Geometric Correction File

• File Suffix: _geo

This file is only used for FUV data. The GEOFILE is used by the GEOCORR calibration module to perform the geometric correction. From the nature and construction of the XDL detectors, the physical size of the pixels vary across the detector. The geometric distortion maps are used to correct for this variation and to transform the data into a constant physical pixel size early in the data reduction calibration process. After the thermal correction has been applied and the detector digital span and position are adjusted to their reference values, as defined in the reference table, the geometric correction can be applied. This implies that all the files used to determine the geometric correction were initially thermally-corrected.

Each geometric correction reference file contains four IMAGE extensions. There are two for each segment, and for each segment, there is one for each axis. At a given (X,Y) location in the uncorrected COS data, the value at that location (corrected for binning and offset) in the geometric correction image gives the distortion to be subtracted from the X or Y coordinates.

3.7.6 DEADTAB: Deadtime Table

• File Suffix: _dead

The deadtAB reference file is used in the DEADCORR module, to obtain the true number of events received compared to the number of events counted by the detector electronics.

There is one DEADTAB reference file for the NUV and FUV detectors. They consist of a primary header extension and a binary table extension which contains the livetime values for a given observed count rate and segment. The livetime is defined as:

 livetime = observed rate / true rate

and can be used to calculate the true count rate.

3.7.7 FLATFILE: Flat Field File

• File Suffix: _flat

FLATFILE provides a flat field image which is used by the pipeline to remove the pixel-to-pixel variations in the detector. The FUV FLATFILE consists of a primary header and two 14000 x 400 IMAGE extensions, one for each segment. The NUV FLATFILE consists of a primary header and a 1024 x 1024 IMAGE extension.

Currently, there is no usable FUV flat field reference file from pre-flight testing, and a dummy file of all ones is being used. A plan is in place to obtain FUV flat-field data in orbit from standard stars for every grating and possibly every central wavelength of the FUV detector. Until these data are available, the FUV flat field processing will use a file consisting of ones, which leaves the data unchanged.

The NUV flat field is a combination of internal and external deuterium flat field lamp exposures from thermal-vacuum testing which illuminate the portion of the detector that will receive all of the incoming external light on orbit. The data cover the following pixel region of the detector: x (dispersion): 0 to 1023, and y (cross-dispersion): 495 to 964. The rest of the detector, where flat field data are not available, has a value of 1.0. The bottom four and top three rows of the detector do not fit well with the rest of the detector and they are flagged in the data quality table.

3.7.8 BPIXTAB: Bad Pixel Table

• File Suffix: _bpix

The data quality initialization table identifies rectangular regions on the detectors that are known to be less then optimal. The feature type describes the type of detector blemish enclosed within the bounding box and q is the quality value assigned to all events detected within the box. The regions were identified by visual inspection of the combined flat field data for each detector (and segment). The BPIXTAB files consist of a primary header and a binary table extension which consists of the columns listed in Table 3.9.

Table 3.9: BPIXTAB table content

Column Name	Data Type	Description
SEGMENT	String	Segment name, FUVA, FUVB, or ANY for NUV
LX	Long	X coordinate of lower left corner of region
LY	Long	Y coordinate of lower left corner of region
DX	Long	Width of region in X
DY	Long	Width of region in Y
DQ	Long	Data quality value to assign to current region
TYPE	String	Comment regarding current region

In the BPIXTAB table, the DQ field may have several different values, each associated with a unique issue as shown in Table 3.10.

Table 3.10: Data Quality Flag Values

Flag	Name	Description
0	DQ OK	No anomalous condition noted
1	DQ Softerr	Reed-Soloman error
2	DQ_Brush Mark	Brush mark
4	DQ Grid Shadow	Grid shadow mark
8	DQ Near Edge	Spectrum near an edge of the detector
16	DQ Dead	Dead spot
32	DQ Hot	Hot spot
64	DQ Burst	Count rate implies a burst (FUV only)
128	DQ Out of Bounds	Pixel is outside the subarray
256	DQ Data Fill	Data fill due to the telemetry drop-out
512	DQ PH Low	Pulse height is below cutoff
1024	DQ PH High	Pulse height is above cutoff
2048	DQ Bad Time	Time is inside a bad time interval
4096	DQ Bad Wavelength	Wavelength is out of bounds
8192	DQ Divots	Wrinkled appearance from detector flat field
16384	DQ Sdistortion	Vertical S distortion seen on FUVA

3.7.9 LAMPTAB: Template Calibration Lamp Spectra Table

• File Suffix: _lamp

The LAMPTAB files consist of a primary header extension and a binary table extension which contains an extracted 1-D spectrum from the internal PtNe calibration lamp through the WCA aperture, for each grating and central wavelength setting. It is used in the calcos pipeline to determine the pixel offset of the observed data. The structure of the template calibration lamp spectra table is shown in Table 3.11.

Table 3.11: LAMPTAB table contents

Column Name	Data Type	Description
SEGMENT	String	Segment name: FUVA, FUVB, NUVA, NUVB, NUVC
OPT_ELEM	String	Grating name
CENWAVE	Long	Central wavelength (Angstrom)
WAVELENGTH	Double	Array of wavelength (Angstrom)
INTENSITY	Float	Spectrum array

3.7.10 WCPTAB: Wavecal Parameter Table

• File Suffix: _wcp

The WCPTAB file contains information relevant for the wavecal pipeline processing. It consists of primary header extension and a binary table extension which is described in Table 3.12. A fixed RESWIDTH value of 6.0 pixels (per resolution element) is used for the FUV detector and a fixed RESWIDTH value of 3.0 pixels (per resolution element) is used for the NUV detector. The FUV STEPSIZE is measured by calculating the displacement in pixels from a PtNe spectrum obtained at a position of FPOFFSET=0 to the position FPOFFSET=-2 for segment A from the WCA (and dividing by 2). The NUV STEPSIZE is measured by calculating the displacement in pixels from a PtNe spectrum obtained at a position of FPOFFSET=0 to the position FPOFFSET=-2 for stripe B of the WCA (and dividing by 2). The XC_RANGE was estimated as 110% of the STEPSIZE for both FUV and NUV.

Table 3.12: WCPTAB table contents

Column Name	Data Type	Description
OPT_ELEM	String	Grating name
XC_RANGE	Long	Maximum Lag (amplitude) for cross correlation
RESWIDTH	Double	Number of pixels per resolution element in the dispersion direction
MAX_TIME_DIFF	Double	Defines `close in time' for wavecals
STEPSIZE	Long	One step of OSM is this many pixels

3.7.11 DISPTAB: Dispersion Coefficient Table

• File Suffix: _disp

There are two DISPTAB files with similar formats, one for the NUV, and one for the FUV. They consist of a main header and a binary table in the second HDU. These tables provide the dispersion relations for each segment, aperture, optical element and central wavelength. Each file has the format given in Table 3.13.

Table 3.13: DISPTAB table format

Column Name	Data Type	Description
SEGMNT	String	Segment name, FUVA, FUVB, NUVA, NUVB, NUVC
OPT_ELEM	String	Grating name
APERTURE	String	Aperture name
CENWAVE	Long	Central wavelength of setting
NELEM	Long	Number of non-zero coefficients in the polynomial
COEFF	Double	Coefficients.
DELTA	Float	Offset for the science data

For P_x = the Doppler corrected pixel value in the dispersion direction, the associated wavelength for a specific segment, optical element, aperture, and central wavelength is given by

 lambda(Px) = COEFF[0] + COEFF[1]*Px + COEFF[2]*Px2 + 
COEFF[3]*Px3 + DELTA

3.7.12 XTRACTAB: 1-D Spectral Extraction Table

• File Suffix: _1dx

There are two XTRACTAB files with similar formats, one for the NUV and one for the FUV. They consist of a main header and a binary table in the second HDU. These tables provide the information needed to extract the spectrum from a geometrically corrected image of the detector for each optical element and central wavelength. Each file has the format given in Table 3.14.

Table 3.14: XTRACTAB table format

Column Name	Data Type	Description
SEGMENT	String	Segment name, FUVA, FUVB, NUVA, NUVB, NUVC
OPT_ELEM	String	Grating name
CENWAVE	Long	Central wavelength setting
APERTURE	String	Aperture name
SLOPE	Double	Slope of the spectrum
B_SPEC	Double	Intercept of the spectrum
B_BKG1	Double	Intercept of the background below the spectrum
B_BKG2	Double	Intercept of the background above the spectrum
HEIGHT	Long	Height of the extraction window for the spectrum
BHEIGHT	Long	Height of the extraction window for the background
BWIDTH	Long	Width of the boxcar filter used to smooth the backgrounds

The spectral extraction of a source is performed by collapsing the data within a parallelogram of height HEIGHT that is centered on a line whose slope and intercept are given by SLOPE and B_SPEC. Similarly, two background spectra are determined by collapsing the data within a parallelogram of height BHEIGHT centered on the lines defined by SLOPE and B_BKG1 and SLOPE and BKG2. The background spectra are then smoothed by a boxcar of width BWIDTH. These are then scaled and subtracted from the source spectrum.

3.7.13 PHOTTAB: Photometric Throughput Table

• File Suffix: _phot

There are two PHOTTAB files with similar formats, one for the NUV, and one for the FUV. They consist of a main header and a binary table in the second HDU. These tables provide the information needed to convert from corrected detector counts to flux units of erg s^-1cm^-2A^-1 for each segment, optical element, aperture and central wavelength. Each file has the format given in Table 3.15.

Table 3.15: PHOTTAB Table Format

Column Name	Data Type	Description
SEGMENT	String	Segment Name
OPT_ELEM	String	Name of optical element
CENWAVE	Long	Central wavelength of the setting
APERTURE	String	Name of the aperture
WAVELENGTH	Double	Wavelength array in Angstroms
SENSITIVITY	Float	Sensitivity array

The units of the Sensitivity array are (count s^-1 pixel^-1)/(erg s^-1 cm^-2 Angstrom^-1). For each segment, optical element, central wavelength setting, and aperture, these files contain arrays of wavelengths and sensitivities which can be interpolated onto the observed wavelength grid. The net counts can then be divided by the sensitivity curves to produce flux calibrated spectra.

3.7.14 TDSTAB: Time Dependent Sensitivity Table

• File Suffix: _tds

There are two such files, one for the FUV and one for the NUV. They are only used for spectroscopic data. The files contain the information necessary to determine the relative sensitivity curve at any given time by interpolating between relative sensitivity curves given at fiducial times which bracket the observation, or else extrapolate the results from the last curve if the observation date is more recent than the last fiducial date. Interpolation data are provided for each segment, optical element, and aperture (see Table 3.16).

Table 3.16: TDSTAB Table Format

Column Name	Data Type	Description
SEGMENT	String	Segment Name
OPT_ELEM	String	Name of optical element
APERTURE	String	Name of the aperture
NWL	Long	Number of wavelength points
NT	Long	Number of time points
WAVELENGTH	Double[NWL]	Wavelength array in Angstroms
TIME	Double[NT]	Fiducial times in MJD
SLOPE	Double[NWL, NT]	Percent per year
INTERCEPT	Double[NLW, NT]	Ratios of current curve to original curves

For an observation obtained at time T, which lies between TIME[j] and

TIME[j+1], the sensitivity curve used to calibrate the spectrum will

be corrected by the following factor:

 (T - REF_TIME) SLOPE[i,j]/(365.25*100) + INTERCEPT[i,j].

where REF_TIME is a general reference time given in the header of the FITS extension.