2.6 Headers, Keywords, and Relationship to Phase II

As with previous HST instruments, the FITS header keywords in COS data files store important information characterizing the observations and telemetry received during the observations, and describe the post-observation processing of your dataset. Each keyword follows FITS conventions and is no longer than eight characters. Values of keywords can be integer, real (floating-point), boolean, and character strings. Several keywords are HST and COS specific. Knowledge of the keywords and where to find them is an important first step in understanding your data. By examining your file headers using the astropy.io.fits and astropy.table modules in the AstroConda environment, you will find detailed information about your data including:

  • Target name, coordinates, proposal ID, and other proposal level information.
  • Observation and exposure time information such as observation start and duration.
  • Instrument configuration information such as detector, grating, central wavelength setting, and aperture.
  • Readout definition parameters such as subarray parameters.
  • Exposure-specific information such as more detailed timing, world coordinate system information, and Fine Guidance Sensor identification.
  • Calibration information such as the calibration switches and reference files used by the pipeline and parameters derived from the calibration, such as image statistics and wavelength shifts.

The keywords relevant for one COS data type will not necessarily be relevant to another. Accordingly, you will find that the header in a particular file type contains a unique combination of keywords appropriate for that type of observation. Long definitions for the keywords can also be accessed from the following Web page, which provides detailed explanations of the contents and algorithm for populating the keywords. This site also provides sample headers for different COS file types:
http://stdatu.stsci.edu/keyword/.

Keywords that deal with a particular topic, such as the instrument configuration, are grouped together logically throughout the headers. Table 2.15 lists a useful subset of these groups of keywords, indicates the name of the grouping, and where applicable, shows their relationship to the corresponding information from the Phase II proposal.

Table 2.15 summarizes the possible calibration switch keywords, and indicates whether they are present for a particular observation; it also indicates the reference file keyword corresponding to the particular calibration step. A calibration switch keyword is initially populated with values of OMIT, PERFORM or N/A in the raw uncalibrated science data (with the exception of XTRACTALG, which has values of 'BOXCAR' or 'TWOZONE' to select the extraction algorithm to be used). After each calibration step is executed in the COS calibration pipeline, calcos will set the keyword switch to COMPLETE.

Spectroscopic Calibration Switch Keywords

Table 2.15: Selected Header Keywords and Relationship to Phase II Parameters

Header KeywordPhase II EquivalentDescription
Gerneral File Information (Primary Header) 
FILENAME
Name of file
FILETYPE
Type of data found in the file (SCI, ACQ, APT, ASN_TABLE)
NEXTEND
Number of extensions in the file
DATE
Date file was created
Program Information (Primary Header)
PROPOSID
4 or 5 digit program number

PR_INV_L
PR_INV_F

PR_INV_M

PI Last Name
PI First Name
PI Middle Initial

Last name of principal investigator
First name of principal investigator
Middle name initial of principal investigator

