Part II: STIS Data Handbook

2.4 Headers, Keywords, and Relationship to Phase II

---

As with previous HST instruments, the FITS header keywords in STIS 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), or character string. Many are HST and STIS 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 either infostis, catfits, imhead, hselect or hedit, 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 filter.
• Readout definition parameters such as binning, gain, and 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 easiest way to quickly identify the observational parameters of a given dataset is to run the task infostis (see Figure 2.5), which prints selected header information for STIS FITS images. Wildcard characters (*raw.fits) or a file list (@fitslist) may be used for input.

 
Figure 2.5: Using infostis to Display Header Keywords

cl> infostis o3xi03a1q_raw.fits --------------------------------------------------------------------------- S T I S --------------------------------------------------------------------------- Rootname: O3XI03A1Q Detector: CCD Proposal ID: 7071 Obs Type: IMAGING Exposure ID: 3.031 Obs Mode: ACQ Lamp: NONE Target Name: GD153-1 Aperture: F28X50LP Right Ascension: 12:57:02.3 Filter: Long_Pass Declination: +22:01:53.2 Opt Element: MIRVIS Equinox: 2000.0 CCD amp: D Gain: 4 Axis 1 binning: 1 CR-split: 1 Axis 2 binning: 1 Subarray: yes Total Exp. Time: 0.7 sec Number of imsets: 3

 

 

STIS takes CCD and MAMA spectroscopic and imaging data, as well as acquisitions and ACQ/peakups. The keywords relevant for one of these data types will not necessarily be relevant to another. Accordingly, you will find that the header on your particular file contains a unique combination of keywords appropriate for your 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 STIS file types:

http://www.dpt.stsci.edu/keyword.

Keywords that deal with a particular topic, such as the instrument configuration, are grouped together logically throughout the headers. Table 2.5 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.6 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 populated with values of OMIT, COMPLETE, or PERFORM. Similarly, Table 2.7 summarizes the reference file group of keywords that identify the files used by the pipeline during calibration (see Chapter 3 for a detailed description of pipeline processing).

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

Header Keyword	Phase II Equivalent	Description
NEXTEND		Number of image extensions in the file.
Target Information (Primary Header)
TARGNAME	Target_Name	Name of target.
RA_TARG DEC_TARG	RA DEC	Right ascension of the target (deg) (J2000). Declination of the target (deg) (J2000).
PROPOSID		4 or 5 digit proposal number.
LINENUM	Visit_Number, Exposure_Number	Indicates the visit and exposure number from the Phase II proposal: Visit_Number.Exposure_Number.
Summary Exposure Information (Primary Header)
TDATEOBS		UT date of start of first exposure in file (a character string, yyyy-mm-dd).
TTIMEOBS		UT start time of first exposure in file (a character string, hh:mm:ss).
TEXPSTRT		Start time (MJD) of first exposure in file (a real number).
TEXPEND		End time (MJD) of last exposure in the file (a real number).
TEXPTIME	Number_of_Iterations × Time_per_Exposure	Total of science exposure times in an association.
Science Instrument Configuration (Primary Header)
OBSTYPE		Observation type (IMAGING or SPECTROSCOPIC).
OBSMODE	Opmode	Operating mode (ACQ, ACQ/PEAK, ACCUM, TIME-TAG).
DETECTOR	Config	Detector in use (NUV-MAMA, FUV-MAMA, or CCD).
OPT_ELEM	Sp_Element	Optical element in use (grating name or mirror).
CENWAVE	Wavelength	Central wavelength for grating settings.
APERTURE	Aperture	Aperture name.
PROPAPER	Aperture	Proposed aperture name.
FILTER	Aperture	Filter in use.
APER_FOV		Aperture field of view.
PLATESC		Nominal plate scale (arcsec/pixel); see Section 3.4.14.
SCLAMP		Lamp status (NONE or name of lamp which is on).
LAMPSET		Spectral cal lamp current value (milliamps).
NRPTEXP	Number_of_Iterations	Number of repeat exposures in dataset (for MAMA data only): Default = 1. ASN_MTYP=REPEATOBS.
SUBARRAY		Data from a subarray (T) or full frame (F).
CRSPLIT	CR-SPLIT (optional parameter)	Number of split exposures for cosmic ray removal in CCD data. ASN_MTYP=CRSPLIT.
TARGNAME	WAVECAL=NO & Target_Name = WAVELINE or Target_Name = WAVEHITM	Turn off automated wavecal exposures. Note: This is not a default or recommended setting and is listed here for informational purposes only.
Readout Definition Parameters
SIZAXIS1	SIZEAXIS1	Subarray axis 1 size in unbinned detector pixels.
SIZAXIS2	SIZEAXIS2	Subarray axis 2 size in unbinned detector pixels.
BINAXIS1	BINAXIS1	Axis 1 data bin size in unbinned detector pixels.
BINAXIS2	BINAXIS2	Axis 2 data bin size in unbinned detector pixels.
Engineering Parameters
CCDAMP	AMP (optional engineering parameter)	CCD amplifier read out (A, B, C, D).
CCDGAIN	GAIN (optional parameter)	Commanded gain of CCD.
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).
PA_APER		Position angle of reference aperture.
ORIENTAT		Position angle of image y-axis.
CRPIX1, CRPIX2		X and Y coordinates of reference pixel.
DGESTAR		Dominant guide star ID // FGS ID (F1,F2,F3); (_spt file) e.g., DGESTAR = 0087900462F3.
EXPTIME	Time_per_Exposure/CR-SPLIT or Time_per_Exposure (if not CR-SPLIT)	Exposure time of an individual exposure in a CR-SPLIT or REPEATOBS series, in seconds (a real number).
EXPSTART		Exposure start time (Modified Julian Date).
EXPEND		Exposure end time (Modified Julian Date).

 
Table 2.6: Calibration Switch Keywords

