FITS keywords

| HyperLeda home | Documentation | Search by name | Search near a position | Define a sample | SQL Search |

HyperLeda: The FITS Archive

• Introduction: FITS keywords
• Categories of Keywords
• Definition of the keywords

Introduction: FITS keywords

Note: We use the term 'keywords', as in the documents describing the Fits conventions, rather than 'descriptor' as used in Midas
The FITS standards are described in NASA/Science Office of Standards and Technology NOST 100-1.1 "Definition of the Flexible Image Transport System (FITS)", 1995.

As far as possible the keywords will conform the recommendations of the HEASARC Fits Working Group and to the "World Coordinates" Proposal (Eric W. Greisen)

The principle is to provide a description as much standardized as possible in order to help downstream softwares

Non-standard keywords: The FITS standard strongly limits the name and content of keywords. Different packages use local norms to allow for long string keywords or tabular data.

• Midas codes "descriptors" (ie. keywords) in HISTORY keywords. They form a group like:

  HISTORY  ESO-DESCRIPTORS START   ................                              
  HISTORY  'LHCUTS'         ,'R*4 '   ,    1,    4,'5E14.7',' ',' '              
  HISTORY  -3.2906001E+00 1.2797500E+03-3.2906001E+00 1.2797500E+03              
  HISTORY                                                                        
  HISTORY  'DISPLAY_DATA'   ,'I*4 '   ,    1,    9,'7I10',' ',' '                
  HISTORY           1         1       152       257         0        -1        -1
  HISTORY          -1        -1                                                  
  HISTORY                                                                        
  HISTORY  ESO-DESCRIPTORS END     ................                              

  This conforms to the FITS standards, but needs a special programmation in the I/O routines.
• Another answer to overturn this limitation is the definition of Hierarchical Keywords adopted by the ESO VLT archive .
• HEASARC has defined a standard for long string keywords. The presence of this extension is signaled by the keyword:

  LONGSTRN= 'OGIP 1.0'           / The HEASARC Long String Convention may be used.
  

  Then long keywords are coded as:

  LONGK   = '1234567890123456789012345678901234567890123456789012345678901234567&'
  CONTINUE  '890123456789012345678901234567890' / [ADU] Cut                      

  This does NOT conform to the FITS standard.

The HyperLeda keywords conform the FITS standard

• the keywords can only be up to 8 characters long
• HyperLeda keywords are prefixed "H_"
• keywords are uppercase.
• keywords should contain all digits and latin alphabetic characters (underscore "_" is also permitted; "-" accepted in FITS is avoided here since some softwares do not like it);

Categories of keywords

1. FITS mandatory keywords
2. Keywords for software internal use
3. Dataset Setup Keywords
4. Frame Setup Keywords
5. Related Frames keywords
6. Processing History Keywords
7. Foreign Keywords

Definition of the keywords