LINENUMVisit_Number, Exposure_NumberIndicates the visit and exposure number from the Phase II
proposal: Visit_Number, Exposure_Number
Target Information (Primary Header)
TARGNAMETargetNameName of target
RA_TARG
DEC_TARG
RA
DEC
Right ascension of the target (deg) (J2000)
Declination of the target (deg) (J2000)
POSTARG1
POSTARG2
POSTARG
POSTARG
Postarg in axis 1 direction
Postarg in axis 2 direction
Science Instrument Configuration (Primary Header)
OBSTYPE
Observation type (IMAGING or SPECTROSCOPIC)
OBSMODE OpmodeOperating mode (ACCUM, TIME-TAG)
EXPTYPEOpmodeExposure type (EXTERNAL/SCI, WAVECAL, PHA, DARK, FLAT, ACQ/IMAGE, ACQ/SEARCH, ACQ/PEAKD, ACQ/PEAKXD, ENG DIAG, or MEM DUMP)
DETECTORConfigDetector in use (NUV or FUV)
SEGMENTSEGMENTFUV detector segment in use (FUVA, FUVB, BOTH, or N/A)
DETECTHV
FUV detector high voltage state (NomAB, NomA, NomB, Off, Low)
SUBARRAY
Data from a subarray (T) or full frame (F)
LAMPUSED
Lamp status, NONE or name of lamp which is on (P1, D1, P2, or D2)
LAMPSET
Spectral calibration lamp current value (milliamps)
LIFE_ADJLIFETIME-POSDetector life time adjustment position
OPT_ELEM SpElementOptical element in use (grating or mirror name)
CENWAVE WavelengthCentral wavelength for grating settings
APERTUREApertureAperture name
PROPAPERApertureProposed aperture name
APER_FOV
Aperture field of view description in mm
APMPOS
Aperture Mechanism Position from telemetry
APERXPOS
Aperture Block Pos. cross dispersion (telemetry)
FPPOSFPPOSGrating offset index (1–4) for spectrum dithers (FPPOS)
TAGFLASHFLASHType of flashed exposures in TIME-TAG (NONE, AUTO, or UNIFORMLY-SPACED)
EXTENDEDExtendedIs the target extended (Yes or No)
NRPTEXPNumberOfIterationsNumber of repeat exposures in dataset: Default = 1
EXP_NUM
Exposure number for repeated observations
SHUTTER
External shutter position (OPEN or CLOSED)
Engineering Parameters (Primary Header)
FPOFFSET
FP offset from nominal, in motor steps
DEVENTA
Digital event counter, FUV segment A (counts s–1)
DEVENTB
Digital event counter, FUV segment B (counts s–1)
FEVENTA
Fast event counter, FUV segment A (counts s–1)
FEVENTB
Fast event counter, FUV segment B (counts s–1)
MEVENTS
NUV MAMA event counter (counts s–1)
Target Acquisition Dataset Identifiers (Primary Header)
ACQSNAME
Rootname of first acquisition search exposure
ACQINAME
Rootname of first acquisition image exposure
PEAKXNAM
Rootname of first x-dispersion peakup exposure
PEAKDNAM
Rootname of first dispersion peakup exposure
ACQ_NUM
Total number of exposures in acquisition sequence
Archive Search Keywords (Primary Header)
BANDWID
Bandwidth of the data
SPECRES
Approximate resolving power at central wavelength
CENTRWV
Central wavelength of the data
MINWAVE
Minimum wavelength in spectrum
MAXWAVE
Maximum wavelength in spectrum
PLATESC
Plate scale (arcsec/pixel)

Association Keywords (Primary Header)

ASN_ID
Unique identifier assigned to association
ASN_MTYP
Role of the member in the association
ASN_TAB

Name of the association table

Exposure Information (in Extension header 1 or greater)
DATE-OBS

UT date of start of observation (yyyy-mm-dd)

TIME-OBS
UT time of start of observation (hh:mm:ss)
EXPTIME
Corrected exposure time (seconds). For FUV exposures, the largest of EXPTIMEA and EXPTIMEB
EXPTIMEA
Corrected FUV Segment A exposure time (seconds)
EXPTIMEB

Corrected FUV Segment B exposure time (seconds)

RAWTIME
Exposure time of an individual raw exposure (seconds)
EXPSTART
Exposure start time (Modified Julian Date)
EXPEND
Exposure end time (Modified Julian Date)
EXPSTRTJ
Exposure start time (Julian Date)
EXPENDJ
Exposure end time (Julian Date)
PLANTIMETimePerExposurePlanned exposure time (seconds)
NINTERPT
Number of exposure interrupts
ORIENTAT

Position angle of image y-axis (degrees)

SUNANGLE
Angle between sun and V1 axis
MOONANGL

Angle between moon and V1 axis

SUN_ALT

Altitude of the sun above Earth’s limb

FGSLOCK
Commanded FGS lock (Fine, Coarse, Gyros, Unknown)
GYROMODE
Number of gyros scheduled for observation
REFFRAME
Guide star catalog version
Aperture Information (in Extension header 1 or greater)
RA_APER DEC_APER

RA of reference aperture center
Declination of reference aperture center

PA_APER

Position angle of reference aperture center

