Section 12. Cosmic Origins Spectrograph

Datasets and associations generated by the Cosmic Origins Spectrograph (COS) are calibrated by CALCOS. The calibration procedure is specified in the document COS-01-0003 (AV-03). Section 12.2 describes calibration reference images, and section 12.3 describes calibration reference tables.

12.1 File Formats and Conventions

The COS calibration reference files are all written as FITS files, with the data in either image or table extensions, depending on the particular reference file. The primary header/data unit consists of just a header, and this header contains keywords such as DETECTOR that are used to select the reference file. The flat field and geometric correction reference files contain images in one or more extensions of type IMAGE. All other reference files are tables, each file containing one table in a BINTABLE extension. The file name is constructed from the standard CDBS unique name, an underscore, a suffix that indicates the type of reference file, and the extension .fits.

In a change from the convention for previous instruments, when pixel numbers are given in a COS reference file, the numbers are zero indexed. CALCOS is written in Python, and reference files will likely be created using software that uses zero indexing. Converting to one indexing could be a source of error, and it would likely cause more confusion than if the original zero-indexed values were retained.

12.1.1 Selection Criteria

For a given calibration step, the appropriate reference files are selected based on the values of header keywords in the file to be calibrated. For a reference table, in addition to selecting the file, the row or rows to be used are also selected based on header keywords, but each keyword name matches a column name in the reference table.

Wildcard values have been adopted for reference table columns, to avoid the need for a large number of redundant rows. The wildcard value for a column containing character-string values is “ANY”, and for a column containing integer values it is -1.

12.1.2 Version Comparison

During the lifetime of COS, it is likely that the formats of some of the reference files will change. Some changes might be backward compatible with CALCOS, but others might not be. In an attempt to reduce the chance of a problem due to using a new reference file with an older version of CALCOS, or an old reference file with a version of CALCOS that expects a newer one, there are three version strings that CALCOS will compare for consistency. Each reference file has a VCALCOS keyword in its primary header. CALCOS itself has a version string, which is written to the headers of calibrated files with the keyword CAL_VER; this must be at least as large as the reference file version. For each reference file, CALCOS also specifies a minimum version for that file; CALCOS requires the reference file to be at least this version. In summary, the version strings don’t all have to be the same; the reference file version must be bracketed between the minimum version and the version of CALCOS.

It must be emphasized that the VCALCOS of a reference file should not change just because its contents change; this keyword should change only when the format changes in a way that requires a corresponding change to CALCOS. The format of a reference file should not change very often, although the contents may be updated frequently. The version of CALCOS, on the other hand, will change whenever any code has been changed. So it will usually be perfectly OK to use a later version of CALCOS with an earlier version of a reference file. If the format of a reference file is changed, its VCALCOS should be set to the first version of CALCOS that handles that new format, and the minimum version in CALCOS for the particular reference file in question should also be set to that version unless earlier versions of the file are backward compatible.

12.2 Calibration Reference Images

12.2.1 Flat Field Correction Image <unique name>_flat.fits

Description: The flat field image is a pixel-to-pixel flat; the large scale fluctuations in sensitivity will be accounted for in the photometric correction table. These images contain the wavelength-independent high spatial frequency information about the uniformity of the detector response. For ACCUM data, the correction is applied by dividing the science image by the flat field image. For TIME-TAG data, the correction is applied for each event as follows. The zero-indexed pixel coordinates from the XCORR and YCORR columns (which are corrected for thermal and geometric distortion, if FUV), rounded to the nearest integer, are used as an index into the flat field reference image. The reciprocal of the value at that pixel is assigned to the EPSILON column of the corrected TIME-TAG table. (This column may also be modified by the deadtime correction).

Format: For NUV, each flat field reference file contains one image as an IMAGE extension. For FUV, each flat field reference file contains two IMAGE extensions, one for each segment; the EXTNAME values are FUVA and FUVB, corresponding to the segment names. EXTVER should be 1.

The images must be unbinned, but they do not need to be full-frame. If they are smaller than full-frame, the extension headers must have keywords giving the offset of the first pixel from the beginning of a full frame. The keywords are ORIGIN_X and ORIGIN_Y; the values are integers, with zero indicating no offset (so a full-frame image would have ORIGIN_X = 0 and ORIGIN_Y = 0). ORIGIN_X is for the more rapidly varying axis, and ORIGIN_Y is for the less rapidly varying axis.

Slectrion Criteria: Files are selected on DETECTOR and OBSTYPE.

Restrictions: None.

Required Additional Primary Header Keywords:

FILETYPE = 'FLAT FIELD REFERENCE IMAGE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Required Additional Extension Header Keyword:

SNR_FF = the signal-to-noise ratio (e.g. 50.) characteristic of
      the flat field image

The following keyword lists describe example primary and extension headers for the flat field correction images.

SIMPLE  =                    T / Fits standard
BITPIX  =                   16 / Bits per pixel
NAXIS   =                    0 / Number of axes
EXTEND  =                    T / There may be standard extensions
ORIGIN  = '        '           / FITS file originator
DATE    = '        '           / Date FITS file was generated
COMMENT   FITS (Flexible Image Transport System) format defined in Astronomy and
COMMENT   Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365.
COMMENT   Contact the NASA Science Office of Standards and Technology for the
COMMENT   FITS Definition document #100 and other FITS information.
FILENAME= '        '
FILETYPE= 'FLAT FIELD REFERENCE IMAGE'
INSTRUME= 'COS     '
DETECTOR= 'FUV     '
OBSTYPE = 'SPECTROSCOPIC'      / type of observation: IMAGING or SPECTROSCOPIC
USEAFTER= 'Jan 01 2004 00:00:00' / use after this date
DESCRIP = '        '
PEDIGREE= 'GROUND  '
VCALCOS = '2.0     '           / string to compare with CALCOS version
NEXTEND =                    2 / number of extensions in file
END

XTENSION= 'IMAGE   '           / Image extension
BITPIX  =                  -32 / Bits per pixel
NAXIS   =                    2 / Number of axes
NAXIS1  =                      / Axis length
NAXIS2  =                      / Axis length
PCOUNT  =                    0 / No 'random' parameters
GCOUNT  =                    1 / Only one group
EXTNAME = 'FUVA    '           / Segment name
EXTVER  =                    1 / Extension version
ORIGIN_X=                      / Offset within detector in first axis
ORIGIN_Y=                      / Offset within detector in second axis
SNR_FF  =                      / Average signal-to-noise of the flat field
END
XTENSION= 'IMAGE   '           / Image extension
BITPIX  =                  -32 / Bits per pixel
NAXIS   =                    2 / Number of axes
NAXIS1  =                      / Axis length
NAXIS2  =                      / Axis length
PCOUNT  =                    0 / No 'random' parameters
GCOUNT  =                    1 / Only one group
EXTNAME = 'FUVB    '           / Segment name
EXTVER  =                    1 / Extension version
ORIGIN_X=                      / Offset within detector in first axis
ORIGIN_Y=                      / Offset within detector in second axis
SNR_FF  =                      / Average signal-to-noise of the flat field
END

12.2.2 Geometric Distortion Correction Image <unique name>_geo.fits

Description: The geometric distortion reference file is used to correct for the intrinsic nonlinearity (INL) of the FUV detector. See COS-11-0039 for a detailed description of how the distortion was measured and how the images may be applied. 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 coordinate (depending on the image in the reference file, see “Format” below).