Header Keywords		Explanation	Spectra	Images	CCD	MAMA
Calibration Switch	Reference File
ATODCORR	ATODTAB	A-to-D correction	·	·	·
BACKCORR	ADDSTAB	Subtract spectral background	·		·	·
BIASCORR	BIASFILE	Bias image (structure) correction	·	·	·
BLEVCORR	N/A	Correct for CCD bias level (trim overscan)	·	·	·
CRCORR	CRREJTAB	Cosmic ray subtraction	·	·	·
CTECORR	CCDTAB	Correct flux for CTE losses	·		·
DARKCORR	DARKFILE	Dark image correction	·	·	·	·
	CCDTAB	CCD Parameters	·	·	·	·
DISPCORR	DISPTAB	Apply dispersion solution	·		·	·
	INANGTAB	Incident angle correction	·		·	·
	MOFFTAB	MAMA offset correction	·			·
DOPPCORR	N/A	Doppler correction	·			·
DQICORR	BPIXTAB	Initialize data quality image	·	·	·	·
EXPSCORR	N/A	Process individual observations after CRCORR	·	·	·
FLATCORR	LFLTFILE	Flat field corrections	·	·		·
	PFLTFILE	Pixel-to-pixel flat
	DFLTFILE	(Not done)
FLUXCORR	APERTAB	Convert to absolute flux	·		·	·
	PCTAB	Photometry correction
	PHOTTAB	Photometric conversion
	TDSTAB	Time dependent sensitivity correction
GEOCORR	IDCTAB	Geometric correction		·	·	·
GLINCORR	MLINTAB	Global detector non-linearities	·	·		·
HELCORR	N/A	Convert to heliocentric wavelengths	·		·	·
LFLGCORR	HLINTAB	Flag pixels for local and global non-linearities	·	·		·
LORSCORR	N/A	Convert MAMA image to low-res	·	·		·
PHOTCORR	PHOTTAB	Populate header photometric keywords		·	·	·
	APERTAB	Aperture throughput		·	·	·
	CCDTAB	CCD parameters		·	·	·
	TDSTAB	Time dependent sensitivity correction		·	·	·
