# # "@(#) $Id: DicbSummary.txt,v 0.7 2004/07/29 12:05:32 vltsccm Exp $" # # dicVIRCAM/DicbSummary # # For convenience, this text file lists the recommendations from # the ESO-VLT Data Interface Control Board. See [AD1] for details. Summary of Data Interface Control Document ========================================== [AD1] Data Interface Control Document, GEN-SPE-ESO-19940-794, V2.0 21 May 2002 Guidelines ---------- These guidelines are mentioned in several places throughout the document. --- Observation Frames --- 1) Multiple windows are stored in different image extensions of the same FITS file, with each extension storing the data from one window. 2) Multiple chip data are stored in different image extensions of the same FITS file if they refer to the same exposure, with each extension storing the data from one chip. 3) If a FITS extension consists of one HDU only (one chip or one window) then the data are stored in the primary array. If the file contains multiple HDUs the primary array remains empty. 4) Keyword values always reflect the actual setting of the parameter or function in question, as opposed to the value that was requested at setup. 5) If a FITS file consists of more than one HDU, keywords describing the dataset as a whole are written into the primary header, while keywords that are related to the data in a particular extension are written into the header of that extension. 6) Only optical elements intersecting the light path in a given exposure are recorded in the header. 7) Header records should be ordered such that primary keywords are listed first, followed by hierarchical keywords sorted by category in the order DPR, OBS, TPL, GEN, TEL, ADA, INS, DET, ESO-LOG, then any others. --- Log Files --- 8) By convention, all keywords that identify the configuration in place on a given night are recorded in the configuration log at the beginning of the night, and whenever the configuration changes. --- Primary FITS Keywords --- 9) The primary FITS keyword OBJECT contains the value of OBS TARG NAME for science exposures and DPR TYPE for all other exposures. 10) The primary FITS keyword PI-COI repeats the value of OBS PI-COI NAME. 11) The primary FITS keyword OBSERVER contains the string 'SERVICE' when service observing is conducted. --- Coordinate System Keywords --- 12) The World Coordinates reference pixel is defined as the (fractional) pixel coordinate of the rotator centre. 13) World Coordinate keywords describe the coordinate system for each chip. In the case of multi-chip inctruments keywords are written to the header of each of the image extensions. 14) Subsystem keywords may be concatenated for a particular context (e.g. AMBI WIND) but only a maximum of two keywords may be concatenated in this way. --- Heirarchical Keywords --- 15) Numerical suffixes for parameter keyword names must not have leading zeros, i.e. the second components of X should be X2 not X002. --- Errors and Statistical Parameters --- 16) In the case a enumerated parameters (e.g. TEMP1) the index suffix is always added at the end (i.e. TEMPMAX1 not TEMP1MAX). --- Category Data Product (DPR) --- 17) For a science frame (DPR CATG='SCIENCE') the DPR TYPE keyword is filled with the object class tag provided by the Observation Block. --- Category Observation (OBS) --- 18) The first template in an Observation Block has OBS TPLNO = 1 --- Category Template (TPL) --- 19) The first exposure in a template has TPL EXPNO = 1 --- Category Telescope (TEL) --- 20) The TEL DATE keyword gives the installation date of the TCS software. 21) The TEL ID keyword gives the revision number of the TCS software. --- Category Instrument (INS) --- 22) A suffix is appended to an instrument subsystem name keyword if there are more than one even if the second is not mounted (e.g. FILT1 keyword is used even if a second filter wheel does not affect the beam). 23) The INS DATE keyword gives the installation date of the ICS software. 24) The INS ID keyword gives the revision number of the ICS software. --- Category Detector (DET) --- 25) Detector subsystem keyword CHIPi always carries an index, even if only one detector chip is exposed. The keyword DET CHIPS gives the number of chips used. 26) The detector subsystem keywords DET CHIPi NX and DET CHIPi NY refer to the number of used pixels on the chip (i.e. which are actually written to an unbinned unwindowed image) rather than the physical number of pixels (which might include unused reference pixels or frame transfer areas). 27) The detector subsystem keyword DET OUTi always carries an index, even if one output is used. DET OUTPUTS gives the number of outputs used. The pixel area covered by each output is not a setup parameter - each DCS needs to assemble the selected windows properly. 28) The detector outputs are counted per chip, not over the whole instrument, i.e. there are DET OUT1, DET OUT2 subsystems for each chip. 29) Detector subsystem keywords DET OUTi NX and DET OUTi NY contain the number of image pixels that are read out through port i, exclusing any prescan or overscan pixels. 30) The detector subsystem keyword DET WINi always carries an index, even if there is only one window. DET WINDOWS gives the number of windows used. 31) In those cases in which several outputs are used to read out a chip *and* disjoint windows are reda, the keyword combination DET OUTn WINm must be used. 32) The keyword DET DATE gives the installation date of the DCS software. 33) The keyword DET ID gives the revision number of the DCS software. --- Data Interface Dictionaries --- 34) Where a dictionary is stored as a file on a computer system, the file name should be the same as the dictionary name. 35) The fields Revision, Date, Status and Description in a dictionary are repeated for each revision of a dictionary. 36) Every dictionary must contain a parameter record describing the dictionary itself. 37) By convention, the comment part of a FITS/LOG/etc. record is appended the name of the physical unit in parenthesis (square brackets in a parameter record, round brackets in a FITS record). --- Naming Convention for Optical Components --- 38) Each optical element (filter, grism etc.) shall have a unique identifier and a verbose name. Identifiers are typically sequential numbers, which are recorded in the FILT ID keyword and used as a reference to the full characterisation information (e.g. transmission curve) of the component. Verbose names are recorded in FILT NAME. 39) Identfiers of elements that cease to exist (e.g. broken filter) are retained to ensure the historical validity of the archive. 40) The ID keyword can require up to 10 characters of space and the NAME keyword up to 30 characters. 41) An optical element has a technical name that describes its major physical characteristics, and may have a short conventional name as well. 42) Values for wavelengths and other characteristics are rounded to the nearest integer in the naming scheme, except for sluit widths. --- File Naming Convention --- 43) It is recommended that instrument names are put into uppercase letters when used in file names. Section4.1 Primary FITS keywords -------------------------------- *** Changes needed for VISTA IR ? TELESCOP = 'ESO-VISTA' (Table 2) INSTRUME = 'VIRCAM' Section 4.3.1.1 Heirarchical Keyword Categories (p23) ----------------------------------------------------- 2 or 3 letter acronyms DPR - Data Product OBS - Observation (Observation Block) TPL - Template GEN - General (observatory parameters) TEL - Telescope ADA - Adaptor (rotator located between telescope and instrument) INS - Instrument DET - Detector OCS - Observation Control Software (OS) DEL - Delay line COU - Coude (VLTI) ISS - Interferometric Supervisor Software (VLTI) AOS - Adaptive Optics Software PAF - Parameter File SIM - Simulator (simulator assumptions) ARC - Archive (archiving remarks and parameters) PRO - Process (data processing parameters) QC - Quality Control (results) Table 5 Subsystems (p24) ------------------------ 0, 1 or 2 words, each of up to 4 characters ACTO - Active Optics ADAO - Adaptive Optics ADC - Atmospheric Dispersion Compensator AIRM - Airmass parameters AMBI - Observatory ambient conditions CAT - Target catalogue CHIP - Detector chip (e.g. DET CHIP) COMP - Control computer DLMT - Delay line metrology DOME - Telescope enclosure DROT - Derotator DPOR - Depolariser EXP - Exposure FILT - Filter (e.g. INS FILT) FOCU - Focus (e.g. TEL FOCU) FRAM - Detector coordinate system GRAT - Grating GRIS - Grism GRP - Group (of some kind) GUID - Guiding system LAMP - Lamp MIRR - Instrument mirror MOS - Multi-object spectrum details OPTI - Optical element inserted in light path OUT - Detector readout options POS - Position PRIS - Prism PROG - Observing programme REDU - Data reduction ROT - Rotating device SIES - Siesmic monitor SENSOR - Digital sensor (breaks 4 character rule) SHUT - Shutter SLIT - Slit SOFW - Control software TARG - Astronomical target TILT - Tilt TRAK - Tracking system WIN - Detector window WIND - Wind measurement VLTI - Coherent modes *** Extra for VISTA IR ? HOWFS - High Order Wavefront Sensor parameters Table 6: Basic Parameter Keywords (p26) --------------------------------------- Up to 8 characters (only a few listed here) ENC - Encoder ENCREL - Encoder relative " ID - Identification (up to 10 characters) " NAME - Name (up to 30 characters) " NO - Number (e.g. slot number) " PRES - Pressure (Pa) " ROT - Rotation angle (degrees) " SCALE - Scale factor SCALX - Scale factor along X axis SCALY - Scale factor along Y axis " ST - State binary flag (T/F) " TEMP - Temperature (K) " X - Position along X axis (m) Y - Position along Y axis (m) Table 7: Data product categories - DPR CATG (p28) ------------------------------------------------- SCIENCE - any scientific object CALIB - any calibration source TEST - any test exposure SIMULATION - any simulated exposure OTHER - any other exposure Table 8: Data product types - DPR TYPE (p29) -------------------------------------------- OBJECT - any unspecified object SKY - any empty field of sky STD - any standard calibration source FLUX - flux standard VELOC - radial velocity standard POLAR - polarization standard RECT - for continuum rectification TELLURIC - for correction telluric (night sky) lines SPECTEMPL - spectral template source PSF-CALIBRATOR - reference for PSF calibration ASTROMETRY - astrometric standard field BIAS - readout frame DARK - dark frame FLAT - any flat-field LAMP - any lamp exposure DOME - any exposure using the dome SCREEN - any exposure using an illuminated screen WAVE - any (instrument internal) wavelength calibration FOCUS - any focus measurement exposure SLIT - any non-spectroscopic exposure using slit FIBER - any exposure using fibres FMTCHK - any arc lamp exposures to solve dispersion (UVES) ORDERDEF - any flat-field to derive order and background positions (UVES) FRINGE - frame recording interference fringes in the system OFFSOURCE - any off-source observation for interferometry BEAM_A - any observation in interfereometry using only one beam BEAM_B - any observation in interfereometry using only one beam OTHER - any other type Examples 'SKY, FLAT' 'DOME, FLAT' *** Extra for VISTA IR ? WFS - any exposure used to derive a wavefront Table 9: List of data processing techniques - DPR TECH (p29) ------------------------------------------------------------ IMAGE - any picture SPECTRUM - any spectrum ECHELLE - cross-dispersed spectrum MOS - multi-object spectrum MXU - multi-object spectrum using pre-manufactured mask POLARIMETRY - polarimetric exposure CORONOGRAPHY - coronographic 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 SLIC# - observation using image slicer (UVES) HIT - high time resolution mode (FORS) FILTERCURVE - spectroscopic flat-field with narrowband filter included *** Extras for VISTA IR ? TEL-POINTING - Telescope pointing calibration exposure TEL-ROTATOR - Telescope rotator calibration sequence CURVATURE - Curvature sensing exposure to derive wavefront Table 10: Examples of INS catagory (p33) ---------------------------------------- *** Extra for VISTA IR camera INS HOWFS Table 11: Examples of DET category keywords (p36) ------------------------------------------------- Table 13: VLT Parameter file header keywords (p48) -------------------------------------------------- PAF records are limited to 256 characters in length. PAF.HDR.START PAF.TYPE PAF.ID PAF.NAME PAF.DESC etc... PAF.HDR.END PAF.PROT.START PAF.PROT.END PAF.TYPE must take one of the following values "Reference Setup" "Instrument Setup" "Detector Setup" "Telescope Setup" "Reference Configuration" "Configuration" "Ambient Data" "Template Signature" "OB Description" "Pipeline Result" Data Interface Dictionary Parameter Records (p54) ------------------------------------------------- Parameter name: Class: Context: Type: Value Format: Unit: Comment Format: Description: Parameter name may contain a suffix "i" acting as a placeholder for an integer. Parameter class can be on or more of the following: setup - keyword appears in setup operations header - keyword appears in science headers ext-header - keyword appears in extension header unit maint-header - keyword appears in maintenance headers template - keyword appears in template script or signature file conf-log - keyword appears in configuration log cond-log - keyword appears in the conditions log ops-log - keyword appears in the operations log reduc-log - keyword appears in the reduction log qc-log - keyword appears in quality control log config - keyword appears in configuration description private - keyword is used only internally by the subsystem Parameter context describes the overall category. Examples: instrument telescope Parameter type can be string, logical (T/F), integer, double Parameter comment field can contain the following keywords: %TIME - replaced by value converted to time %DAYTIME - replaced by value converted to date and time %DEGREE - replaced by value converted to dd:mm:ss %HOURANG - replaced by value converted to hh:mm:ss %CELSIUS - replaced by value converted from K to C Section 10: Naming Scheme for Optical Components (p59) ------------------------------------------------------ INS OPTIn keywords describe optical components making up the internal functions of the instrument, where these are not fully described by the usual INS FILT etc. keywords. Allowed values INS OPTIn TYPE keywords are: MIRROR FILTER GRISM GRATING ECHELLE WOLLASTON BEAMSPLITTER FIBER PRISM FABRYPEROT SLIT MASK FOCUSWEDGE HARTMANN RETARDER DICHROIC LENS FREE (when nothing mounted in the slot) Section 10.3.1: Filters ----------------------- Filters have conventional names and technical names: Conventional names: J, K, etc.. Technical names: FILT__ FILT_VARi for variable filters FILT_<50% wavelength in nm>_ for long/shortpass filters where is L or S