Format: 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.

EXTNAME = 'FUVA', EXTVER = 1:  Distortion in the X direction for segment FUVA
EXTNAME = 'FUVA', EXTVER = 2:  Distortion in the Y direction for segment FUVA
EXTNAME = 'FUVB', EXTVER = 1:  Distortion in the X direction for segment FUVB
EXTNAME = 'FUVB', EXTVER = 2:  Distortion in the Y direction for segment FUVB

The images do not need to be full-frame, and they may be binned. The extension headers must have keywords giving the binning and the offset of the first pixel from the beginning of a full frame. The keywords for binning are XBIN and YBIN, with integer values; 1 indicates no binning. The keywords for offset are ORIGIN_X and ORIGIN_Y; the values are integers, with zero indicating no offset (so a full-frame image would have ORIGIN_X = 0 and ORIGIN_Y = 0). In all four of these keywords, X indicates the more rapidly varying axis, and Y indicates the less rapidly varying axis.

Slectrion Criteria: Files are selected on DETECTOR.

Restrictions: This file is only used for FUV data.

Required Additional Primary Header Keywords:

FILETYPE = 'GEOMETRIC DISTORTION REFERENCE IMAGE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

The following keyword lists describe example primary and extension headers for the geometric correction images.

SIMPLE  =                    T / Fits standard
BITPIX  =                   16 / Bits per pixel
NAXIS   =                    0 / Number of axes
EXTEND  =                    T / There may be standard extensions
ORIGIN  = '        '           / FITS file originator
DATE    = '        '           / Date FITS file was generated
COMMENT   FITS (Flexible Image Transport System) format defined in Astronomy and
COMMENT   Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365.
COMMENT   Contact the NASA Science Office of Standards and Technology for the
COMMENT   FITS Definition document #100 and other FITS information.
FILENAME= '        '           / name of file
FILETYPE= 'GEOMETRIC DISTORTION REFERENCE IMAGE'
INSTRUME= 'COS     '
DETECTOR= 'FUV     '
OBSTYPE = 'ANY     '           / type of observation: IMAGING or SPECTROSCOPIC
USEAFTER= 'Jan 01 2004 00:00:00' / use after this date
DESCRIP = '        '
PEDIGREE= 'GROUND  '
VCALCOS = '2.0     '           / string to compare with CALCOS version
NEXTEND =                    4
END

XTENSION= 'IMAGE   '           / Image extension
BITPIX  =                  -32 / Bits per pixel
NAXIS   =                    2 / Number of axes
NAXIS1  =                      / Axis length
NAXIS2  =                      / Axis length
PCOUNT  =                    0 / No 'random' parameters
GCOUNT  =                    1 / Only one group
EXTNAME = 'FUVA    '           / Data for segment A
EXTVER  =                    1 / Offsets in the X direction
DATE    = '                  '
ORIGIN_X=                      / Offset within detector in first axis
ORIGIN_Y=                      / Offset within detector in second axis
XBIN    =                      / Bin factor in first axis
YBIN    =                      / Bin factor in second axis
END

XTENSION= 'IMAGE   '           / Image extension
BITPIX  =                  -32 / Bits per pixel
NAXIS   =                    2 / Number of axes
NAXIS1  =                      / Axis length
NAXIS2  =                      / Axis length
PCOUNT  =                    0 / No 'random' parameters
GCOUNT  =                    1 / Only one group
EXTNAME = 'FUVA    '           / Data for segment A
EXTVER  =                    2 / Offsets in the Y direction
DATE    = '                  '
ORIGIN_X=                      / Offset within detector in first axis
ORIGIN_Y=                      / Offset within detector in second axis
XBIN    =                      / Bin factor in first axis
YBIN    =                      / Bin factor in second axis
END

XTENSION= 'IMAGE   '           / Image extension
BITPIX  =                  -32 / Bits per pixel
NAXIS   =                    2 / Number of axes
NAXIS1  =                      / Axis length
NAXIS2  =                      / Axis length
PCOUNT  =                    0 / No 'random' parameters
GCOUNT  =                    1 / Only one group
EXTNAME = 'FUVB    '           / Data for segment B
EXTVER  =                    1 / Offsets in the X direction
DATE    = '                  '
ORIGIN_X=                      / Offset within detector in first axis
ORIGIN_Y=                      / Offset within detector in second axis
XBIN    =                      / Bin factor in first axis
YBIN    =                      / Bin factor in second axis
END

XTENSION= 'IMAGE   '           / Image extension
BITPIX  =                  -32 / Bits per pixel
NAXIS   =                    2 / Number of axes
NAXIS1  =                      / Axis length
NAXIS2  =                      / Axis length
PCOUNT  =                    0 / No 'random' parameters
GCOUNT  =                    1 / Only one group
EXTNAME = 'FUVB    '           / Data for segment B
EXTVER  =                    2 / Offsets in the Y direction
DATE    = '                  '
ORIGIN_X=                      / Offset within detector in first axis
ORIGIN_Y=                      / Offset within detector in second axis
XBIN    =                      / Bin factor in first axis
YBIN    =                      / Bin factor in second axis
END

12.3 Calibration Reference Tables

COS reference tables are selected on keyword values in the header. Within the table, one or more rows may be selected based on columns in the table. Whether one row, several rows, or all rows in the table may be selected depends on the type of reference table, as described below.

The following keyword lists describe the generic primary and extension headers for the calibration reference tables.

SIMPLE  =                    T / Fits standard
BITPIX  =                   16 / Bits per pixel
NAXIS   =                    0 / Number of axes
EXTEND  =                    T / There may be standard extensions
ORIGIN  = '        '           / Software package used for creating the file
DATE    = '        '           / Date FITS file was generated
COMMENT   FITS (Flexible Image Transport System) format defined in Astronomy and
COMMENT   Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365.
COMMENT   Contact the NASA Science Office of Standards and Technology for the
COMMENT   FITS Definition document #100 and other FITS information.
FILENAME= '        '           / name of file
FILETYPE= '        '
INSTRUME= 'COS     '
DETECTOR= '        '
OBSTYPE = 'SPECTROSCOPIC'      / type of observation: IMAGING or SPECTROSCOPIC
OBSMODE = 'TIME-TAG'           / TIME-TAG or ACCUM
USEAFTER= 'Jan 01 2004 00:00:00' / use after this date
DESCRIP = '        '
PEDIGREE= '        '
VCALCOS = '2.0     '           / string to compare with CALCOS version
NEXTEND =                    1 / number of extensions in file
END

XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                      / width of table in bytes
NAXIS2  =                      / number of rows
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)
TFIELDS =                      / number of columns
END

12.3.1 Bad Time Intervals Table <unique name>_badt.fits

Description: The bad time intervals table gives start and stop times that indicate when there was an unusual level of interference or noise. TIME-TAG events during these intervals may not be due to actual photon events.

Format: Each row of the table gives the start and stop times in MJD of one bad time interval, for one of the FUV segments. Any row in the table that matches the segment may be relevant for an observation.

Slectrion Criteria: Files are selected on DETECTOR and OBSMODE.

Restrictions: This file is only used for FUV TIME-TAG data.

Required Additional Primary Header Keywords:

