Subject: OFWG Recommendation R11 - Exposure-time related keywords in OGIP FITS files

From: "Ian M George, Code 668, NASA/GSFC, USA (Usque ad mortem bibendum)" <GEORGE at lheavx.gsfc.nasa.gov>
Date: Wed, 13 Jul 1994 10:33:27 -0400 (EDT)

At a meeting on 1994 Jul 06, the OGIP FITS Working Group (OFWG) 
raised its earlier preliminarily recommendation p20.1 regarding 
exposure-time related keywords for OGIP FITS files to the lofty status 
of a full recommendation:

---------------------------------------------------------------------------
OFWG Recommendation R11

	------------------------------------------------------
	| EXPOSURE-TIME RELATED KEYWORDS FOR OGIP FITS FILES |
	------------------------------------------------------
					  Version: 1994 May 11

Below are two sets of FITS keywords & definitions: Table 1 lists the 
keywords which should be used in OGIP files to store various 'exposure
times' associated with a FITS dataset; Table 2 lists the related keywords 
which should be used to store various correction factors to these times.

This set of keywords & definitions was constructed from the most common 
usage within X- & Gamma-ray FITS files. The lack of a consistent naming 
convention most probably reflects the fact that most of these keywords 
were devised by different people in different places at different times.

The OFWG strongly recommends that these keywords (only) be used to store 
the various quantities within OGIP FITS files. It should be noted that 
only those keywords/quantities considered necessary must be included 
in the header of a given FITS dataset. However the OFWG suggests that 
where possible all know quantities are included in the header.

	TABLE 1 - "Exposure-time" related keywords
	******************************************

 Keyword   			Meaning & Notes
 -------   			---------------

 TELAPSE  is the time interval (in seconds) obtained as difference between 
          the start and stop times of an observation. Any gaps due to Earth 
          occultation, or high background counts and/or other anomalies, 
	  are included.

 ONTIME   is the total "good" time (in seconds) on 'source'. If a 'Good 
          Time Interval' (GTI) table is provided, ONTIME should be calculated 
          as the sum of those intervals. Corrections for instrumental 
	  'dead time' effect are NOT included.

 LIVETIME is the total time (in seconds) on source, corrected for the 
          'total' instrumental dead time effect. The ratio LIVETIME/ONTIME 
          therefore gives the dead time correction value (which hence 
	  lies in the range 0.0 to 1.0). 
 
 EXPOSURE is the total time (in seconds) on source, corrected for any 
          relevant quantity used to calculate the corrected count rate.
          The value can include correction which are not directly 
          related with time (e.g. collimation efficiency or vignetting).
          This keyword used in the header of FITS file, is a mean value 
          when appropriate.

	TABLE 2 - Keywords for "Exposure-time" correction factors
	*********************************************************
 Keyword   			Meaning & Notes
 -------   			---------------

 DEADC    is the total correction factor for any dead time effect 
	  (ie LIVETIME/ONTIME), and lies in the range 0.0 to 1.0. 
          Thus the multiplication of this value by the ONTIME value 
          gives the 'effective' integration time or LIVETIME (TIMEDEL in 
          the case of a light curve). Since the total dead time of a 
	  given dataset can be the result of a multitude of 
	  instrumental/processing effects (especially related to the 
	  particular experiment, and/or processing by an onboard computer, 
          and/or spacecraft operations), it is recommended that as 
	  well as including the total correction factor in the DEADC 
	  keyword, instrument-specific keywords are used to keep a record 
	  of the original value for the individual correction factors.

 ERRCOR   Corrections are usually applied to the stored counts and the 
	  error on those counts. However, in some cases the errors can need 
	  an extra correction, different to that applied to the counts. 
          The ERRCOR keyword contains this extra value. The value is 
	  unitless.   
          Es. If the dead time is related to the sampling of the on board 
          computer, it has been found that different correction are needed
          for counts (count/s) and errors. This can be generalized to all 
          cases in which the error needs to be treated differently compared 
          to the counts. 

 VIGNET   is the correction factor for the collimator response or vignetting 
	  function (depending upon the instrument) such as to enable the 
	  scientific dataset (eg lightcurve) to be rescaled to that which 
	  would have been obtained had the source been observed at the 
	  angle of peak collimator response (for collimated instruments) 
	  or on-axis (for instruments employing imaging optics).
	  In both cases the value of VIGNET should lie in the range 0.0 - 1.0,
	  and thus be the factor by which the scientific dataset should be 
	  divided in order to obtain the equivalent on-axis value.
	  In both cases (but especially in the case of imaging optics)
	  the correction factor can be a function of energy, and thus can 
	  only be used if a useful mean value can be defined.
	  In the case of imaging optics, VIGNET should contain the 
	  the total correction factor due to vignetting and any 
	  (energy-independent) reduction in collecting area resulting from 
	  obscuration by the near-side of the mirror, support structures etc.
	  It should be noted that historically these correction factors have 
	  often [naturally] been referred to by different names, and 
	  sometimes as the reciprical of the value defined above.

----------------------------------- END ---------------------------------- 
Ian M George 					
NASA/GSFC OFWG
1994 Jul 11