SHIFT1A
Wavecal shift determined for FUV segment A or NUV stripe A in dispersion direction (pixels)
SHIFT1B
Wavecal shift determined for FUV segment B or NUV stripe B in dispersion direction (pixels)
SHIFT1C
Wavecal shift determined for NUV stripe C in dispersion direction (pixels)
SHIFT2A
Offset in cross-dispersion direction for FUV segment A or NUV stripe A (pixels)
SHIFT2B
Offset in cross-dispersion direction for FUV segment B or NUV stripe B (pixels)
SHIFT2C
Offset in cross-dispersion direction for NUV stripe C (pixels)
SP_LOC_A
Cross-dispersion location at which calcos extracted the FUV segment A or NUV stripe A spectrum
SP_LOC_B
Cross-dispersion location at which calcos extracted the FUV segment B or NUV stripe B spectrum
SP_LOC_C
Cross-dispersion location at which calcos extracted the NUV stripe C spectrum
SP_NOM_A
Nominal location of the spectral extraction region for FUV segment A or NUV stripe A based on the wavecal aperture location
SP_NOM_B
Nominal location of the spectral extraction region for FUV segment B or NUV stripe B based on the wavecal aperture location
SP_NOM_C
Nominal location of the spectral extraction region for NUV stripe C based on the wavecal aperture location
SP_OFF_A
Offset from SP_NOM_A at which the spectrum was found
SP_OFF_B

Offset from SP_NOM_B at which the spectrum was found

SP_OFF_C
Offset from SP_NOM_C at which the spectrum was found
SP_SLP_A
Slope of FUV segment A or NUV stripe A spectrum
SP_SLP_B
Slope of FUV segment B or NUV stripe B spectrum
SP_SLP_C

Slope of NUV stripe C spectrum

SP_HGT_A
Height in pixels of the FUV Segment A spectral extraction region
SP_HGT_B
Height in pixels of the FUV Segment B spectral extraction region
DPIXEL1A
Fractional part of pixel coordinate for FUV segment A or NUV stripe A (pixels). Average binning error
DPIXEL1B
Fractional part of pixel coordinate for FUV segment B or NUV stripe B (pixels).  Average binning error
DPIXEL1C
Fractional part of pixel coordinate for NUV stripe C (pixels). Average binning error
TIME-TAG Parameters (in Extension header 1 or greater)
BUFFTIMEBUFFER-TIMEOnboard memory half-buffer-fill time
OVERFLOW
Number of science data overflows
NBADEVNT
Total number of events deleted in screening (NUV)
NBADEVTA
Total number of events deleted in screening (FUV, segment A)
NBADEVTB
Total number of events deleted in screening (FUV, segment B)
NEVENTS
Total number of events in raw data (NUV)
NEVENTSA
Total number of events in raw data (FUV, segment A)
NEVENTSB
Total number of events in raw data (FUV, segment B)
FUV TIME-TAG Parameters (in Extension header 1 or greater)
TBRST_A
TBRST_B

Time lost to bursts on FUV segment A (seconds)
Time lost to bursts on FUV segment B (seconds)

TBADT_A
TBADT_B

Time lost to BADTCORR screening on FUV segment A (sec)
Time lost to BADTCORR screening on FUV segment B (sec)

NPHA_A
NPHA_B

Number of events lost due to pulse height screening on segment A Number of events lost due to pulse height screening on segment B
NBRST_A
NBRST_B

Number of events lost due to burst screening on segment A
Number of events lost due to burst screening on segment B

NBADT_A
NBADT_B

Number of events flagged by BADTCORR for segment A
Number of events flagged by BADTCORR for segment B

NOUT_A
NOUT_B

Number of events outside the active area for segment A
Number of events outside the active area for segment B

NUV TIME-TAG Parameters (in Extension header 1 or greater)
NBADT
Number of events flagged by BADTCORR
TBADT
Time lost to BADTCORR screening (sec)
TAFGFLASH Parameters (in Extension header 1 or greater)
NUMFLASH
Integer number of flashes
LMPDURi
Duration of flash i, seconds
LMP_ONi
Lamp turn-on time for flash i, seconds since EXPSTART
LMPOFFi
Lamp turn-off time for flash i, seconds since EXPSTART
LMPMEDi
Median time of flash i, seconds since EXPSTART
Velocity Reference Frame Conversion (in Extension header 1 or greater)
V_HELIO
Geometric to heliocentric velocity
V_LSRSTD
Heliocentric to standard solar LSR
Doppler Correction Parameters (in Extension header 1 or greater)
ORBITPER
Orbital period used onboard for Doppler correction
DOPPER
Doppler shift period (seconds)
DOPPMAGV
Doppler shift magnitude (Km/sec)
DOPPON
Doppler correction flag (T or F)
DOPPZERO
Commanded time of zero Doppler shift (MJD)
Instrument Doppler Correction Parameters (in Extension header 1 or greater)
ORBTPERT
Orbital period used onboard for Doppler correction
DOPMAGT
Doppler shift magnitude (low-res pixels)
DOPPONT
Doppler correction flag (T or F)
DOPPZEROT
Commanded time of zero Doppler shift (MJD)