FILETYPE = 'BAD TIME INTERVALS TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-1 describes the column definitions.

Table 12-1 Column Definitions for BADT table

Column Name Data Type Units Description
SEGMENT CH*4 Segment name, FUVA or FUVB
START D MJD Start time of an interval
STOP D MJD Stop time of an interval

12.3.2 Baseline Reference Frame Table <unique name>_brf.fits

Description: The baseline reference frame table gives the actual location of each of the two electronic stims, for each FUV segment. The observed locations in an image differ from the actual locations due to thermal distortion, and it is these differences that are used to determine the thermal distortion. The table also contains parameters for the size of the region to be searched in an image for the stims; for example, for stim 1 the range of pixels to be searched in the first axis of the image is from SX1 - XWIDTH to SX1 + XWIDTH inclusive (zero indexed).

Format: Each row of the table gives the stim parameters for one of the FUV segments. There should be two rows in the table, one per segment, and the appropriate row to use is selected on SEGMENT. Only one row should match.

Slectrion Criteria: Files are selected on DETECTOR.

Restrictions: This file is only used for FUV data.

Required Additional Primary Header Keywords:

FILETYPE = 'BASELINE REFERENCE FRAME TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Required Additional Extension Header Keywords:

TIMESTEP = time interval in seconds (float) within which the thermal
        distortion will be computed and applied, e.g. 200.

Table 12-2 describes the column definitions.

Table 12-2 Column Definitions for BRF Table

Column Name Data Type Units Description
SEGMENT CH*4 Segment name, FUVA or FUVB
SX1 D pixel X pixel coordinate (zero indexed) of stim 1
SY1 D pixel Y pixel coordinate (zero indexed) of stim 1
SX2 D pixel X pixel coordinate (zero indexed) of stim 2
SY2 D pixel Y pixel coordinate (zero indexed) of stim 2
XWIDTH I pixel Half width of search region for stims
YWIDTH I pixel Half height of search region for stims
A_LEFT I pixel X pixel of left side of active region
A_RIGHT I pixel X pixel of right side of active region
A_LOW I pixel Y pixel of lower side of active region
A_HIGH I pixel Y pixel of upper side of active region

12.3.3 Burst Parameters Table <unique name>_burst.fits

Description: The burst parameters table is used for deciding when the count rate in some time interval in FUV time-tag data is too high to be regarded as normal, i.e. it is a burst. Other parameters used for this calibration step are gotten from the BRFTAB and the XTRACTAB.

Format: Each row of the table gives the parameters used by the burst identification and rejection step BRSTCORR. Further details are given below. The row to be used is selected on SEGMENT of the FUV detector. Only one row should match.

Screening for bursts is done in two parts. Both rely primarily (but not exclusively) on counts in regions that do not include the source spectrum (“background” counts), and both use the median of counts within intervals of time to estimate what the count rate would be in the absence of bursts. Arrays of the number of source and background events within time intervals of length DELTA_T (or DELTA_T_HIGH for high count-rate data) are constructed from the TIME column of the time-tag data. The first phase in screening (for “large” bursts) is to take the median of all the elements of the background counts array, and to flag as bursts those elements greater than MEDIAN_N times the median. The second phase uses a boxcar smoothing of the background counts (taking the median within the box), and it uses the difference between the background counts and the running median. The boxcar smoothing is done over a time interval MEDIAN_DT, and elements that have already been flagged as bursts are not included when computing the median. The difference between the background and the median is compared with three expressions; if the difference for a time interval is larger than each of those expressions, that time interval is flagged as a burst. The expressions involve BURST_MIN (the minimum count rate that may be regarded as a burst), STDREJ (an N*sigma criterion), and SOURCE_FRAC (the burst must be larger than this fraction of the source counts). The second phase is repeated until no more intervals are identified as bursts, up to MAX_ITER times.

Slectrion Criteria: Files are selected on DETECTOR and OBSMODE.

Restrictions: This file is only used for FUV TIME-TAG data.

Required Additional Primary Header Keywords:

FILETYPE = 'BURST PARAMETERS TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-3 describes the column definitions.

Table 12-3 Column Definitions for BURST Table

Column Name Data Type Units Description
SEGMENT CH*8 Segment name, FUVA or FUVB
MEDIAN_N D Intervals with counts higher than MEDIAN_N times the global median will be rejected as bursts
DELTA_T D s Time interval for binning events
DELTA_T_HIGH D s Time interval for binning events when the count rate is high
MEDIAN_DT D s Time interval over which the boxcar median filter will be applied
BURST_MIN D count /s The count rate must be greater than this in order to be regarded as a burst
STDREJ D Reject if the counts are greater than STDREJ times the standard deviation
SOURCE_FRAC D A burst must exceed SOURCE_FRAC times the source count rate before it is considered to be significant
MAX_ITER I Maximum number of iterations when searching for “smaller” bursts
HIGH_RATE D count /s An average count rate higher than HIGH_RATE is considered to be “high” (see also DELTA_T_HIGH)

12.3.4 1-D Extraction Parameters Table <unique name>_1dx.fits

Description: The 1-D extraction parameters table gives the location of the spectrum to be extracted from a 2-D image.

Format: The row to be used is selected on SEGMENT, OPT_ELEM, CENWAVE, and APERTURE. For NUV, SEGMENT will be “NUVA”, “NUVB” or “NUVC”, for the three spectral stripes. Only one row should match. The parameters are interpreted as follows (where X and Y refer to the dispersion and cross-dispersion axes respectively).

SLOPE is the slope of the spectrum. For FUV the slope is in Y pixels per X pixel; for NUV the slope is X pixels per Y pixel.

B_SPEC is the intercept of the spectral extraction region. The region is a parallelogram, with the shorter edges at the image boundaries and the longer (sloping) edges parallel to the spectrum. The spectrum will nominally be centered within the extraction region. B_SPEC gives the zero-indexed pixel number where a line along the middle of the spectrum intersects the first column of the image.

HEIGHT is the width of the parallelogram in the second image axis direction, i.e. the length of the shorter edges of the parallelogram. This is the number of pixels (parallel to the image axis) that should be added together when extracting the spectral value for one output pixel.

B_BKG1, B_HGT1 and B_BKG2, B_HGT2 give the intercepts and widths of the two background regions. The slope is the same as for the spectral extraction region.

BWIDTH is the width of the boxcar smoothing operator to be applied to the background regions.

Slectrion Criteria: Files are selected on DETECTOR and OBSTYPE.

Restrictions: This file is only used for SPECTROSCOPIC data.

Required Additional Primary Header Keywords:

FILETYPE = '1-D EXTRACTION PARAMETERS TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-4 describes the column definitions.

Table 12-4 Column Definitions for 1DX Table

Column Name Data Type Units Description
SEGMENT CH*4 Segment name, FUVA or FUVB
OPT_ELEM CH*8 grating name
CENWAVE I central wavelength
APERTURE CH*4 PSA, BOA, or WCA
SLOPE D slope of extraction region
B_SPEC D pixel intercept (0-indexed) of middle of extr region
HEIGHT I pixel full height of extraction region
B_BKG1 D pixel intercept for first background extr region
B_BKG2 D pixel intercept for second background extr region
B_HGT1 I pixel full height of first background region
B_HGT2 I pixel full height of second background region
BWIDTH I pixel width of boxcar smoothing for background

