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 stenv 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.16 (spectroscopy) and Table 2.17 (imaging) summarize the possible calibration switch keywords and indicate whether they are present for particular observations; Table 2.18 indicates reference file keywords corresponding to particular calibration steps. 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, depending on lifetime position (LP)). After each calibration step is executed in the COS calibration pipeline, calcos will set the keyword switch to COMPLETE
.
Table 2.15: Selected Header Keywords and Relationship to Phase II Parameters.
Header Keyword | Phase II Equivalent | Description |
---|---|---|
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 | |
| PI Last Name | Last name of principal investigator |
LINENUM | Visit_Number, Exposure_Number | Indicates the visit and exposure number from the Phase II proposal: Visit_Number, Exposure_Number |
Target Information (Primary Header) | ||
TARGNAME | TargetName | Name of target |
RA_TARG | RA DEC | Right ascension of the target (deg) (J2000) Declination of the target (deg) (J2000) |
POSTARG1 | POSTARG POSTARG | Postarg in axis 1 direction Postarg in axis 2 direction |
Science Instrument Configuration (Primary Header) | ||
OBSTYPE | Observation type (IMAGING or SPECTROSCOPIC ) | |
OBSMODE | Opmode | Operating mode (ACCUM , TIME-TAG ) |
EXPTYPE | Opmode | Exposure type (EXTERNAL /SCI , WAVECAL , PHA , DARK , FLAT , ACQ /IMAGE , ACQ /SEARCH , ACQ /PEAKD , ACQ /PEAKXD , ENG DIAG , or MEM DUMP ) |
DETECTOR | Config | Detector in use (NUV or FUV ) |
SEGMENT | SEGMENT | FUV 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_ADJ | LIFETIME-POS | Detector life time adjustment position |
OPT_ELEM | SpElement | Optical element in use (grating or mirror name) |
CENWAVE | Wavelength | Central wavelength for grating settings |
APERTURE | Aperture | Aperture name |
PROPAPER | Aperture | Proposed aperture name |
APER_FOV | Aperture field of view description in mm | |
APMPOS | Aperture Mechanism Position from telemetry | |
APERXPOS | Aperture Block Pos. cross dispersion (telemetry) | |
FPPOS | FPPOS | Grating offset index (1–4) for spectrum dithers (FPPOS ) |
TAGFLASH | FLASH | Type of flashed exposures in TIME-TAG (NONE , AUTO , or UNIFORMLY -SPACED ) |
EXTENDED | Extended | Is the target extended (Yes or No ) |
NRPTEXP | NumberOfIterations | Number 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) | |
PLANTIME | TimePerExposure | Planned 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 | |
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) | ||
BUFFTIME | BUFFER-TIME | Onboard 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 | Time lost to bursts on FUV segment A (seconds) | |
TBADT_A | Time lost to BADTCORR screening on FUV segment A (sec) | |
NPHA_A | 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 | Number of events lost due to burst screening on segment A | |
NBADT_A | Number of events flagged by BADTCORR for segment A | |
NOUT_A | Number of events outside the active area for segment A | |
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 | Segment A Left STIM pulse X centroid in raw data | |
STIMB_LX | Segment B Left STIM pulse X centroid in raw data | |
STIMA0LX | Reference location of Segment A Left STIM pulse X coordinate | |
STIMB0LX | Reference location of Segment B Left STIM pulse X coordinate | |
STIMASLX | RMS width of Segment A Left STIM pulse X coordinate | |
STIMBSLX | RMS width of Segment B Left STIM pulse X coordinate | |
Pulse Height Parameters (in Extension header 1 or greater for FUV data only) | ||
PHALOWRA PHALOWRB | Pulse height screening lower limit for segment A | |
PHAUPPRA PHAUPPRB | Pulse height screening upper limit for segment A | |
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 | Count rate used for the NUV dead time correction (cps) | |
DEADMT | NUV Deadtime correction method ( | |
TIME-TAG Events Orientation Keywords (in Extension header 1 or greater)2 | ||
TCTYP2 | Axis type for dimension 1 | |
TCRVL2 | Sky coordinates of 1st axis | |
TCDLT2 | Axis 1 degrees per pixels | |
TCRPX2 | Axis 1 pixel of tangent plane direction | |
TALEN2 | Length of axis 1 | |
TC2_2 | Partial of first axis coordinate with respect to x | |
TCUNI2 | 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 | x-coordinate of reference pixel y-coordinate of reference pixel | |
CRVAL1 | First axis value at reference pixel | |
CTYPE1 | The coordinate type for the first axis The coordinate type for the second axis | |
CD1_1 | Partial of first axis coordinate with respect to x | |
CUNIT1 | Units of first coordinate value | |
LTV1 | Offset in X to subsection start | |
LTM1_1 | Reciprocal of sampling rate in X | |
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.
Table 2.16: Spectroscopic Calibration Switch Keywords.
EXPTYPE | EXTERNAL/SCI | WAVECAL | DARK | FLAT | ||||||
DETECTOR | FUV | NUV | FUV | NUV | FUV | NUV | FUV | NUV | ||
OBSMODE | TIME-TAG | ACCUM | TIME-TAG | ACCUM | TIME-TAG | TIME-TAG | TIME-TAG | TIME-TAG | TIME-TAG | TIME-TAG |
Module | ||||||||||
| Omit | N/A | N/A | N/A | Omit1 | N/A | Omit1 | N/A | Omit2 | N/A |
| Perform | N/A | Perform | N/A | Perform | Perform | Perform | Perform | Perform | Perform |
| Perform | Perform | N/A | N/A | Perform | N/A | Perform | N/A | Perform | N/A |
| Perform | Perform | N/A | N/A | Perform | N/A | Perform | N/A | Perform | N/A |
| –1 | –1 | N/A | N/A | –1 | N/A | –1 | N/A | –1 | N/A |
| Omit | N/A | N/A | N/A | Perform | N/A | Perform | N/A | Perform | N/A |
| Perform | N/A | N/A | N/A | Perform | Perform | Perform | N/A | Perform | N/A |
| Perform | Perform | N/A | N/A | Perform | N/A | Perform | N/A | Perform | N/A |
| Perform | Perform | N/A | N/A | Perform | N/A | Perform | N/A | Perform | N/A |
| Perform | Perform | N/A | N/A | Perform | N/A | Perform | N/A | Perform | N/A |
| Perform | Perform | N/A | N/A | Perform | N/A | Perform | N/A | Perform | N/A |
| Perform | Perform | Perform | Perform | N/A | N/A | N/A | N/A | N/A | N/A |
| Perform | Perform | Perform | Perform | Perform | Perform | Perform | Perform | Perform | Perform |
| Perform | Perform | Perform | Perform | Perform | Perform | Omit | Omit | Omit | Omit |
| TWOZONE | TWOZONE | BOXCAR | BOXCAR | BOXCAR | BOXCAR | BOXCAR | BOXCAR | BOXCAR | BOXCAR |
| Perform | Perform | Omit | Omit | Omit | Omit | Omit | Omit | Omit | Omit |
| Perform | Perform | Perform | Perform | Perform | Perform | Perform | Perform | Perform | Perform |
| Perform | Perform | Perform | Perform | Perform | Perform | Omit | Omit | Omit | Omit |
| Perform | Perform | Perform | Perform | Perform | Perform | Omit | Omit | Omit | Omit |
| Perform | Perform | Perform | Perform | Perform | Perform | Omit | Omit | Omit | Omit |
| Perform | Perform | Perform | Perform | N/A | N/A | Omit | Omit | Omit | Omit |
| Perform | Perform | Perform | Perform | N/A | N/A | Omit | Omit | Omit | Omit |
| Perform | Perform | Perform | Perform | N/A | N/A | Omit | Omit | Omit | Omit |
| Perform | Perform | Omit | Omit | Omit | Omit | Omit | Omit | Omit | Omit |
| 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 is OMIT for LP=4 and PERFORM for all other LPs. DGEOCORR is PERFORM for LP=4 and OMIT for all other LPs.
Table 2.17: Imaging Calibration Switch Keywords.
EXPTYPE | EXTERNAL/SCI | WAVECAL | DARK | FLAT | ACQ/IMAGE | |
DETECTOR | NUV | NUV | NUV | NUV | NUV | |
OBSMODE | TIME-TAG | ACCUM | TIME-TAG | TIME-TAG | TIME-TAG | ACCUM |
Modules | ||||||
| Perform | N/A | Perform | Perform | Perform | N/A |
| Perform | Perform | Perform | Omit | Omit | Perform |
| Perform | Perform | Perform | Perform | Perform | Perform |
| Perform | Perform | Perform | Perform | Perform | Perform |
| Perform | Perform | Perform | Omit | Omit | Perform |
| Perform | Perform | Perform | Omit | Omit | Perform |
| T | T | T | T | T | T |
Table 2.18: Reference File Keywords.
Note that some reference files depend on LP (lifetime position), cenwave, etc. See https://hst-crds.stsci.edu/.
Note also that reference file names in italic bold (e.g., BRSTTAB) apply only to FUV data.
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 |