Global Count Parameters (in Extension header 1 or greater)

GLOBRATE
Global count rate (NUV)
GLOBRT_A
Global count rate (FUV, segment A)
GLOBRT_B
Global count rate (FUV, segment B)
Subarray Readout Parameters1 (in Extension header 1 or greater)
NSUBARRY
Number of subarrays (1–8)
CORNER[N]X
Subarray N axis1 corner pt in unbinned detector pixels. Valid values of N are 0 to 7
CORNER[N]Y
Subarray N axis2 size in unbinned detector pixels, with N=0 to 7
SIZE[N]Y
Subarray N axis1 corner pt in unbinned detector pixels, with N=0 to 7
SIZE[N]X
Subarray N axis2 size in unbinned detector pixels, with N=0 to 7

Stim Pulse Parameters (in Extension header 1 or greater; for FUV data only)

STIMRATE
Approximate STIM pulse injection rate
STIMA_LX
STIMA_LY
STIMA_RX
STIMA_RY

Segment A Left STIM pulse X centroid in raw data
Segment A Left STIM pulse Y centroid in raw data
Segment A Right STIM pulse X centroid in raw data
Segment A Right STIM pulse Y centroid in raw data

STIMB_LX
STIMB_LY
STIMB_RX
STIMB_RY

Segment B Left STIM pulse X centroid in raw data
Segment B Left STIM pulse Y centroid in raw data
Segment B Right STIM pulse X centroid in raw data
Segment B Right STIM pulse Y centroid in raw data

STIMA0LX
STIMA0LY
STIMA0RX
STIMA0RY

Reference location of Segment A Left STIM pulse X coordinate
Reference location of Segment A Left STIM pulse Y coordinate
Reference location of Segment A Right STIM pulse X coordinate
Reference location of Segment A Right STIM pulse Y coordinate

STIMB0LX
STIMB0LY
STIMB0RX
STIMB0RY

Reference location of Segment B Left STIM pulse X coordinate
Reference location of Segment B Left STIM pulse Y coordinate
Reference location of Segment B Right STIM pulse X coordinate
Reference location of Segment B Right STIM pulse Y coordinate

STIMASLX
STIMASLY
STIMASRX
STIMASRY

RMS width of Segment A Left STIM pulse X coordinate
RMS width of Segment A Left STIM pulse Y coordinate
RMS width of Segment A Right STIM pulse X coordinate
RMS width of Segment A Right STIM pulse Y coordinate

STIMBSLX
STIMBSLY
STIMBSRX
STIMBSRY

RMS width of Segment B Left STIM pulse X coordinate
RMS width of Segment B Left STIM pulse Y coordinate
RMS width of Segment B Right STIM pulse X coordinate
RMS width of Segment B Right STIM pulse Y coordinate

Pulse Height Parameters (in Extension header 1 or greater for FUV data only)
PHALOWRA PHALOWRB

Pulse height screening lower limit for segment A
Pulse height screening lower limit for segment B

PHAUPPRA PHAUPPRB

Pulse height screening upper limit for segment A
Pulse height screening upper limit for segment B

Image Statistics and Data Quality Flags (in Extension header 1 or greater)
NGOODPIX
Number of good pixels (NUV)
NGOOD_A
Number of good pixels (FUV, segment A)
NGOOD_B

Number of good pixels (FUV, segment B)

SDQFLAGS

Serious data quality flags. (Can be modified as a calcos parameter; see Section 3.4.22)

GOODMAX
Maximum value of good pixels (NUV)
GOODMAXA

Maximum value of good pixels (FUV, segment A)

GOODMAXB
Maximum value of good pixels (FUV, segment B)
GOODMEAN
Mean value of good pixels (NUV)
GOODMN_A
Mean value of good pixels (FUV, segment A)
GOODMN_B
Mean value of good pixels (FUV, segment B)
SOFTERRS
Number of soft error pixels (DQF=1)