12.3.5 Data Quality Initialization Table <unique name>_bpix.fits

Description: The data quality initialization table gives the locations of rectangular regions that cover portions of the detector that are known to be less then optimal. For each such region, a data quality flag value is given, and there is a column for a text description of the region.

Format: Each row of the table gives the location and data quality value for one rectangular region. The region may be finite in both dimensions, but it may also be one pixel wide in either or both dimensions. For FUV, there will be different regions for each of the two segments, and these are distinguished by the SEGMENT column. Any row in the table that matches the segment should be used. For NUV, the value in the SEGMENT column should be “ANY”.

Slectrion Criteria: Files are selected on DETECTOR.

Restrictions: None

Required Additional Primary Header Keywords:

FILETYPE = 'DATA QUALITY INITIALIZATION TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-5 describes the column definitions.

Table 12-5 Column Definitions for BPIX Table

Column Name Data Type Units Description
SEGMENT CH*4 FUVA, FUVB, or ANY for NUV
LX I pixel X coordinate of lower left corner of region
LY I pixel Y coordinate of lower left corner of region
DX I pixel width of region in X
DY I pixel width of region in Y
DQ I data quality value to assign to current region
TYPE CH*24 comment regarding current region

12.3.6 Deadtime Reference Table <unique name>_dead.fits

Description: The deadtime reference frame table gives the livetime factor for various values of the observed global count rate.

Format: For FUV, there will be different parameters for each of the two segments, and these are distinguished by the SEGMENT column. All rows in the table that match the segment should be used. For NUV, the value in the SEGMENT column should be “ANY”, so that all rows in the table will be used. The rows should be sorted in increasing order of OBS_RATE, the observed count rate. The livetime factor for an observation is determined by first finding the observed global count rate for that observation, and then interpolating within the relevant rows of the deadtime reference table to obtain the corresponding livetime factor.

Slectrion Criteria: Files are selected on DETECTOR.

Restrictions: None

Required Additional Primary Header Keywords:

FILETYPE = 'DEADTIME REFERENCE TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Required Additional Extension Header Keywords:

TIMESTEP = time interval in seconds (float) within which the deadtime
       will be computed and applied, e.g. 10.

Table 12-6 describes the column definitions.

Table 12-6 Column Definitions for DEAD Table

Column Name Data Type Units Description
SEGMENT CH*4 Segment name, FUVA or FUVB
OBS_RATE D count/s/pixel Observed count rate
LIVETIME D Livetime factor

12.3.7 Dispersion Relation Table <unique name>_disp.fits

Description: The dispersion relation table gives a set of polynomial coefficients for computing wavelength from pixel number.

Format: Each row of the table gives a set of dispersion coefficients. The row to be used is selected on SEGMENT, OPT_ELEM, CENWAVE, and APERTURE; if an FPOFFSET column is present in the table, then FPOFFSET will also be used to select the row. For NUV, SEGMENT will be “NUVA”, “NUVB” or “NUVC”, for the three spectral stripes. Only one row should match. If X is a zero-indexed pixel number in the dispersion direction, and X' = X + (D\_TV03 - D), the corresponding wavelength in Angstroms is: wavelength = COEFF[0] + COEFF[1] * X' + COEFF[2] * X'**2 + COEFF[3] * X'**3

Slectrion Criteria: Files are selected on DETECTOR and OBSTYPE.

Restrictions: This file is only used for SPECTROSCOPIC data.

Required Additional Primary Header Keywords:

FILETYPE = 'DISPERSION RELATION REFERENCE TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-7 describes the column definitions.

Table 12-7 Column Definitions for DISP Table

Column Name Data Type Units Description
SEGMENT CH*4 FUVA, FUVB, NUVA, NUVB, or NUVC
OPT_ELEM CH*8 Grating name
APERTURE CH*4 PSA, BOA, or WCA
CENWAVE I angstrom Central wavelength
FPOFFSET I Offset in motor steps (optional column)
NELEM I Number of coefficients to use
COEFF D[4] Array of coefficients
D_TV03 D Offset from WCA to PSA for TV 2003 data
D D Add (D_TV03 - D) to pixel coordinate before evaluating polymomial

12.3.8 Template Cal Lamp Spectra Table <unique name>_lamp.fits

Description: The template cal lamp spectra table contains template wavecal spectra, to be compared with observed wavecal spectra.

Format: Each row of the table gives a template wavecal spectrum in the INTENSITY column. The number of elements in the array will be 16384 for FUV or 1024 for FUV. The row to be used is selected on SEGMENT, OPT_ELEM, CENWAVE and FPOFFSET. For NUV, SEGMENT will be “NUVA”, “NUVB” or “NUVC”, for the three spectral stripes. Only one row should match. An observed wavecal spectrum may be compared with the template wavecal spectrum in order to find the pixel offset of the observed data.

HAS_LINES is a boolean column (L in FITS, B in IRAF). The value will normally be true (‘T’), meaning that the INTENSITY column has valid data. For some FUV segment B modes (e.g. G140L), the line lamp output and detector sensitivity are so low that no wavecal signal can be detected. In this case HAS_LINES will be false (‘F’), and calcos will copy the wavecal shift information from segment A (if there is any segment A data).

Slectrion Criteria: Files are selected on DETECTOR and OBSTYPE.

Restrictions: This file is only used for SPECTROSCOPIC data.

Required Additional Primary Header Keywords:

FILETYPE = 'TEMPLATE CAL LAMP SPECTRA TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-8 describes the column definitions.

Table 12-8 Column Definitions for LAMP Table

Column Name Data Type Units Description
SEGMENT CH*4 FUVA, FUVB, NUVA, NUVB, or NUVC
OPT_ELEM CH*8 Grating name
CENWAVE I angstrom Central wavelength
FPOFFSET I Offset in motor steps
FP_PIXEL_SHIFT D pixel Offset in pixels from FPOFFSET=0
INTENSITY R[16384] Spectrum array to compare with extracted wavecal spectrum
HAS_LINES L False if there is no valid data

12.3.9 Pulse Height Parameters Reference Table <unique name>_pha.fits

Description: The pulse height parameters reference table gives thresholds for checking FUV data based on pulse height. For TIME-TAG data, the table contains lower and upper limit thresholds (LLT and ULT). The pulse height of each event is to be compared with these limits, and the event will be flagged as bad if the pulse height is below the lower limit or above the upper limit. For ACCUM data, individual events are not available, but there will be a histogram of the pulse height distribution (PHD) included with the raw data. Tests will be based on the average of the PHD and location of the peak in the PHD, and warnings will be printed if either value is out of range. The peak must be above the lower threshold and below the upper threshold (the same LLT and ULT as used for TIME-TAG data). In addition, the average must be within a certain fraction of the location of the peak. The lower and upper limits with which the average will be compared are computed by multiplying the location of the peak by MIN_PEAK and MAX_PEAK respectively.

Format: Each row of the table gives lower and upper thresholds. The appropriate row to use is selected on SEGMENT and OPT_ELEM, and only one row should match.

Slectrion Criteria: Files are selected on DETECTOR.

Restrictions: This file is only used for FUV data.

Required Additional Primary Header Keywords:

FILETYPE = 'PULSE HEIGHT PARAMETERS REFERENCE TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-9 describes the column definitions.