RPTCORR	N/A	Add individual repeat observations	·	·		·
SC2DCORR	CDSTAB	2-D scattered light correction	·			·
	ECHSCTAB	Echelle scattering
	EXSTAB	Echelle cross-dispersion scattering
	RIPTAB	Echelle ripple
	HALOTAB	Detector halo
	TELTAB	Telescope point spread function
	SRWTAB	Scattering reference wavelengths
SGEOCORR	SDSTFILE	Small-scale distortion correction (not done)	·	·		·
SHADCORR	SHADFILE	Shutter shading correction (not done)	·	·	·
STATFLAG	N/A	Calculate image statistics	·	·	·	·
WAVECORR	WAVECAL	Use wavecal to adjust wavelength zero point	·		·	·
	LAMPTAB	Template calibration lamp spectra
	APDESTAB	Aperture descriptions
X1DCORR	SPTRCTAB	Extract 1-D spectrum	·		·	·
	XTRACTAB	1-D extraction parameters	·		·	·
	GACTAB	Grating-aperture correction	·		·
X2DCORR	SDCTAB	Rectify 2-D spectral image	·		·	·
	APDESTAB	Aperture descriptions
	SPTRCTAB	1-D spectrum trace

 
Table 2.7: Reference File Keywords

Header Keyword	File Suffix	Format	Explanation	Spectra	Images	CCD	MAMA
APDESTAB	_apd	Table	Aperture descriptions	·		·	·
APERTAB	_apt	Table	Aperture throughput	·	·	·	·
ATODTAB	_a2d	Table	A-to-D correction	·	·	·
BIASFILE	_bia	Image	Bias (structure)	·	·	·
BPIXTAB	_bpx	Table	Bad pixel	·	·	·	·
CCDTAB	_ccd	Table	CCD parameters	·	·	·
CDSTAB	_cds	Table	Cross-disperser scattering	·			·
CRREJTAB	_crr	Table	Cosmic ray rejection parameters	·	·	·
DARKFILE	_drk	Image	Dark current	·	·	·	·
DFLTFILE	_dfl	Image	Delta-flat (not available)	·	·	·	·
DISPTAB	_dsp	Table	Dispersion coefficients	·		·	·
ECHSCTAB	_ech	Table	Echelle scattering	·			·
EXSTAB	_exs	Table	Echelle cross-dispersion scattering	·			·
GACTAB	_gac	Table	Grating-aperture correction	·		·
HALOTAB	_hal	Table	Detector halo	·			·
IDCTAB	_idc	Table	Image distortion correction		·	·	·
INANGTAB	_iac	Table	Incident angle correction	·		·	·
LAMPTAB	_lmp	Table	Template CAL lamp spectra	·		·	·
LFLTFILE	_lfl	Image	Low-order flat	·	·	·	·
MLINTAB	_lin	Table	Flux linearity	·	·		·
MOFFTAB	_moc	Table	MAMA offset correction	·			·
PCTAB	_pct	Table	Photometry correction	·		·	·
PFLTFILE	_pfl	Image	Pixel-to-pixel flat	·	·	·	·
PHOTTAB	_pht	Table	Photometric conversion	·	·	·	·
RIPTAB	_rip	Table	Echelle ripple	·	·		·
SDCTAB	_sdc	Table	2-D spectrum distortion correction	·		·	·
SDSTFILE	_ssd	Image	Small-scale distortion correction (not available)	·	·		·
SHADFILE	_ssc	Image	Shutter shading correction (not available)	·	·	·
SPTRCTAB	_1dt	Table	1-D spectrum trace	·		·	·
SRWTAB	_srw	Table	Scattering reference wavelengths	·			·
TDCTAB	_tdc	Table	NUV dark correction	·	·		·
TDSTAB	_tds	Table	Time dependent sensitivity correction	·	·	·	·
TELTAB	_tel	Table	Telescope point spread function	·			·
WAVECAL	_wav	Image	Wavelength calibration	·		·	·
WCPTAB	_wcp	Table	Wavecal parameters	·		·	·
XTRACTAB	_1dx	Table	1-D extraction parameters	·		·	·