Deadtime Correction Keywords (in Extension header 1 or greater)

DEADRT
DEADRT_A
DEADRT_B

Count rate used for the NUV dead time correction (cps)
Count rate used in the FUV Segment A dead time correction (cps)
Count rate used in the FUV Segment B dead time correction (cps)

DEADMT
DEADMT_A
DEADMT_B

NUV Deadtime correction method (DATA, DEVENTS, or MEVENTS)
FUVA Deadtime correction method (DATA, DEVENTS, or MEVENTS)
FUVB Deadtime correction method (DATA, DEVENTS, or MEVENTS)

TIME-TAG Events Orientation Keywords (in Extension header 1 or greater)2
TCTYP2
TCTYP3

Axis type for dimension 1
Axis type for dimension 2

TCRVL2
TCRVL3

Sky coordinates of 1st axis
Sky coordinate of 2nd axis

TCDLT2
TCDLT3

Axis 1 degrees per pixels
Axis 2 degrees per pixels

TCRPX2
TCRPX3

Axis 1 pixel of tangent plane direction
Axis 2 pixel of tangent plane direction

TALEN2
TALEN3

Length of axis 1
Length of axis 2

TC2_2
TC2_3
TC3_2
TC3_3

Partial of first axis coordinate with respect to x
Partial of first axis coordinate with respect to y
Partial of second axis coordinate with respect to x
Partial of second axis coordinate with respect to y

TCUNI2
TCUNI3

Units of first coordinate value

Units of second coordinate value

World Coordinate System and Related Parameters (in Extension header 1 or greater)
WCSAXES
Number of World Coordinate System axes
CRPIX1
CRPIX2

x-coordinate of reference pixel

y-coordinate of reference pixel

CRVAL1
CRVAL2

First axis value at reference pixel
Second axis value at reference pixel

CTYPE1
CTYPE2

The coordinate type for the first axis

The coordinate type for the second axis

CD1_1
CD1_2
CD2_1
CD2_2

Partial of first axis coordinate with respect to x
Partial of first axis coordinate with respect to y
Partial of second axis coordinate with respect to x
Partial of second axis coordinate with respect to y

CUNIT1
CUNIT2

Units of first coordinate value
Units of second coordinate value

LTV1
LTV2

Offset in X to subsection start
Offset in Y to subsection start

LTM1_1
LTM2_2

Reciprocal of sampling rate in X
Reciprocal of sampling rate in Y

Detector Voltages (in Extension header 1 or greater)
HVLEVELA

Actual segment A commanded HV level (counts)

HVLEVELB
Actual segment B commanded HV level (counts)

1 For FUV data subarrays 0–3 refer to segment A, and subarrays 4–7 refer to segment B.
2 The values for these keywords are currently deleted from the output files except for NUV Imaging.



EXPTYPE

EXTERNAL/SCI
EXTERNAL/CAL

WAVECALDARKFLAT
DETECTORFUVNUVFUVNUVFUVNUVFUVNUV
OBSMODETIME-TAGACCUMTIME-TAGACCUMTIME-TAGTIME-TAGTIME-TAGTIME-TAGTIME-TAGTIME-TAG

Module

BRSTCORR

Omit

N/A

N/A

N/A

Omit1

N/A

Omit1

N/A

Omit2

N/A

BADTCORR

Perform

N/A

Perform

N/A

Perform

Perform

Perform

Perform

Perform

Perform

PHACORR

Perform

Perform

N/A

N/A

Perform

N/A

Perform

N/A

Perform

N/A

RANDCORR

Perform

Perform

N/A

N/A

Perform

N/A

Perform

N/A

Perform

N/A

RANDSEED

–1

–1

N/A

N/A

–1

N/A

–1

N/A

–1

N/A

XWLKCORR2

Perform

Perform

N/A

N/A

Perform

N/A

Perform

N/A

Perform

N/A

YWLKCORR

Perform

Perform

N/A

N/A

Perform

Perform

Perform

N/A

Perform

N/A

TEMPCORR

Perform

Perform

N/A

N/A

Perform

N/A

Perform

N/A

Perform

N/A

GEOCORR

Perform

Perform

N/A

N/A

Perform

N/A

Perform

N/A

Perform

N/A

DGEOCORR

Perform

Perform

N/A

N/A

Perform

N/A

Perform