Table 12-9 Column Definitions for PHA Table

Column Name Data Type Units Description
OPT_ELEM CH*8 Grating name (G130M, G160M, G140L)
SEGMENT CH*4 FUVA or FUVB
LLT I lower limit threshold
ULT I upper limit threshold
MIN_PEAK R lower limit for location of mean
MAX_PEAK R upper limit for location of mean

12.3.10 Photometric Sensitivity Reference Table <unique name>_flux.fits

Description: The photometric sensitivity reference table gives the instrumental sensitivity as a function of wavelength.

Format: Each row of the table gives the instrumental sensitivity for a given observing configuration. The number of elements in the WAVELENGTH and SENSITIVITY arrays must be the same. The flux correction is applied by dividing each element of a 1-D extracted observed spectrum by the instrumental sensitivity, obtained by interpolation within the SENSITIVITY array at the corresponding wavelength. The row to be used is selected on SEGMENT, OPT_ELEM, CENWAVE and APERTURE. For NUV, SEGMENT will be “NUVA”, “NUVB” or “NUVC”, for the three spectral stripes. Only one row should match.

Slectrion Criteria: Files are selected on DETECTOR and OBSTYPE.

Restrictions: This file is only used for SPECTROSCOPIC data.

Required Additional Primary Header Keywords:

FILETYPE = 'PHOTOMETRIC SENSITIVITY REFERENCE TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-10 describes the column definitions.

Table 12-10 Column Definitions for FLUX Table

Column Name Data Type Units Description
SEGMENT CH*4 FUVA, FUVB, NUVA, NUVB, or NUVC
OPT_ELEM CH*8 Grating name
CENWAVE I angstrom Central wavelength
APERTURE CH*4 PSA or BOA
WAVELENGTH D[2730] angstrom Array of wavelengths
SENSITIVITY R[2730] [1] Instrumental sensitivity
[1]The units for SENSITIVITY are (count/s/bin) / (erg/s/cm**2/angstrom), where bin refers to an element of a 1-D extracted spectrum.

12.3.11 Time Dependent Sensitivity Table <unique name>_tds.fits

Description: The time dependent sensitivity table gives information about the relative sensitivity as a function of time and wavelength. The relative sensitivity is represented by a piecewise linear function, one which is linear over intervals of time. The sensitivity may be discontinuous at an endpoint of a time interval. A separate function of time may be specified at each of a number of different wavelengths.

Format: Each row of the table gives the slope and intercept of the relative sensitivity for one or more time intervals, at one or more wavelengths. Further details are given below. The row to be used is selected on SEGMENT, OPT_ELEM, and APERTURE. For NUV, SEGMENT will be “NUVA”, “NUVB” or “NUVC”, for the three spectral stripes. Only one row should match.

The WAVELENGTH array gives the wavelengths, at each of which the relative sensitivity is given as a function of time. The allocated length of this array is 60 (for example), and the actual number of elements that are populated is given by NWL. It is recommended that NWL be at least two, in which case the wavelengths should cover the entire range of the detector. The TIME array gives the time at the beginning of each time interval, as a Modified Julian Date. The allocated length of the time array is 12 (for example), and the actual number is given by NT; NT must be at least one. The relative sensitivity should be extrapolated in time, using the slope and intercept of the first or last time, as appropriate; thus slope = 0 and intercept = 1 at any time suffices to describe the case where the sensitivity is constant. SLOPE and INTERCEPT are 2-D arrays, with an allocated size of 60 by 12. (This may be specified by FITS keywords TDIM8 = ‘(60, 12)’ and TDIM9 = ‘(60, 12)’.) If the time of observation T is greater than or equal to TIME[j] and less than TIME[j+1], then at a wavelength of WAVELENGTH[i] the relative sensitivity at time T is:

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

Dividing by 36525 converts the units of SLOPE from percent per year to a fraction per day. In the above notation for indexing a 2-D array, the first index (over wavelength) is the more rapidly varying. REF_TIME is a table header keyword.

Slectrion Criteria: Files are selected on DETECTOR.

Restrictions: This file is only used for SPECTROSCOPIC data.

Required Additional Primary Header Keywords:

FILETYPE = 'TIME DEPENDENT SENSITIVITY TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Required Additional Extension Header Keyword:

REF_TIME = the Modified Julian Date which serves as the zero point
        for time in the expression (above) for relative sensitivity
        as a function of time.

Table 12-11 describes the column definitions. The sizes given for the WAVELENGTH, TIME, SLOPE and INTERCEPT arrays are examples, and the sizes may be modified. The constraints are that the length of the more rapidly varying dimension of SLOPE and INTERCEPT must be the same as the length of WAVELENGTH, and the length of the less rapidly varying dimension of SLOPE and INTERCEPT must be the same as the length of TIME.

Table 12-11 Column Definitions for TDS Table

Column Name Data Type Units Description
SEGMENT CH*4 FUVA, FUVB, NUVA, NUVB or NUVC
OPT_ELEM CH*8 Grating name
APERTURE CH*8 PSA, BOA, or WCA
NWL I number of wavelengths in WAVELENGTH array
NT I number of times in TIME array
WAVELENGTH D[60] angstrom array of wavelengths
TIME D[12] MJD array of times
SLOPE D[60,12] percent /yr slope of each linear segment
INTERCEPT D[60,12] intercept of each linear segment
PEDIGREE CH*12 DUMMY if the sensitivity was not measured

12.3.12 Wavecal Parameters Reference Table <unique name>_wcp.fits

Description: The wavecal parameters reference table gives parameters which are relevant to wavecal processing.

Format: The row to use is selected on OPT_ELEM; only one row should match. The parameters are interpreted as follows.

XC_RANGE is the maximum pixel offset (and SEARCH_OFFSET is the zero-point offset) to use when doing a cross correlation between the observed data and the template wavecal. That is, the observed spectrum should be shifted relative to the template by a number of pixels, ranging from (-XC_RANGE + SEARCH_OFFSET) to (+XC_RANGE + SEARCH_OFFSET) inclusive.

XD_RANGE is half the search range for finding the spectrum in the cross dispersion direction. The search range is from b_spec - xd_range to b_spec + xd_range inclusive, where b_spec is the nominal location of the spectrum, as read from column B_SPEC in the 1dx table. BOX is the width of the boxcar filter for smoothing the cross-dispersion profile.

When applying the offsets found from the wavecals to the science data, it may happen that there was no wavecal at the same OSM position. In this case, the wavecal that was closest in time to the science observation may be used, with a correction for the difference in OSM positions. That correction is based on STEPSIZE, the number of pixels corresponding to one OSM step. There may be a check, however, to guard against using a wavecal that was taken too far away in time from the science observation. If the science observation and wavecal were taken more than MAX_TIME_DIFF apart, then the wavecal should not be used for that science observation.

Slectrion Criteria: Files are selected on DETECTOR and OBSTYPE.

Restrictions: This file is only used for SPECTROSCOPIC data.

Required Additional Primary Header Keywords:

FILETYPE = 'WAVECAL PARAMETERS REFERENCE TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-12 describes the column definitions:

Table 12-12 Column Definitions for WCP Table