FITS mandatory keywords
Name Status format	Description
SIMPLE Mandatory (Logical)	T, ie. conforms to Fits standards
BITPIX Mandatory (Integer)	Data representation UsuallyBITPIX=-32 (IEEE Floating), but other values are accepted
EXTEND Non-Mandatory (Logical)	T, FITS extension may be present
NAXIS Mandatory (Integer)	Number of axes
NAXISn Mandatory (Integer) n=1, ..., NAXIS	Length, in pixels, of axis "n"
...	... (other keywords, reserved or not) ...
END Mandatory (No value)	End of Header
Keywords for software internal use
Name Status format	Description
CREATOR Mandatory (Character string)	Identification of the package who wrote the data: CREATOR = Pleinpot 0 This definition follows HEASARC R7 It is in competition with some use of ORIGIN (eg. Midas writes: ORIGIN = ESO-Midas. In the present version, Pleinpot will not process ORIGIN If CREATOR = Pleinpot nnn the reading program will search for the Pleinpot specific set of keywords. If a file is processed outside of Pleinpot. it is recommended to force the change of the value of CREATOR if the software does not do it, because the data may have been altered with respect to the value of the keywords. Pleinpot would not know about this if CREATOR is not changed. The VLT archive use ORIGIN to identify the origin of the observations, eg. "ESO-PARANAL".
FILENAME Mandatory (Character string)	Name of the disk (or memory) file containing the data
EXTNAME Mandatory (Character string)	Name of the extension A FITS file may contain several extension (images or tables), EXTNAME is intended to provide a unique identification to each extension in the file
H_PARENT (Character string)	File identifier of the parent of the current extension Some extension are related between each others. For example H_WCALIB points to an extension containing the wavelength calibration relation. It some case is is also necessary to establich a connection between an extension and its "parent" (the file or extension from which it originated). H_PARENT does this job.
DATE Mandatory (Character string)	Date the file was created or modified (This is not the same as DATE-OBS, the date of observation).
Dataset Setup Keywords
Name Status format	Description
OBSERVER Non-Mandatory (Character string)	Identify the observer(s) see also AUTHOR
TELESCOP Non-Mandatory (Character string)	Identification of the data acquisition telescop Note that when "importing" a foreign file, this keyword is used, as well as INSTRUME to recognize the type of data and initialize the internal Pleinpot/HyperLeda keywords. This recognition is hard coded in the software.
INSTRUME Non-Mandatory (Character string)	Identification of the data acquisition instrument See TELESCOP
AUTHOR Not used (Character string)	AUTHOR was originally intended to cite a publication Maybe we could use it to identify who is maintaining the corresponding dataset (to be defind).
REFERENC Not used (Character string)	Bibliographic reference Maybe we could provide BIBCODE here.
H_CONTXT Mandatory (Character string)	Context Value Meaning LSS Long Slit spectroscopy BBI Broad Band image ELD ELODIE Echelle Order spectra ETS Evolutive Template Spectra ... ...
H_DTSET Mandatory (Character string)	Dataset identification coded on 9 characters
H_DRON Mandatory	Detector Read out noise, in electrons
H_DPIXn Mandatory	Detector Pixel step along axis "n", in micron/dpx dpx stands for "detector pixel" This is not obligatory equal to the spet between pixels. There may be a bind border around pixels, or pixels can overlap (scan of a photographic plate).
H_SCALE BBI & LSS Mandatory	Spatial scale on the detector [arcsec/micron]
H_WDISP LSS Mandatory	Wavelength dispersion [Angstrom/mm]
Frame Setup Keywords
Name Status format	Description
MJD-OBS Non-Mandatory (D Float)	Modified Julian Date of the start of obs. (in days) Adopted by ESO Sometime the date of observation was not written in the header, or was lost in the processing... This will miss at some stage of the data analysis (eg. for computing the heliocentric correction to the velocity).
DATE-OBS Non-Mandatory (Character string)	Date of data acquisition Format CCYY-MM-DDThh:mm:ss (Conform to ISO 8601) Redundant with MJD-OBS, given for (1) Down-stream compatibility (2) Human readability
EXPTIME Mandatory	Exposure time in seconds and decimals Adopted by ESO archive HEASARC recommends EXPOSURE Some observatories use: TM-EXPOS
H_TYPE Mandatory (Integer)	Type of file 01 Science observation 02 Template observation 11 Mean Bias/Dark 12 Bias/Dark 21 Normalized FF 22 Sky FF 23 Dome FF 24 Internal FF 31 Arc Lamp
AIRMASS Non-Mandatory	Airmass (observed) (some systems use: O-AIRM)
H_SEEING Non-Mandatory (Floating)	FWHM Seeing in arcsec This is a preliminary definition, we will introduce later a more precise definition in order to precise (at least) (1) how the seeing was determined (2) describe the seeing as an ellipse (3) give the standard errors.
OBJECT Mandatory (Character string)	Standard identifier of the reference object, eg. NGC4486
RA Non-Mandatory	Position of the telescope Midas use this keyword, but other FITS systems may also use: OBSRA OBJCRA ... The definition is not widely accepted. In particular, the FITS headers of OHP observation do not clearly state the coordinate system associated. HyperLeda uses this keyword only in particular cases when importing an image.
DEC Non-Mandatory	See RA
RADECSYS	To be discussed
EQUINOX	To be discussed (Floating) In DSS: Julian Reference frame equinox (coded as Floating)
EPOCH	To be discussed In DSS: Epoch of observations; In VLA (1991AJ....101..127W) Epoch for RA, DEC The use of the EPOCH keyword is deprecated (Draft Standard NOST 100), EQUINOX
Dataset Processed Keywords
Name Status format	Description
H_DGAIN Mandatory	Detector gain, in electrons/ADU Note that the ADU levels, are the actual values on the frame, not the values produced at the time of the observation. This has been a mistake to adopt this definition, we will probably separate this keyword in two parts: the true H_DGAIN, kept as a characteristics of the detector, and the flux scale. This will have to be discussed together with the flux calibration...
H_DBIAS Mandatory	Bias, in ADU Note that the ADU levels, are the actual values on the frame, not the values produced at the time of the observation. If the bias has been subtracted, H_DBIAS will be null. Same mistake as for H_DGAIN
H_DSATU Mandatory	Saturation level, in ADU Same mistake as for H_DGAIN
H_AXISn Mandatory (Integer) n=1,NAXIS	Type of coordinate for axis n Code Meaning 0 Not precised 1 Spatial dimension 2 Wavelength 3 Order 4 Time/Age The type of coordinate is mainly usefull for uncalibrated frames. It is partly redundant with CTYPEn after a frame is wavelength calibrated
Frame Processed Keywords
Name Status format	Description
Keywords related to the world coordinate system (WCS) The WCS is attached to the Natural Coordinate System (ie. pixel coordinates) By convention in FITS, the natural coordinates refer to the center of the pixels, ie. the coordinate of the center of pixel "i" is "i" and this pixel extend over the range [i-0.5; i+0.5]. Pixels are numbered from 1 to NAXISn. In principle, in the LSS context, axis 1 is the wavelength coordinate (in Angstrom); axis 2 the space coordinate (in arcsec) In addition to the standard FITS keywords CTYPE CRPIX and CRVAL, the Pleinpot keywords H_AXISn will define the nature of the data along each axis: ie. spatial dimension or wavelength. This does not duplicate the information provided by CTYPE. Note: If the processing affect the NCS, eg. rebinning, the WCS will be changed.
CTYPEn Optional (Character*8)	Type of the physical coordinate on axis n Standard FITS values The standard values of CTYPEn are detailed in the papers by Griesen and collaborators (A&AS in press) For celestial coordinate system (CCS) and spectroscopic coordinate system (SCS) CTYPEn consist in 2 parts. The firts 4 characters specify the coordinate type and the last 4 describe the type of gridding. Examples are RA--TAN or WAVE-WAV respectively standing for "Right ascension with tangential projection" and "Wavelength with linear step". Standard FITS values presently used in Pleinpot RA--TAN DEC-TAN WAVE-WAV WAVE-LOG Additional values DETECTOR Coordinates in the system of the detector POSITION Position along the slit for a spectrum ORDER For echelle spectra, number of the order AGE For the evolutive template spectra Other values may be used, but will not be recognized (yet). This list will probably be extended to include more elaborated coordinate systems (eg. CTYPE1 = RA-TAN, see the proposal for wcs
CUNITn Optional (Character*16)	Unit of coordinate The units mus be written as specified in Griesen and Calabretta (A&AS in press) Unit values presently used PIXEL MICRON arcsec 10**(-10)m log(10**(-10)m)
CRPIXn Mandatory (Floating)	Location along the axis "n" of the reference point
CRVALn Mandatory (Floating)	Value of the "n" coordinate of the reference pixel
CDELTn Mandatory (Character string)	Unit/pixel Unit is specified in CTYPEn
BUNIT Non-Mandatory (Character string)	Unit of the data (Count, ADU, JY, Mag/Arcsec^2...)
DATAMIN Non-Mandatory (Character string)	Minimum valid physical value represented
DATAMAX Non-Mandatory (Character string)	Maximum valid physical value represented
Keywords related to the astrometric coordinate system (ACS) The ACS is attached to the WCS For the moment we will consider only a linear mapping betwen astrometric and frame coordinates (for both LSS and BBI) but this should soon evolve toward Sky World Coordinate Systems
H_REFRA Mandatory (Float)	RA (1950) of the reference point
H_REFDEC Mandatory (Float)	DEC (1950) of the reference point
H_REFPn Mandatory (Float) n=(1,2)	Position (world coordinates) of the reference point on axis "n"
Keywords related to the detector coordinate system (DCS) The DCS is attached to the WCS, it is the NCS of the detector. The DCS is intended to allow to retrieve the location of any pixel of the current frame on the detector. Since the frame may have been processed through non-linear rebinning (in particular wavelength calibration), the conversion from NCS to DCS is in general not simple. At present, we will only keep an information about the rebinning. H_REBINn give the binning factor. If non-linear transformation were applied, H_REBINn take a negative value and give the "mean" rebinning factor. The information about the extracted region, rotation, fip... is not kept, it sould be described in the AAAReadMe file. If this information appears useful, the transformation matrix and reference point may be coded in a future version...
H_REBINn Mandatory (Floating)	Binning factor between pixels on the current frame and detector pixels. [dpx/pixel]. dpx stands for "detector pixel" For example, if the processing resulted in a 2x2 rebinning (ie. converting an original 1024x1024 frame to 512x512), H_REBIN1 = HREBIN2= 2.
H_IDENT Non-Mandatory (Character string)	Identification comment of this frame It is usually initialized to the original value of the OBJECT keyword as recorded during the observations. OBJECT may then be changed to a standard identifier.
Other keywords
H_NCORLn Mandatory (Floating)	Noise correlation length. Pixels.
H_WCALIB (Character)	Pointer to the wavelength calibration relation
H_FCAPHY (Character)	Pointer to the flux calibration relation between instrumental and physical fluxes
H_FCANOR (Character)	Pointer to the flux calibration relation between instrumental and continuum-normalized fluxes
H_WLINCA (Character)	Pointer to a catalogue of spectral lines
H_CHARCj Non-Mandatory (Floating)	Characteristic curve. By default the characteristic curve is considered linear
H_WRESOL Mandatory (Floating)	Spectral resolution. FWHM of the arc-line located at wavelength H_WLINE
H_WLINE Mandatory (Floating)	Wavelength where the spectral resolution has been measured, in A.
Catalogue of objects An observation frame may contain several astronomical objects stored in a catalogue of objects At present, sice we are dealing with only a few object per field (at generaly onely one), the catalogue of object is coded as a series of keywords. In the future it may become possible to store it as a separate extension. A particular object may be selected in the catalogue, it become the "current" object, identified by the OBJECT keyword. This keyword is coupled with OBJECT which identify the object centered at this position. Using the identifier, HyperLeda will find the absolute astronomical coordinates of the reference point and hence define the absolute astrometric system of the frame
H_RADIUS Mandatory (Characters)	Radius of the current object along axis "n", in arcsec.
H_OBJPn Mandatory (Characters)	Position of the current object along axis "n", in pixels
H_OCAjjj Mandatory (Characters)	Record in the catalogue of object. "jjj" is a running number. It contains 4 fields: (1) Standard idntifier of the object, (2,3) X-Y position of the object, in world coordinates, (4) radius of the object (in arcsec).
Related frames keywords A frame may have several related frames; eg. the Arc exposures taken before and after, the flatfield used (or to be used), a series of exposures on template stars... The "related frames" are identified by their filename. It may be the absolute path or a relative path, in this latter case it is relative to the location of the current file (not to the current directory where the program is executed). The filename must conform to the "extended syntax" adopted in Pleinpot, this syntax allow in particular to access to: disk files, files in the HFA, URL and a couple of other things. See the Pleinpot documentation. At present, the "related frames" keywords cannot contain a pipeline command (problems of recursivity, it will be solved one day). To reference a file in the HFA, the prefix: fa: is used, for example: fa:L93111HP1/00147
H_AFR000 Mandatory (String)	Current frame, for example: fa:L93111HP1/00147
H_AFRjjj Mandatory (String)	Other frames on the same object, with the same setup in the same dataset (ie. frames which can be combined together)
H_ASP001 Mandatory (String)	file identifier of the bias
H_ASP002 Mandatory (String)	Normalized Flat-field
H_AAR000 Mandatory (String)	Reference arc (ie. the one used for the wavelength calibration)
H_AAR001 Mandatory (String)	Arc taken before the current observation (same setup, ie. position of the telescope, rotation of the spectrograph...)
H_AAR002 Mandatory (String)	Arc taken after the current observation
H_ATPjjj Non-Mandatory (String)	Template observations related to the current frame
Processing History Pleinpot maintains a set of "Processing History" Keywords in order to trace the processing along the pipeline. These keywords are prefixed H_P. Presently, we have defined H_P related to the calibration.
H_AHIST Non-Mandatory (Character)	Describes the steps of the processing Ante-history, ie. history before the file was stored in the archive. The symbolic codes of the processing are written in the chronological order, separated by "/". eg. FFC000/WCA000/XTO001/ The number after the command code point to a keyword describing the parameter of the corresponding processing. For instance, XTO001 points to the keyword H_XTO001
H_PHIST Non-Mandatory (Character)	Describes the steps of the processing Processing-history. ie. the commands executed on the pipeline after de-archiving. Same syntax as H_AHIST
H_PSTATU Not yet defined (Integer)	Error status along the processing To be discussed
H_FFCnnn Non-Mandatory (Character)	Parameters of the FlatFielding (physical calibration) Target of the item H_FFCnnn of the H_AHIST or H_PHIST keywords.
H_WCAnnn Non-Mandatory (Character)	Parameters of the wavelength calibration Similar coding as H_FFCnnn
H_XTOnnn Non-Mandatory (Character)	Parameters of the subimage extraction around object Similar coding as H_FFCnnn
H_XTCnnn Non-Mandatory (Character)	Parameters of the extraction of a sub-image specified by coordinates Similar coding as H_FFCnnn
H_WRSnnn Non-Mandatory (Character)	Parameters of the wavelength resampling Similar coding as H_FFCnnn
H_VSGnnn Non-Mandatory (Character)	Parameters of the VSG pipeline function Similar coding as H_FFCnnn
Other standard keywords: Comment and History
COMMENT Non-mandatory (Character string)	May contain any ASCII text. Any number of COMMENT records can appear in headers. Not used by Pleinpot/HyperLeda. Given for human readability
HISTORY (string) Non-mandatory (Character string)	May contain any ASCII text. Any number of HISTORY records can appear in headers. Not used by Pleinpot/HyperLeda. Given for human readability

Type of data: BTYPE