N/A

Perform

N/A

IGEOCORR

Perform

Perform

N/A

N/A

Perform

N/A

Perform

N/A

Perform

N/A

DOPPCORR

Perform

Perform

Perform

Perform

N/A

N/A

N/A

N/A

N/A

N/A

DEADCORR

Perform

Perform

Perform

Perform

Perform

Perform

Perform

Perform

Perform

Perform

FLATCORR

Perform

Perform

Perform

Perform

Perform

Perform

Omit

Omit

Omit

Omit

XTRACTALG1

TWOZONE

TWOZONE

BOXCAR

BOXCAR

BOXCAR

BOXCAR

BOXCAR

BOXCAR

BOXCAR

BOXCAR

ALGNCORR1

Perform

Perform

Omit

Omit

Omit

Omit

Omit

Omit

Omit

Omit

DQICORR

Perform

Perform

Perform

Perform

Perform

Perform

Perform

Perform

Perform

Perform

WAVECORR

Perform

Perform

Perform

Perform

Perform

Perform

Omit

Omit

Omit

Omit

X1DCORR

Perform

Perform

Perform

Perform

Perform

Perform

Omit

Omit

Omit

Omit

BACKCORR

Perform

Perform

Perform

Perform

Perform

Perform

Omit

Omit

Omit

Omit

FLUXCORR

Perform

Perform

Perform

Perform

N/A

N/A

Omit

Omit

Omit

Omit

TDSCORR

Perform

Perform

Perform

Perform

N/A

N/A

Omit

Omit

Omit

Omit

HELCORR

Perform

Perform

Perform

Perform

N/A

N/A

Omit

Omit

Omit

Omit

TRCECORR1

Perform

Perform

Omit

Omit

Omit

Omit

Omit

Omit

Omit

Omit

STATFLAG

T

T

T

T

T

T

T

T

T

T


1 FUV data taken at LP1 and LP2 will still use BOXCAR extraction. ALGNCORR and TRCECORR will be set to OMIT.

2 XWLKCORR and DGEOCORR are lifetime dependent, and are set to OMIT as of April 2018. They will be set to PERFORM as marked in the table with the release of new reference files planned for the end of 2018.

Table 2.16: Imaging Calibration Switch Keywords

EXPTYPE

EXTERNAL/SCI
EXTERNAL/CAL

WAVECAL

DARK

FLAT

ACQ/IMAGE

DETECTORNUVNUVNUVNUVNUV
OBSMODETIME-TAGACCUMTIME-TAGTIME-TAGTIME-TAGACCUM

Modules







BADTCORR

Perform

N/A

Perform

Perform

Perform

N/A

FLATCORR

Perform

Perform

Perform

Omit

Omit

Perform

DEADCORR

Perform

Perform

Perform

Perform

Perform

Perform

DQICORR

Perform

Perform

Perform

Perform

Perform

Perform

PHOTCORR

Perform

Perform

Perform

Omit

Omit

Perform

TDSCORR

Perform

Perform

Perform

Omit

Omit

Perform

STATFLAG

T

T

T

T

T

T


Table 2.17: Reference File Keywords

Reference File

Description

BRSTTAB

Burst parameter table

BRFTAB

Baseline reference frame reference table

BADTTAB

Bad time interval reference table

PHATAB

Pulse height discrimination reference table

GEOFILE

Geometric distortion table

DGEOFILE

Delta Geometric Correction Reference File

YWLKFILE

Y Walk Correction Lookup Reference Image

XWLKFILE

X Walk Correction Lookup Reference Image

DEADTAB

Deadtime reference file

FLATFILE

Pixel to pixel flat-field reference file

LAMPTAB

Template calibration lamp spectra table

WCPTAB

Wavecal parameters table

DISPTAB

Dispersion coefficient reference table

BPIXTAB

Bad pixel table

GSAGTAB

Gain sag table

XTRACTAB

1-D spectral extraction information table

FLUXTAB

Photometric throughput table

TDSTAB

Time-dependent sensitivity correction table

SPWCSTAB

Spectroscopic World Coordinate System table

TRACETAB

1-D spectral trace table

PROFTAB

2-D spectrum profile table

HVTAB

High voltage command level reference table

SPOTTAB

Hot spot reference table

TWOZXTAB

Two-zone spectral extraction information table