Column Name Data Type Units Description
OPT_ELEM CH*8 Grating name
XC_RANGE I pixel Maximum lag (amplitude) for cross correlation
SEARCH_OFFSET D pixel Zero-point offset for the search range
RESWIDTH D pixel Resolution width in dispersion direction
MAX_TIME_DIFF D day Defines ‘close in time’ for wavecals
STEPSIZE I OSM step One step of OSM is this many pixels
XD_RANGE I pixel Amplitude of search range for finding spectrum
BOX I pixel Width of boxcar smoothing filter

12.3.13 Spectroscopic WCS Parameters Table <unique name>_spwcs.fits

Description: The spectroscopic WCS parameters table gives values to be used for populating the world coordinate keywords.

Format: The row to be used is selected on SEGMENT, OPT_ELEM, CENWAVE, and APERTURE. For NUV, SEGMENT will be “NUVA”, “NUVB” or “NUVC”, for the three spectral stripes. Only one row should match. The columns are interpreted as follows.

The detector coordinate system has two dimensions. In this section we’ll call the more rapidly varying axis X and the less rapidly varying axis Y. The world coordinate system has three dimensions, the spectral coordinate, right ascension, and declination. The reference pixel is at approximately the middle of the detector. CTYPE1 can be “WAVE” to indicate that the wavelength is a linear function of pixel number, or it can be “WAVE-GRI” to indicate that the wavelengths should be computed by using the grating (“grism”) equation. In either case, the wavelengths are in vacuum. CRVAL1 is the wavelength at the reference pixel. CRPIX1 is the location of the reference pixel in the first axis (X), and CRPIX2 is the location in the second axis (Y).

CDELT1 is the dispersion in Angstroms per pixel at the reference pixel. At a single wavelength (nominally the wavelength at the reference pixel), a pixel when projected onto the sky would be approximately a rectangle. CDELT2 and CDELT3 are the sizes of that rectangle in the X and Y axes. G is the groove density of the grating, e.g. 3.8e+6 grooves per meter for G130M.

SPORDER is the spectral order. This will usually be 1, but for G230L, stripe NUVC, SPORDER will be 2.

ALPHA is the angle between the normal to the grating and the light that is incident onto the grating.

THETA is the angle between two lines from the grating to the detector, the line to the reference pixel and the line that is perpendicular to the detector. Since the reference pixel is close to the middle of the detector, THETA will probably be close to zero.

Slectrion Criteria: Files are selected on DETECTOR and OBSTYPE.

Restrictions: This file is only used for SPECTROSCOPIC data.

Required Additional Primary Header Keywords:

FILETYPE = 'SPECTROSCOPIC WCS PARAMETERS TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-13 describes the column definitions.

Table 12-13 Column Definitions for SPWCS Table

Column Name Data Type Units Description
SEGMENT CH*4 segment or stripe name
OPT_ELEM CH*8 grating name
CENWAVE I angstrom central wavelength
APERTURE CH*4 PSA, BOA, or WCA
CTYPE1 CH*8 type of world coordinate on spectral axis
CRPIX1 D pixel reference pixel number for spectral axis (X)
CRPIX2 D pixel reference pixel number for Y axis
CRVAL1 D angstrom wavelength at the reference pixel
CDELT1 D angstrom/pixel dispersion at reference pixel
CDELT2 D degree/pixel size of a pixel in dispersion direction
CDELT3 D degree/pixel size of a pixel perpendicular to dispersion direction
G D grooves/m groove density of grating
SPORDER I   spectral order
ALPHA D degree incident angle from aperture onto grating
THETA D degree angle from reference pixel to base of normal from grating to detector

12.3.14 Walk Correction Table <unique name>_walk.fits

Description: The walk correction table gives parameters for correcting the pixel coordinates XCORR and YCORR of FUV TIME-TAG data, depending on the pulse height amplitude (PHA). The parameters are used for computing the coefficients of polynomials in PHA (one polynomial for XCORR, another for YCORR) that give the corrections to be subtracted from XCORR and YCORR. The coefficients of PHA are themselves computed by evaluating polynomial functions of XCORR and YCORR. Further details are given below.

Format: One row of the table gives parameters for segment FUVA, and the other row gives parameters for FUVB; the appropriate row to use is selected by SEGMENT.

Selection Criteria: Files are selected on DETECTOR.

Restrictions: This file is only used for FUV TIME-TAG data.

Required Additional Primary Header Keywords:

FILETYPE = 'WALK CORRECTION TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Table 12-14 describes the column definitions:

Table 12-14 Column Definitions for WALK Table

Column Name Data Type Units Description
SEGMENT CH*4 FUVA or FUVB
X0 D pixel Zero point in XCORR for polynomials, i.e. to be subtracted from XCORR before evaluating polynomials
Y0 D pixel Zero point in YCORR for polynomials
N_X I Number of terms in X
N_Y I Number of terms in Y
N_PHA_COEFF I Number of coefficients in polynomial for PHA
XCOEFF D Array of coefficients for determining the change to XCORR
YCOEFF D Array of coefficients for determining the change to YCORR

XCOEFF and YCOEFF are 3-D arrays, with axis lengths N_X, N_Y, N_PHA_COEFF. See below for more information regarding the order of the values in the arrays.

X0 and Y0 will be subtracted from the pixel coordinates before evaluating the polynomial expressions, to reduce numerical problems. Appropriate values are X0 = 8192, Y0 = 512 (these do not need to be integers).

Suppose, for example, N_PHA_COEFF = 3. This would be a quadratic function of PHA for the X coordinates (with a similar expression for Y). The three coefficients x_c0, x_c1 and x_c2 would be computed by evaluating the polynomials in XCOEFF (and similarly using YCOEFF for Y) at the pixel position (XCORR, YCORR) for a row in the EVENTS table. Then the changes to be subtracted from XCORR and YCORR would be:

dx = x_c1 * (pha - x_c0) + x_c2 * (pha - x_c0)^2 dy = y_c1 * (pha - y_c0) + y_c2 * (pha - y_c0)^2

x_c0 and y_c0 are the pha0 terms for their respective axes. The XCORR (YCORR) coordinate of an event with pha = x_c0 (y_c0) will not be modified. Note that the first of the pha coefficients is the offset to be subtracted from PHA, while all the rest are polynomial coefficients. Since the coefficients x_c0, x_c1, x_c2 (and y_c0, y_c1, y_c2) are computed by evaluating the polynomial expressions of x and y, they differ, in general, for each event in a rawtag table. For example, if N_X = 4 and N_Y = 3 (cubic in x, quadratic in y):

x_c0 = a000 + a100 * x + a010 * y\\ + a200 * x^2 + a110 * x * y + a020 * y^2\\ + a300 * x^3 + a210 * x^2 * y + a120 * x * y^2\\ + a310 * x^3 * y + a220 * x^2 * y^2\\ + a320 * x^3 * y^2\\ x_c1 = a001 + a101 * x + a011 * y\\ + a201 * x^2 + a111 * x * y + a021 * y^2\\ + a301 * x^3 + a211 * x^2 * y + a121 * x * y^2\\ + a311 * x^3 * y + a221 * x^2 * y^2\\ + a321 * x^3 * y^2\\ x_c2 = a002 + a102 * x + a012 * y\\ + a202 * x^2 + a112 * x * y + a022 * y^2\\ + a302 * x^3 + a212 * x^2 * y + a122 * x * y^2\\ + a312 * x^3 * y + a222 * x^2 * y^2\\ + a322 * x^3 * y^2\\

