4 Keyword Description

This chapter describes keywords used by ESO in FITS headers, log files and other data products. The main purpose here is to provide the overall structure of the keywords and their value/usage conventions. The precise specification for each keyword is given in separate data dictionaries (see section 8 ).

Some of the keywords will be used only in headers, some in headers and setup files and again some other only in log files. The specification of where a keyword is included is given through the data dictionaries (see section 8.3 ).

4.1 Primary FITS keywords

The FITS format, header syntax and standard keywords are described in [1] . In addition to the FITS standard keywords, ESO uses a set of primary keywords in its data products headers. Such keywords, although not belonging to the official FITS standard are widely used by the community. ESO follows for these keywords common conventions for value formats and units.

Primary keywords are set by any one of the subsystems listed in the categories described in section 4.3 . Tables [1] – [] [5] list the primary keywords used by ESO. They are grouped by the subsystems that sets them.

Keyword values can be either decimal integers , doubles (notations allowed: 1. , 1.0 , 1.E+00 ), strings (enclosed within quotes i.e. `string' ) or booleans in which case the value can be either T (true) or F (false).

The ESO usage conventions for primary FITS keywords are summarized below.

TABLE 1 Primary FITS keywords set by the DET subsystem
	Keyword	Example	Explanation
(L)	`SIMPLE`	`T`	Standard FITS format (NOST-100.0)
(I)	`BITPIX`	`16`	# bits storing pix values
(I)	`NAXIS`	`2`	# of axes in frame
(I)	`NAXIS1`	`1124`	# of pixels/row
(I)	`NAXIS2`	`520`	# of rows (also # of scan lines)
(R)	`BZERO`	`32768.`	real = fits-value*`BSCALE` + `BZERO`
(R)	`BSCALE`	`1.`	real = fits-value*`BSCALE` + `BZERO`
(I)	`BLANK`	`32767`	Value used for NULL pixels
(S)	`DATE`	`1995-03-24T10:10:25'	Date the file was written
(S)	`DATE-OBS`	`1995-03-24T09:55:22'	Date the exposure was started (UTC)
(R)	`MJD-OBS`	`49800.41345000`	Exp start `1995-03-24T09:55:22.000` (UTC)
(S)	`ORIGIN`	`ESO-LASILLA'	Observatory
(R)	`EXPTIME`	`900.000`	Total integration time (s)

DATE gives the UTC date in which the FITS file was created. The value string for date uses the ISO 8601 format (YYYY-MM-DDThh:mm:ss ).
MJD-OBS is the modified Julian Date ( JD - 2400000.5 ) of the start of the observation. Two resolutions will be supported depending on the capabilities of the instrument: seconds and milliseconds. Five decimals are required for an accuracy of one second and 8 decimals for one millisecond. The reference frame for MJD-OBS at ESO is UTC and is given as known to the detector control system local control unit (LCU). The time on the LCU is synchronized with the observatory time system via the Network Time Protocol (ntp ).
DATE-OBS gives the UTC date in which the exposure was started. The value string for date uses the ISO 8601 format (YYYY-MM-DDThh:mm:ss ). This keyword repeats the value of MJD-OBS and is included mainly for human readability.
BZERO and BSCALE give respectively offset and scale factor for data pixels when required. These keywords are only used when unsigned 16-bit integer data (BITPIX=16 ) is transferred in which BZERO=32768 is specified.
ORIGIN specifies the observatory where the file was generated. ESO usage is either `ESO-LASILLA' or `ESO-PARANAL' for acquisition data. `ESO-GARCHING' shall be used for simulation data.
EXPTIME provides the total integration time in seconds; it may have decimals. When the exposure is made of several periods, EXPTIME time is the sum of the exposure periods, and not simply the difference between end and start of exposure. Subintegrations, i.e. multiple exposures before a readout of the detector are described by the DIT and NDIT , see section 4.11 .: UTC and LST give the time in seconds ellapsed since midnight of the start of the exposure as known to TCS. The time on TCS is synchronized with the observatory time system via a dedicated time module. In principle, UTC and LST should correspond, within a second accuracy, to the UTC time given by the detector control LCU in MJD-OBS . In praxis, MJD-OBS , UTC and LST provide for a redundant consistency check mechanism in case of malfunction.
RA and DEC report the telescope pointing in mean places of equinox given in EQUINOX . For the VLT this is always J2000. RA is given in degrees without applying any cosd factor.

RADECSYS gives the frame of reference for the equatorial coordinate system. ESO uses FK5 for mean place coordinates new (post-IAU 1976) system.

TELESCOP provides a standard designation of ESO telescopes.

TABLE 3 Usage of the `TELESCOP` keyword at ESO
Value for `TELESCOPE`	Telescope
`ESO-NTT`	ESO 3.5m New Technology Telescope
`ESO-3.6`	ESO 3.6m Telescope
`MPI-2.2`	MPI 2.2m Telescope
`ESO-1.5`	ESO 1.5m Telescope
`DK-1.5`	Danish 1.5m Telescope
`NL-0.9`	Dutch 90cm Telescope
`ESO-CAT`	ESO coudé 1.4 Auxiliary Telescope
`ESO-1.0`	ESO 1.0m Telescope
`ESO-VLT-Ui`	ESO VLT, Unit telescope i
`ESO-VLT-Uijkl`	ESO VLT, incoherent combination of Unit Telescopes i, j,k and l
`ESO-VLTI-Uijkl`	ESO VLT, coherent combination of Unit Telescopes i, j,k and l
`ESO-VLT-Amnopqrst`	ESO VLT, coherent combination of Auxiliary Telescopes mnopqrst
`ESO-VLT-Uijkl-Amnop`	ESO VLT, coherent combination of Telescopes U`ijkl` and A`mnop`

INSTRUME provides a designation of the instrument used. The complete identification of the instrument is described in the Instrument category (see section 4.10 ); the instrument mode used, when several observing modes are available, is also to be found in this category.

OBSERVER The observer's initials followed by his/her surname.

guideline-6: The observer name is `SERVICE' when service observing is conducted.

PI-COI The PI or Co-I's initials followed by his/her surname.

guideline-7: The primary keyword PI-COI repeats the value of OBS PI-COI NAME

COMMENT reports any comments associated with this frame (see section 5.1 ).
OBJECT is either the target designation, as given by the astronomer, for science exposures or the exposure type for non-science frames.

guideline-8: This keyword contains the value of OBS TARG NAME for science exposures and the value of DPR TYPE for all other exposures.

TABLE 5 FITS primary keywords set by the On-line Archive subsystem
	Keyword	Example	Explanation
(S)	`ORIGFILE`	`SCTO2_3.fits'	Original file name
(S)	`ARCFILE`	`SUSI.1997-03-12T03:44:35.212.fits'	DFS file name
(S)	`CHECKSUM`	`qmmnbj89787AA44d'	ASCII 1's complement checksum
(S)	`CHECKVER`	`COMPLEMENT'	Checksum algorithm

ORIGFILE and ARCFILE provide the means for Data Flow Operations to trace back FITS files as the flow through the system.
CHECKSUM provides a Cyclic Redundant Check (CRC) calculation of the complete file or of the data records respectively. It uses the ASCII encoded 1's complement algorithm. CHECKVER gives the algorithm used; for the ESO VLT its value is always `COMPLEMENT' . The source code for a C function to compute the CHECKSUM of a frame is available at http://arch-http.hq.eso.org/DICB/checksum

4.2 Coordinate system keywords

The keywords CRPIXn , CDELTn , CRVALn and CTYPEn give the coordinate system frame on which the data pixels are to be interpreted. Raw frames obtained with the VLT include keywords describing the detector coordinate system. Their usage is shown in table 6 and explained below.

Note that coordinates in FITS frames refer to the center of pixels, i.e. pixel 1 would integrate flux between 0.5 and 1.5 if the chip had uniform sensitivity.

TABLE 6 Usage of coordinate system keywords for raw frames
	Keyword	Example	Explanation
(R)	`CRVAL1`	`1020.`	X Ref. pixel of center of rotation
(R)	`CRVAL2`	`1025.`	Y Ref. pixel of center of rotation
(R)	`CRPIX1`	`315.`	Value of X ref pixel
(R)	`CRPIX2`	`325.`	Value of Y ref pixel
(R)	`CDELT1`	`1.`	Binning factor along X
(R)	`CDELT2`	`1.`	Binning factor along Y
(S)	`CTYPE1`	`PIXEL'	Pixel coordinate system
(S)	`CTYPE2`	`PIXEL'	Pixel coordinate system

CRVALn give the reference pixel of the full detector matrix.

guideline-9: The reference pixel is defined as the pixel (possibly with fraction if the accuracy is achieved) through which the center of rotation of the adapter intersects the detector.

CRPIXn give the position of the reference pixel of the detector matrix (CRVALn ) relative to the coordinate frame of the readout window. The following picture illustrates the use of CRVALn and CRPIXn for a window readout:

when the complete detector is readout CRPIX1 /CRPIX2 are equal to CRVAL1 /CRVAL2 , i.e. 8.5 and 5.5 respectively. In the case a window only is readout, CRPIX1 = -3.5 and CRPIX2 = 2.5 while CRVAL1 /CRVAL2 remain the same.
CDELTn is the number of detector pixels per data pixels, also known as binning factor.
CTYPEn gives the coordinate system for CRPIXn . CTYPEn for raw frames is the string `PIXEL' indicating that coordinate system refers to detector pixels.

In order to obtain celestial coordinates for a given image, a mapping is required between the sky and the physical layout of the detector while making use of the VLT field astrometric calibration and detector orientation (see section 4.11 ).

The keywords used to describe this mapping are known under the name World Coordinate System (WCS). With the help of WCS keywords, analysis software can establish the celestial coordinates corresponding to any pixel in the frame.

In the general case, WCS keywords will account for translation, rotation, mirroring and projection functions to accurately describe the mapping. However, in the case of the VLT, it is expected that under normal conditions a simple tangential projection will provide the required transformation.

The WCS keywords are based on the current proposal presented to the FITS community by Greisen and Calabretta (September 19, 1994 [3] , the proposal text can be found at
http://fits.cv.nrao.edu/documents/wcs/wcs.html .).

When the mapping has been applied, the coordinate system keywords have to be interpreted differently according to the value of CTYPEn (see [3] for details). The pipeline task saves the old detector coordinate keywords under the subsystem DET FRAM (see section 4.11 ). table 7 gives the ESO usage convention for WCS keywords.

TABLE 7 ESO usage of WCS keywords
	Keyword	Example	Explanation
(R)	`CRVAL1`	`79.93458`	RA at reference pixel in degrees
(R)	`CRVAL2`	`-45.78056`	DEC at reference pixel
(R)	`CRPIX1`	`510.`	reference pixel in X
(R)	`CRPIX2`	`512.`	reference pixel in Y
(R)	`CDELT1`	`-0.00277`	10 arcsec per pixel in RA
(R)	`CDELT2`	`0.00277`	10 arcsec per pixel in DEC
(S)	`CTYPE1`	`RA–-TAN'	TAN projection used
(S)	`CTYPE2`	`DEC–TAN'	TAN projection used
(R)	`PC001001`	`1.0`	no rotation, no skew
(R)	`PC001002`	`0.0`	no rotation, no skew
(R)	`PC002001`	`0.0`	no rotation, no skew
(R)	`PC002002`	`1.0`	no rotation, no skew

The PCnnnmmm keywords express the transformation matrix to correct for rotation, skew, etc. (please refer to the original WCS proposal document [3] for more information).

Two additional keywords are used by ESO to give the accuracy with which the astrometric calibration has been obtained. CMAPERR1 gives the accuracy in RA (in arcsec), CMAPERR2 the corresponding accuracy in DEC (also in arcsec).

4.3 Hierarchical Keywords

The FITS Format standard has been used largely by the astronomical community primarily as a format to transfer data. When it comes to use FITS as format to also archive observational data, the first question that arises is how to use FITS keywords to describe the parameters (instrumental, temporal, etc.) that define the configuration leading to the actual observation. In the absence of a widely accepted semantic standard, some communities have developed their own conventions 1 . In the Optical and the Infrared communities, however, different projects have diverged quite considerably, making the re-use of software packages for data reduction across observatories difficult.

One of the main drawbacks of FITS keywords is that they, being limited to names of 8 characters, do not provide enough name space to describe the sometimes hundreds of parameters required to describe the configuration of modern observing facilities.

ESO uses hierarchical keywords as a means to manage a structure of domain names, i.e. to group keywords that belong to the same logical entity. More generally, hierarchical keywords in FITS implement a domain naming convention allowing the definition of context–dependent keywords 2 . The advantage of hierarchical keywords is that they provide readable headers and support an easy to manage data interface based on context instead of managing keywords with cryptic names.

The main disadvantage of hierarchical keywords is that they are not a FITS standard and therefore only ESO data reduction software will be able to interpret parameters recorded in this way. This effectively limits the choice of software packages that ESO users can utilize. As a strategy to overcome this short-coming, ESO has developed the concept of translation tables that are used to produce, upon user request, external versions of ESO data products (see section 2 ).

4.3.1 The domain name structure

A hierarchical keyword starts by convention with HIERARCH and is followed by words describing each a domain except the last one before the = sign which describes the parameter being reported.

The general scheme of hierarchical keyword used by ESO is

HIERARCH ESO category [ subsystem(s) ] parameter = value / comment

Examples of this scheme are

HIERARCH ESO DET WIN1 STRX = 3 / Lower left pixel in X HIERARCH ESO INS FILT1 NAME = `OIII/3000' / Filter name HIERARCH ESO OBS NAME = `NGC 1275' / Observation block name
where DET , INS , OBS are categories, WIN1 and FILT1 are subsystems and STRX , NAME are parameters (see next sections).

4.3.1.1 Categories

The parameters are classified in a small number of broad categories . Ten such categories are presently defined, and designated by a 3-letter abbreviation:

GEN ( general ) provides parameters that relate to the observatory (see section 4.5 ).
OBS ( observation ) provides parameters that relate to the parent observation block to which this frame belongs (see section 4.6 ).
DPR ( data product ) describes the contents of the data product (see section 4.7 ).
TEL ( telescope ) describes the telescope setup, typically position and tracking (see section 4.8 ).
ADA ( adapter ) includes all descriptive parameters, when an adapter and/or a rotator is located between the telescope and the instrument (see section 4.9 ).
INS ( instrument ) describes any element along the optical path between the telescope (or the adapter) and the detector (see section 4.10 ).
DET ( detector ) describes the detector setting parameters (see section 4.11 ).
DEL ( delay line ) describes VLTI delay lines (1 through 8).
TRO ( transfer optics ) describes VLTI transfer optics.
PAF ( parameter file ) describes VLT Parameter File header information (see section 6 ).
SIM ( simulator ) describes simulator information like assumptions taken for the simulation process, e.g. sky emissivity or source brightness (see section 4.12 ).
ARC ( archive ) contains archiving remarks and parameters (see section 4.13 ).
PRO ( process ) details data processing parameters. These describe requested reduction recipes for an observation block and/or possible processing steps applied to the data during pipeline reduction (see section 4.14 ).
TPL ( template ) gives information on parameters for templates (see section 4.15 ).

A detailed description of each category is given in subsequent sections.

4.3.1.2 Subsystems

A subsystem keyword identifies a component in a category and can consist of zero or more words, generally consisting of maximum four characters. Subsystems commonly used by ESO are listed in table 8 .

TABLE 8 List of commonly used subsystem keywords
Subsystem	Meaning
`ACTO`	Active Optics description
`ADAO`	Adaptive Optics description
`ADC`	Atmospheric Dispersion Corrector description
`AIRM`	Airmass parameters
`AMBI`	Observatory ambient conditions
`CAT`	Target catalog
`CHIP`	Detector chip
`COMP`	Control computer
`DLMT`	Delay line metrology
`DOME`	Anything related to the telescope enclosure
`EXP`	Exposure description
`FILT`	Filter description
`FOCU`	Focus description
`FRAM`	Detector coordinate system description
`GRAT`	Grating
`GRIS`	Grism
`GRP`	Group of some kind
`GUID`	Guiding system description
`LAMP`	Any kind of lamp
`MIRR`	Instrument mirror
`MOS`	Multiple Object Spectrum details
`OPTI`	Optical element inserted in the light path
`OUT`	Detector readout Output description
`POS`	Position
`PRIS`	Prism
`PROG`	Observing Programme (accepted proposal)
`REDU`	Data reduction description
`SEIS`	Seismic monitor
`SHUT`	Shutter
`SLIT`	Any kind of slit
`SOFW`	Identifies control software for a subsystem
`TARG`	Target (astronomical object observed) description
`TRAK`	Tracking system description
`WIN`	Detector Window description
`WIND`	Anything related to wind measurements
`VLTI`	Anything related to coherent modes

A suffix i can be added to the last word of the subsystem when several identical components are available in order to differentiate them. As an example, FILT1 and FILT2 could be used to describe two filter elements along the light path.

Subsystem can be concatenated for a particular context like e.g. AMBI WIND to describe ambient (instead of dome) wind measurements, however, only a maximum of two subsystems can be used.

4.3.1.3 Parameters

The last word in the hierarchy designates which parameter of the (sub)system is reported, and implies the format (logical, integer, real, character string) as well as the unit used for the parameter. In order to keep to a minimum the required size by the complete hierarchy, we choose names not exceeding 8 characters. Characters allowed are (as for primary FITS keywords) all uppercase letters, numbers, the dash and underscore characters.

The basic parameter keywords used in the following sections are described in table 9 , examples are given in table 13 and table 14 , standard units are given when applicable.

TABLE 9 Basic parameter keywords
	Parameter	Meaning
(R)	`ALT`	Altitude angle in the ALT-AZ system (`o` )
(R)	`POSANG`	Position angle (`o` , North=0, East=90)
(R)	`AZ`	Azimuth angle (`o` left handed)
(S)	`DAYTIM`	Civil date and time as `ccyy-mm-ddThh:mm:ss.s' (ISO 8601)
(S)	`DATE`	UTC date and time as `ccyy-mm-ddThh:mm:ss.s' (ISO 8601)
(R)	`DEC`	Declination `d` (`o` )
(S)	`DID`	Data Interface Dictionary to which a subsystem complies
(R)	`DIST`	Distance in m
(R)	`DIMX`	Size along x-axis (m)
(R)	`DIMY`	Size along y-axis (m)
(R)	`ENC`	Encoder value
(R)	`ENCREL`	Encoder relative displacement (in encoder units)
(R)	`FWHM`	Seeing measurements (arcsec)
(S)	`ID`	Identification which is unique for any component
(R)	`LEN`	Any angular length (arcsec)
(R)	`LLEN`	Any linear length (m)
(R)	`LWIDTH`	Any linear width (m)
(S)	`MAX`	A maximum value
(S)	`MIN`	A minimum value
(S)	`MODE`	Optional mode description
(S)	`NAME`	a clear designation of the item
(I)	`NO`	Integer number or identifier (e.g. a position on a wheel)
(S)	`PARM`	Parameter in free format, e.g. `Par=value`
(R)	`PRES`	Pressure (Pa)
(R)	`RA`	Right ascension `a` (`o` )
(R)	`RATEA`	Tracking rate in RA (`o` /s)
(R)	`RATED`	Tracking rate in DEC (`o` /s)
(R)	`RHUM`	Relative humidity (%)
(R)	`ROT`	Rotation angle (`o` )
(R)	`SCALE`	Scale factor
(R)	`SCALX`	Scale factor along x-axis
(R)	`SCALY`	Scale factor along y-axis
(R)	`SPEED`	Speed of any system (m/s)
(L)	`ST`	a status binary flag, as `T` rue when the (sub)system is on, `F` alse when off
(S)	`STATUS`	a status of the system
(R)	`TEMP`	Temperature of any system (K)
(R)	`TILTA`	Tilt angle around the East-West axis (`o` ). See figure 1 .
(R)	`TILTB`	Tilt angle around the North-South axis (`o` ). See figure 1
(R)	`TIME`	Elapsed Time (seconds)
(S)	`TYPE`	Type or class of component
(R)	`UTC`	Universal Time Coordinated (seconds since midnight)
(R)	`WIDTH`	Any angular width (arcsec)
(R)	`WLEN`	Wavelength in nm
(R)	`X`	Position along x-axis (m)
(R)	`Y`	Position along y-axis (m)
(R)	`ZENIT`	Zenithal distance (`o` )

A suffix n may be appended to the parameter name in the case of multidimensional parameters (e.g. a complex slit made of several slitlets), as it is done in standard FITS. As an example, X1 refers to the x–position of the first component of the parameter.

guideline-10: Numeric suffixes must be edited without leading zeroes, i.e. the second component of the X parameter must be spelled X2 - but not X002.

The following two parameters deserve special attention because of their usage:

ID provides a unique, ESO–wide identification for a component, part or element. It is built using the following guidelines:
NAME provides a verbose name for the element that complements the ID . Names must follow the convention specified in section 10 .

4.7 Category Data Product ( `DPR` )

The DPR category includes parameters related to the data product and its contents.

DPR keywords are set by instrument template software (sequencer scripts).

DPR CATG , DPR TYPE and DPR TECH give details about the observation. The combination of all three keywords describes uniquely the observation in terms of its purpose and technique. The list of values allowed for each keyword are given below as they are currently known — this list may change as templates get defined for all VLT instruments. The following kinds of observations need yet to be covered by this scheme: Fabry-Perot, chopping, nodding, mosaics, interferometry, spectral scans and other for which the final data product specifications are not yet known.
Note that only certain combinations of these keyword values are meaningful — it is the task of the template designer to characterize the observation making use of a suitable combination of values.
DPR CATG , DPR TYPE and DPR TECH can take each two, at most three values, separated with commas. This provides the means to describe a wide range of observations kinds. Tables 7 to 9 give the possible values of these keywords as they are known at the time this document is issued. It is expected however that these value lists will be enhanced in the future as the dictionaries for each instrument are written.
DPR CATG gives the observation category. It takes the values given in table 10 .
DPR TYPE gives the type of observation/exposure within the category. The list of possible DPR TYPE values is given in table 11 .

DPR TECH gives the technique used for the observations. It takes the values given in table 12 .

TABLE 12 List of `DPR TECH` values
Value	Explanation
`IMAGE`	any picture
`SPECTRUM`	single-order spectrum
`ECHELLE`	cross-dispersed spectrum
`MOS`	frame with spectra of several objects
`POLARIMETRY`	polarimetric exposure
`CORONOGRAPHY`	coronography exposure
`INTERFEROMETRY`	coherent exposure with more than one telescope beam
`TEL-THROUGH`	telescope through-focus sequence
`INS-THROUGH`	instrument through-focus sequence
`WEDGE`	focus wedge frame
`HARTMANN`	Hartmann focus test
`ABSORPTION-CELL`	Absorption lines included (e.g. Iodine cell)
`DRIFTSCAN`	drift scanning exposure
`TRAILED`	trailed exposure

As examples, a twilight sky flat is described by:

DPR CATG = `CALIB'

DPR TYPE = `SKY,FLAT'

DPR TECH = `IMAGE'

and a UVES observation of a scientific target with the Iodine cell would be described as:

DPR CATG = `SCIENCE,CALIB'

DPR TYPE = `object-class-code,WAVE'

DPR TECH = `ECHELLE,ABSORPTION-CELL'

4.10 Category Instrument (`INS` )

INS keywords are set by the Instrument Control Software (ICS) or by the Observation Support Software (OS).

Many subsystem keywords are used in this category. In some cases, a possible i suffix will be required when several similar subsystems can be mounted.

An example of the typical keywords required to describe an instrument setting is given in table 13 . It includes a general description of the instrument itself (the ID parameter, a possible MODE ), followed by an accurate description of each element used.

TABLE 13 Example of the `INS` category
	Keyword	Example	Explanation
(S)	`INS ID`	`EMMI'	Instrument Identification
(S)	`INS DATE`	`1997-03-12T12:02:31'	Control SW installation date
(S)	`INS MODE`	`DIMD'	Mode depends on the instrument
(S)	`INS PATH`	`BLUE'	Instrument optical path used
(R)	`INS PIXSCALE`	`0.270`	Pixel scale (arcsec)
(S)	`INS FOCU MODE`	`USER'	Focus determination method
(I)	`INS FOCU VALUE`	`8309`	Focus unit encoder value
(S)	`INS MIRR1 ID`	`ALUMINUM/1'	Mirror unique identification
(S)	`INS MIRR1 NAME`	`DIMD'	Mirror position
(S)	`INS SLIT1 TYPE`	`MD SLIT'	Type of slit
(S)	`INS SLIT1 ID`	`LONGSLIT/2'	Slit unique identification
(S)	`INS SLIT1 NAME`	`SLIT_1.0'	Slit verbose name, see section 10
(R)	`INS SLIT1 WID`	`1.0`	Slit width (arcsec)
(R)	`INS SLIT1 LEN`	`35.00`	Slit length (arcsec)
(R)	`INS SLIT1 POSANG`	`0.000`	Position angle (N=0 E=90)
(S)	`INS PRIS1 ID`	`DIC PRSM/1'	Prism unique identification
(S)	`INS PRIS1 NAME`	`DICHR'	Beamsplitter position name
(S)	`INS GRAT2 ID`	`GR5'	Blue grating unit unique ident.
(S)	`INS GRAT2 NAME`	`GRAT_400B'	Blue grating unit name
(S)	`INS GRAT2 DISP`	`15.0`	Blue grating dispersion (nm/mm)
(R)	`INS GRAT2 WLEN`	`250.0`	Blue grating central wavel. (nm)
(S)	`INS MIRR2 NAME`	`LOWER BLUE'	Lower folding mirror blue
(L)	`INS MIRR2 ST`	`T`	Mirror IN when true
(S)	`INS FILT2 ID`	`#590'	ESO Filter identification
(S)	`INS FILT2 NAME`	`OIII/3000'	ESO Filter name

While optical elements are described in the FITS headers by the corresponding keywords (FILT , GRIS , etc.), the generic OPTI subsystem gives the means to describe elements for engineering purposes. The OPTI subsystem may refer to any selectable optical element: filter, a grism, a polarimeter, a diaphragm, etc. Such elements are generally mounted on a wheel.

An example for OPTIi keywords is given when an instrument operates several wheels to implement a logical function (e.g. FILT1) , i.e. the user selects one filter to be inserted into the light path and the instrument internal logic selects which wheel has the filter mounted. For such cases, FILTi keywords are used for instrument setup while the OPTIi set of keywords describe uniquely the internal instrument configuration.

Another example for the usage of OPTIi keywords is the case of `multi-purpose' wheels. In this case a single wheel is used to mount different element types, e.g. grisms and a focus-wedge. Again here it is advisable to separate the user function (setup selection) from the actual instrument configuration recording. OPTIi keywords provide the mechanism to accurately describe the actual setup independently of user intention.

It is assumed that n wheels are available; for each of these wheels, the following parameters must be known:

OPTI n NO specifies the actual slot number n in the wheel.
OPTI n ID specifies the identification of the filter, grism, etc. The identification scheme is given in section 10 .
OPTI n TYPE and OPTI n NAME provide an explanation of what is inserted along the optical path. These two parameters can normally be derived from the contents of the OPTI n ID keyword. OPTIn TYPE provides a generic name for the optical element, OPTI n NAME provides a verbose name for the optical element. The naming convention is given in section 10 .

Angles that describe the orientation of a grism or polarimeter include:

OPTI n POSANG specifies the position angle of the optical element on the sky, East of North.
OPTI n ROT specifies the rotation angle in regard to the optical axis.
OPTI n TILTA specifies the tilt angle in regard to the plane perpendicular to the optical axis along the East-West direction.
OPTI n TILTB specifies the tilt angle in regard to the plane perpendicular to the optical axis along the North-South direction.

All angles are expressed in degrees, and measured according to the conventions given in section 1.6 .

For example:

INS OPTI3 TYPE = `FILTER' / Optical element used

INS OPTI3 NO = 7 / Position of wheel used

INS OPTI3 ID = `#590' / ID of the element

INS OPTI3 NAME = `OIII/3000' / Name of the element

would reflect filter '#590' (OIII/3000) being mounted on wheel 3 in position 7.

SOFW identifies the detector control software and gives related parameters (see the log example on page 36 ).

guideline-15: INS DATE gives the installation date of the instrument control software system.

guideline-16: INS ID gives the revision number of the instrument control software.

4.11 Category Detector (`DET` )

DET keywords are set by the Detector Control Software (DCS) for optical instruments and by the Instrument Control Software for infrared instruments.

Subsystems used in this category are:

CHIP describes each CCD chip when an array of CCDs is exposed.
EXP describes exposure parameters.
FRAM describes the detector coordinate system (see section 4.2 ).
OUT describes the outputs used for read-out. This subsystem includes the description of detector orientation.
PARM gives unspecified detector parameters.
READ gives readout parameters.
SHUT gives shutter parameters.
SOFW identifies the detector control software and gives related parameters (see the log example on page 36 ).
WIN describes read-out window(s) parameters.

TABLE 14 Example `DET` category keywords
	Keyword	Example	Explanation
(S)	`DET NAME`	`#31-TK1024AB'	Name of detector system
(S)	`DET DATE`	`1997-03-12T12:02:31'	Control SW installation date
(S)	`DET ID`	`RCA5064/CCDB-V4.2'	Detector system identification
(S)	`DET EXP ID`	`23965031`	Unique exposure ID for detector
(R)	`DET CHIPi PSZX`	`24.E-6`	Size of a pixel in X direction (m)
(R)	`DET CHIPi PSZY`	`24.E-6`	Size of a pixel in Y direction (m)
(I)	`DET WINDOWS`	`1`	# of windows read-out
(I)	`DET BITS`	`16`	# of bits/pixel transferred
(R)	`DET WINi STRX`	`1.`	Position of window along x axis
(R)	`DET WINi STRY`	`400.`	Position of window along y axis
(I)	`DET WINi NX`	`1124`	# of pixels along X
(I)	`DET WINi NY`	`201`	# of pixels along Y
(I)	`DET WINi BINX`	`1`	Binning factor along X
(I)	`DET WINi BINY`	`1`	Binning factor along Y
(R)	`DET WINi UIT1`	`900.`	Requested exposure time (s)
(I)	`DET WINi NDIT`	`1`	# of subintegrations
(R)	`DET WINi DIT1`	`900.000`	Actual subintegration time (s)
(S)	`DET OUTi ID`	`5064-18-5/1'	Output identification
(I)	`DET OUTi X`	`1`	X location of default out
(I)	`DET OUTi Y`	`1`	Y location of default out
(S)	`DET READ SPEED`	`SLOW'	Read-out speed for default out
(R)	`DET OUTi GAIN`	`2.`	Gain for default out
(R)	`DET OUTi CONAD`	`35.015`	ADUs to electrons factor (e/ADU)
(R)	`DET TMPi MAX`	`175.8`	Max DET temp. during exposure (K)

guideline-17: When only one detector device is exposed, NAME and ID give a unique description of the detector. When an array of CCDs is used, the subsystem CHIP describes each chip in detail (e.g. CHIP1 NAME, CHIP1 ID).

WIN includes parameters that define the readout region used on the CCD: the location of the window on the chip (offset position), its size, and the binning factors used. The horizontal axis is named X, and the vertical axis Y.

guideline-18: A suffix i is added to WIN when multiple windows are read-out in which case DET WINDOWS gives the number of windows.

Let us assume that the window is defined with its lower left corner at position ( i 0 , j 0 ), a size D i ¥ D j , and binning factors ( f i , f j ); the largest window has the values (1,1) for the start position, and binning factors (1,1). The window is described by:

NX and NY give the number of pixels, i.e.: D i = NX ¥ f i and D j = NY ¥ f j The values are obviously identical to those given in NAXIS1 andNAXIS2 ;
BINX and BINY give the binning factors f i and f j respectively;
STARTX and STARTY represent the start position of the window, i.e. i 0 and j 0 respectively.

guideline-19: When more that one output is used for the read-out OUT takes a suffix to describe each output separately (OUTn). In this case NOUT gives the number of outputs used. Note that the pixel area which is covered by each OUT is not a setup parameter but rather

guideline-20: In those cases in which several outputs are used to read-out the chip and disjoint windows are read, the subsystem combination DET OUTn WINm must be used.

The FRAM subsystem provides the description frame in detector (pixel) coordinates as opposed to the WCS keywords which provide pixel to sky mapping (see also section 4.2 ).

guideline-21: DET DATE gives the installation date of the detector control software system.

guideline-22: DET ID gives the name and revision number of the detector control software.

1. See recommendations of the OFWG, NASA/GSFC at
http://legacy.gsfc.nasa.gov/docs/heasarc/ofwg

2. Another example of a domain name management is the very well known structure of Internet network addresses (e.g. host.domain.country), except that here the hierarchy is reversed: from general (broad) to specific (narrow).

`D`	Director's Discretionary Time Programme
`K`	Key Programme
`T`	Technical programme
`<blank>`	Normal Science Programme

Value	Explanation
`SCIENCE`	any scientific object
`CALIB`	any calibration source
`TEST`	any exposure to check the instrument performance/setup
`SIMULATION`	any simulated exposure
`OTHER`	any other exposure

Value	Explanation
object class	following the scheme to be defined in DICD 2.0
`SKY`	any observation of an empty field in the sky
`STD`	any observation of a standard calibration source
`FLUX`	flux standard (spectroscopy and photometry)
`VELOC`	radial velocity standard
`POLAR`	polarization standard
`RECT`	source usable for continuum rectification
`TELLURIC`	source usable for correction for telluric lines
`SPECTEMPL`	spectral template source
`PSF-CALIBRATOR`	reference star for PSF calibration
`ASTROMETRY`	astrometric standard field
`BIAS`	readout frame
`DARK`	dark exposure (shutter closed)
`FLAT`	any flat field exposure
`LAMP`	any lamp exposure
`DOME`	any exposure using the dome
`WAVE`	any (instrument-internal) wavelength calibration
`FOCUS`	any focus exposure
`FRINGE`	frame recording interference fringes in the system
`OTHER`	Any other observation type

Data Interface Control Document

Top Back Next

4 Keyword Description

4.1 Primary FITS keywords

TABLE 1 Primary FITS keywords set by the DET subsystem

TABLE 2 Primary FITS keywords set by the TCS subsystem

TABLE 3 Usage of the `TELESCOP` keyword at ESO

TABLE 4 Primary FITS keywords set by the INS subsystem

TABLE 5 FITS primary keywords set by the On-line Archive subsystem

4.2 Coordinate system keywords

TABLE 6 Usage of coordinate system keywords for raw frames

TABLE 7 ESO usage of WCS keywords

4.3 Hierarchical Keywords

4.3.1 The domain name structure

4.3.1.1 Categories

4.3.1.2 Subsystems

TABLE 8 List of commonly used subsystem keywords

4.3.1.3 Parameters

TABLE 9 Basic parameter keywords

4.4 Errors and statistics parameters

4.5 Category General (`GEN` )

4.6 Category Observation ( `OBS` )

4.7 Category Data Product ( `DPR` )

TABLE 10 List of `DPR CATG` values

TABLE 11 List of `DPR TYPE` values

TABLE 12 List of `DPR TECH` values

4.8 Category Telescope (`TEL` )

4.9 Category Adapter (`ADA` )

4.10 Category Instrument (`INS` )

TABLE 13 Example of the `INS` category

4.11 Category Detector (`DET` )

TABLE 14 Example `DET` category keywords

4.12 Category Simulator (`SIM` )

4.13 Category Archive (`ARC` )

4.14 Category Process (`PRO` )

4.15 Category Template (`TPL` )

Top Back Next

Data Interface Control Document

Top Back Next

4 Keyword Description

4.1 Primary FITS keywords

TABLE 1 Primary FITS keywords set by the DET subsystem

TABLE 2 Primary FITS keywords set by the TCS subsystem

TABLE 3 Usage of the TELESCOP keyword at ESO

TABLE 4 Primary FITS keywords set by the INS subsystem

TABLE 5 FITS primary keywords set by the On-line Archive subsystem

4.2 Coordinate system keywords

TABLE 6 Usage of coordinate system keywords for raw frames

TABLE 7 ESO usage of WCS keywords

4.3 Hierarchical Keywords

4.3.1 The domain name structure

4.3.1.1 Categories

4.3.1.2 Subsystems

TABLE 8 List of commonly used subsystem keywords

4.3.1.3 Parameters

TABLE 9 Basic parameter keywords

4.4 Errors and statistics parameters

4.5 Category General ( GEN )

4.6 Category Observation ( OBS )

4.7 Category Data Product ( DPR )

TABLE 10 List of DPR CATG values

TABLE 11 List of DPR TYPE values

TABLE 12 List of DPR TECH values

4.8 Category Telescope ( TEL )

4.9 Category Adapter ( ADA )

4.10 Category Instrument ( INS )

TABLE 13 Example of the INS category

4.11 Category Detector ( DET )

TABLE 14 Example DET category keywords

4.12 Category Simulator ( SIM )

4.13 Category Archive ( ARC )

4.14 Category Process ( PRO )

4.15 Category Template ( TPL )

Top Back Next

TABLE 3 Usage of the `TELESCOP` keyword at ESO

4.5 Category General (`GEN` )

4.6 Category Observation ( `OBS` )

4.7 Category Data Product ( `DPR` )

TABLE 10 List of `DPR CATG` values

TABLE 11 List of `DPR TYPE` values

TABLE 12 List of `DPR TECH` values

4.8 Category Telescope (`TEL` )

4.9 Category Adapter (`ADA` )

4.10 Category Instrument (`INS` )

TABLE 13 Example of the `INS` category

4.11 Category Detector (`DET` )

TABLE 14 Example `DET` category keywords

4.12 Category Simulator (`SIM` )

4.13 Category Archive (`ARC` )

4.14 Category Process (`PRO` )

4.15 Category Template (`TPL` )