where x = XCORR - X0, y = YCORR - Y0, and each Aijk is an element of XCOEFF (and similarly for YCOEFF). For each k, the Aijk coefficients (i and j varying) describe a polynomial in x and y for computing one coefficient of the polynomial in (pha - pha0) for the walk correction in X (or Y). i = 0 is a term that includes x^0, i = 1 is a term that includes x^1, etc. j = 0 is a term that includes y^0, j = 1 is a term that includes y^1, etc. k = 0 is a term for computing pha0, k = 1 is a term for the coefficient of (pha - pha0)^1, k = 2 is a term for the coefficient in (pha - pha0)^2, etc.

If the coefficients are applied as shown above, they would be stored in one row of the XCOEFF (or YCOEFF) column in the following order (reading left to right):

a000, a100, a200, a300,\\ a010, a110, a210, a310,\\ a020, a120, a220, a320,\\ \\ a001, a101, a201, a301,\\ a011, a111, a211, a311,\\ a021, a121, a221, a321,\\ \\ a002, a102, a202, a302,\\ a012, a112, a212, a312,\\ a022, a122, a222, a322\\

In code to read or write an XCOEFF or YCOEFF array, the dimensions of an array would be written differently depending on the language. In IDL or Fortran, the dimensions would be N_X, N_Y, N_PHA_COEFF. In Python or C, the dimensions would be N_PHA_COEFF, N_Y, N_X. Element a012 (in the notation above, i.e. the coefficient of y for computing x_c2) of xcoeff would be accessed as xcoeff[0,1,2] in IDL, or as xcoeff[2,1,0] in Python.

As described above, XCOEFF and YCOEFF have the same dimensions, i.e. the same polynomial orders in x, y and pha. This is not essential, just a simplification.

Here is an example in Python, for N_PHA_COEFF = 3, N_Y = 3, N_X = 4:

 >>> x = np.array (['a000', 'a100', 'a200', 'a300',
                'a010', 'a110', 'a210', 'a310',
                'a020', 'a120', 'a220', 'a320',
                'a001', 'a101', 'a201', 'a301',
                'a011', 'a111', 'a211', 'a311',
                'a021', 'a121', 'a221', 'a321',
                'a002', 'a102', 'a202', 'a302',
                'a012', 'a112', 'a212', 'a312',
                'a022', 'a122', 'a222', 'a322'])

>>> print x
['a000' 'a100' 'a200' 'a300' 'a010' 'a110' 'a210' 'a310' 'a020' 'a120'
 'a220' 'a320' 'a001' 'a101' 'a201' 'a301' 'a011' 'a111' 'a211' 'a311'
 'a021' 'a121' 'a221' 'a321' 'a002' 'a102' 'a202' 'a302' 'a012' 'a112'
 'a212' 'a312' 'a022' 'a122' 'a222' 'a322']

>>> x = x.reshape ((3,3,4))             # n_pha_coeff=3, n_y=3, n_x=4

>>> print x
[[['a000' 'a100' 'a200' 'a300']         # for pha0
  ['a010' 'a110' 'a210' 'a310']
  ['a020' 'a120' 'a220' 'a320']]

 [['a001' 'a101' 'a201' 'a301']         # for coeff of (pha - pha0)
  ['a011' 'a111' 'a211' 'a311']
  ['a021' 'a121' 'a221' 'a321']]

 [['a002' 'a102' 'a202' 'a302']         # for coeff of (pha - pha0)^2
  ['a012' 'a112' 'a212' 'a312']
  ['a022' 'a122' 'a222' 'a322']]]

>>> print x[2,1,0]
a012
>>> print x[0,1,2]
a210

12.3.15 Gain Sag Reference Table <unique name>_gsag.fits

Description: The gain sag reference table gives the locations of rectangular regions for portions of the FUV detector that have very low pulse height amplitude (PHA). For each such region, a data quality flag value is given, although the value is the same in every row.

Format: This file contains multiple extensions. Each extension is a binary table giving regions to be flagged as low gain regions. The appropriate extension to use is selected by SEGMENT and FUV high voltage (given by keyword HVLEVELA or HVLEVELB in the first extension header of the raw file); see also the section on extension header keywords below. Each row of the table gives the location and data quality value for one rectangular region. The format of a table is similar to the bad pixel reference table (_bpix.fits), except that the gain sag table includes a DATE column and does not include either a SEGMENT or TYPE column. The DATE column is used to select rows. A row will be used to flag a gain sagged region if the value in the DATE column is less than or equal to the exposure start time.

Selection Criteria: Files are selected on DETECTOR.

Restrictions: This file is only used for FUV data.

Required Additional Primary Header Keywords:

FILETYPE = 'GAIN SAG REFERENCE TABLE'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Required Additional Extension Header Keywords:

Each extension must have the following keywords:

SEGMENT   = segment name, FUVA or FUVB (string)
HVLEVELA or HVLEVELB = commanded high voltage, raw (int)

Keywords SEGMENT and either HVLEVELA or HVLEVELB (depending on SEGMENT) are used for selecting the appropriate extension. SEGMENT must be the same as in the raw file, and the commanded detector high voltage (HVLEVELA or HVLEVELB) will have been populated by calcos using the HVTAB (_hv).

Table 12-15 describes the column definitions:

Table 12-15 Column Descriptions for GSAG Table

Column Name Data Type Units Description
DATE D MJD Modified Julian Date at which the PHA in a region dropped so low that the region should be flagged as gain-sagged.
LX I pixel X coordinate of lower left corner of region
LY I pixel Y coordinate of lower left corner of region
DX I pixel width of region in X
DY I pixel width of region in Y
DQ I data quality value to assign to current region

12.3.16 High Voltage Reference Table <unique name>_hv.fits

Description: The high voltage reference table gives the times when the FUV high voltage was changed, and the value (raw counts) that was used in the command to set the high voltage. Calcos will use the values in this table to populate extension header keywords HVLEVELA and HVLEVELB.

Format: This file contains two extensions. Each extension is a binary table giving the date/time and commanded high voltage value for one FUV segment. Keyword EXTNAME is used for selecting the appropriate extension.

Selection Criteria: Files are selected on DETECTOR.

Restrictions: This file is only used for FUV data.

Required Additional Primary Header Keywords:

FILETYPE = 'FUV HIGH VOLTAGE HISTORY'
VCALCOS = a string (e.g. '2.0') to compare with the CALCOS version.

Required Additional Extension Header Keywords:

Each extension must have the following keyword:

EXTNAME = segment name, FUVA or FUVB (string)

Table 12-16 describes the column definitions:

Table 12-16 Column Definitions for HV File

Column Name Data Type Units Description
DATE D MJD Modified Julian Date when the high voltage was changed.
HVLEVEL# I counts # = A or B. Commanded (raw) high voltage level, segment A or B

The column for commanded high voltage will be HVLEVELA in the table for which EXTNAME = ‘FUVA’, and it will be HVLEVELB in the table for which EXTNAME = ‘FUVB’.

12.3.17 Trace Table <unique name>_trace.fits

Description: The trace table gives the variation of y centroid of the spectrum as a function of column number (XCORR) in COS FUV data.

Format: The file is a FITS table with a primary header and one extension with optional EXTNAME = ‘TRACE’. The row to be used is selected on SEGMENT, OPT_ELEM, CENWAVE and APERTURE. Each row has 8 columns: SEGMENT, OPT_ELEM, CENWAVE and APERTURE are used to select the row to use. DESCRIP supplies a short description, while TRACE_YLOC is the location of the center of the trace. TRACE is an array of 16384 floats where the index is the value of XCORR and the value is the offset to be subtracted from each event’s YFULL value. The value of XCORR for each event is interpolated onto the TRACE array to give the value of the shift to be applied to the corresponding YFULL value of the event. This process happens in the TRCECORR step of the COS pipeline. ERROR is an array of 16384 floats that gives the statistical error of the TRACE measurement.

Selection Criteria: Files are selected on INSTRUME, DETECTOR, OBSTYPE and LIFE_ADJ

Restrictions: This file is only used for FUV data

Required Additional Primary Header Keywords:

FILETYPE = '1D SPECTRAL TRACE TABLE'
VCALCOS  = a string (e.g. '2.23') to compare with the CALCOS version

Table 12.17 describes the column definitions:

Table 12.17 Column definitions for TRACETAB reference file

Column Name Data Type Units Description
SEGMENT CH*4 segment or stripe name
OPT_ELEM CH*8 grating name
CENWAVE I Angstrom central wavelength
APERTURE CH*4 PSA or BOA
DESCRIP CH*28 description
TRACE_YLOC R pixel YCORR location of center of trace (median)
TRACE R[16384] pixel profile y location
ERROR R[16384] pixel error in trace

12.3.18 Profile Table <unique name>_profile.fits

Description: The profile table gives the profile of a point source perpendicular to the dispersion as a function of column number (XFULL) in COS FUV data.

Format: The file is a FITS table with a primary header and one extension with optional EXTNAME = ‘PROFILE’. The row to be used is selected on SEGMENT, OPT_ELEM, CENWAVE and APERTURE. Each row has 8 columns: SEGMENT, OPT_ELEM, CENWAVE and APERTURE are used to select the row to use. DESCRIP gives a short description of the row. CENTER is the measured centroid of the profile in the full-sized array in (XFULL, YFULL) coordinates. ROW_0 is the index of the first row of the profile in the full-sized array. In other words, if the profile has NROWS rows, it corresponds to rows with 0-based indices running from ROW_0 to (ROW_0 + NROWS - 1). PROFILE is the 2-d array of floats that gives the profile in the cross-dispersion direction for each column of data in (XFULL, YFULL) space (offset by ROW_0). This reference file is used in the ALGNCORR step of calcos processing, which currently is only active for FUV data taken at LP3. During this step, the flux-weighted centroid of the science data over ‘good’ rows and columns is calculated, and compared with the flux-weighted centroid of the profile contained in this reference file over the same rows and columns. The difference between these centroids is applied to the YFULL values of the events to align each set of science data to the same center.

Selection Criteria: Files are selected on INSTRUME, DETECTOR, OBSTYPE and LIFE_ADJ

Restrictions: This file is only used for FUV data

Required Additional Primary Header Keywords:

FILETYPE = '1D SPECTRUM PROFILE TABLE'
VCALCOS  = a string (e.g. '2.23') to compare with the CALCOS version

Table 12.17 describes the column definitions:

Table 12.17 Column definitions for the PROFTAB reference file

Column Name Data Type Units Description
SEGMENT CH*4 segment or stripe name
OPT_ELEM CH*8 grating name
CENWAVE I Angstrom central wavelength
APERTURE CH*4 PSA, BOA or ANY
DESCRIP CH*28 description
CENTER R pixel profile centroid
ROW_0 I pixel row offset of profile array
PROFILE R[16384,339] pixel profile in (XFULL, YFULL), offset by ROW_0

12.3.19 Two Zone Extraction Table <unique name>_2zx.fits

Description: The two zone extraction table contains the starting values for the object center and background regions, as well as containing the cumulative flux boundary values for the two zone extraction.

Format: The file is a FITS table with a primary header and one data extension. The row to be used is selected on SEGMENT, OPT_ELEM, CENWAVE and APERTURE. Each row has 16 columns: SEGMENT, OPT_ELEM, CENWAVE and APERTURE are used to select the row to use. B_SPEC is the center of the science extraction aperture, and is used by the ALGNCORR step to get an initial guess for the location of the spectral trace. B_BKG1 and B_BKG2 are the center of the background regions, and HEIGHT and BHEIGHT are the widths of the object and background regions. BWIDTH is the width of the smoothing box used to smooth the background region in the extraction step.

In the two-zone extraction step (which is only performed if the ALGNCORR keyword is set to ‘TWOZONE’, currently only for FUV data taken at LP3), the spectral profile in the PROFTAB is analyzed to determine the boundaries of ‘inner’ and ‘outer’ zones. These boundaries are specified in terms of the cumulative flux enclosed. In the inner region, the flux is summed within the region and any DQ flags are propagated to the extracted spectrum. In the outer region, the flux is also summed and added to the flux in the inner region, but any DQ flags in the outer region are not propagated to the final extracted spectrum. The columns LOWER_OUTER, UPPER_OUTER, LOWER_INNER and UPPER_INNER give the cumulative flux boundaries to be used in the two zone extraction. Typically the outer boundaries enclose 99% of the flux, while the inner boundaries enclose 80%.

The YERRMAX column is used in the ALGNCORR step to test the statistical error in the calculation of the flux-weighted centroid of the science data. If this measurement is greater than the value of YERRMAX for that setting, the spectrum is deemed ‘not found’, and the location of the center of the reference profile is used instead.

The PEDIGREE column gives the pedigree of the information in the row, with values that are typically ‘INFLIGHT’, ‘GROUND’ or ‘DUMMY’.

Selection Criteria: Files are selected on INSTRUME, DETECTOR, OBSTYPE and LIFE_ADJ

Restrictions: This file is only used for FUV data

Required Additional Primary Header Keywords:

FILETYPE = 'TWO-ZONE SPECTRAL EXTRACTION PARAMETERS TABLE'
VCALCOS  = a string (e.g. '2.23') to compare with the CALCOS version

Table 12.19 describes the column definitions:

Table 12.19 Column definitions for the TWOZXTAB reference file

Column Name Data Type Units Description
SEGMENT CH*4   segment or stripe name
OPT_ELEM CH*5   grating name
CENWAVE S Angstrom central wavelength
APERTURE CH*3   aperture
B_SPEC D pixel location of center of object aperture
B_BKG1 D pixel location of center of background #1 aperture
B_BKG2 D pixel location of center of background #2 aperture
HEIGHT S pixel width of object aperture
BHEIGHT S pixel width of background apertures
BWIDTH S pixel background smoothing width
LOWER_OUTER D   percentage of flux below lower outer boundary
UPPER_OUTER D   percentage of flux below upper outer boundary
LOWER_INNER D   percentage of flux below lower inner boundary
UPPER_INNER D   percentage of flux below upper inner boundary
YERRMAX D pixel maximum allowed error in centroid
PEDIGREE CH*8   pedigree

Table Of Contents

Previous topic

Section 11 Wide Field Camera 3

Next topic

Section 13. CDBS Control Relations and Tables

This Page