OGIP Calibration Memo CAL/GEN/92-019

(EARVERSN = 1992a)

Ian M George & Ron S Zellar
Mail Code 668,
MD 20771.

Version: 1995 Jul 31


Ths document describes the standard format adopted by the HEASARC for the storage of the effective area of an instrument as a function of energy, and position.

Intended audience: primarily HEASARC programmers & hardware teams.

Log of Significant Changes

Release Sections Changed Brief Notes
1992 Jul 24 First Draft (within memo CAL/GEN/92-003)
1993 Oct 03 All Separation from CAL/GEN/92-003
1993 Nov 25 All Added HDUCLASn info
1994 Jul 24 2.2 Clarified CSYSNAME conventions
1994 Aug 09 All General Review/up-dates
1995 Jan 19 All Made compatible with LaTeX2HTML software
2004 Apr 01 All Made compatible with tth


The following documents may also be of use:

1  Introduction

Historically, the term 'Effective Area' has been used somewhat ambiguously. Within the HEASARC caldb, the term is reserved exclusively to denote that of the telescope mirror/collimator assembly (only), but including any vignetting and obscuration effects applicable for off-axis angles of incidence1.

1.1  Storage Options

In the general case an Effective Area calibration dataset consists of a 3-dimensional grid, EffArea, with 1 axis giving the photon energy (E), and 2 axes defining the position relative to the optical axis - invariably the off-axis angle (θXMA) & azimuthal angle (φXMA).

However, there are two basic methods in which this information can be stored within the caldb:

Method A provides the clear advantage to users and s/w requiring an off-axis Effective Area that all the necessary information is contained within a single dataset. However, this method has the potential disadvantage that the Total Vignetting function (including the effects of vignetting and obscuration) has been folded in, requiring the entire dataset to be recreated if (say) the Total Vignetting function only is improved in-flight. By the same token Method B has a disadvantage to users and s/w requiring an off-axis Effective Area that additional calibration information is required - namely the Total Vignetting function, Vignet, appropriate for the desired off-axis position and energy range, i.e. 
EffArea (E,θXMAXMA)
EffArea (E,0,0)
× Vignet (E,θXMAXMA)
However, since the on-axis Effective Area is sometimes known to a higher accuracy than the Total Vignetting function, the advantage of Method B is that the isolation of the latter component means that updates can be made without the necessity of updating the (on-axis) Effective Area BCF. The pros and cons of the two methods are further discussed in Section 1.2.

The data formats described in Section 2 are able to accomodate both Methods A& B, with the CBDnxxxx keyword(s) providing downstream software with the necessary information as to whether further calibration i/p (i.e. off-axis Vignetting & Obscuration factors) is required.

1.2  Dataset Origins & Storage Recommendations

The construction, format used (within the limitations discussed here) and delivery of the data to the HEASARC (including any updates) is the responsibility of the h/w teams and/or GOF. However, below, are the recommendations of the HEASARC calibration team based on their experience.

For completeness and maximum flexibility, in the case of instruments for which the calibration is well understood and stable, the HEASARC would prefer that an effective area dataset is stored using Method A, but that the associated vignetting and obscuration functions are also stored in CCNMxxxx = VIGNET and CCNMxxxx = OBSCFACT datasets.

Prior to launch, the on-axis effective area is usually accurately measured at a (limited) number of photon energies during ground calibration experiments, and combined with a theoretical model to produce a good estimation of the effective area at all energies within the required band. The effects of vignetting and obscuration at off-axis positions are also measured at a (usually more limited) number of photon energies during such experiments and/or combined with theoretical (e.g. ray-tracing) models to produce the off-axis correction factors. Thus in most cases, Method B (Section 1.1) is the natural method of storing the necessary calibration datasets at this time.

The effective area of the optics only cannot be measured in-orbit. Instead, observations of standard cosmic sources (e.g. the Crab) combined with spectral modelling enables the Spectral Response of the instrument (i.e. the effective area of the optics multiplied by the transmission of any filters & windows and by the detector efficiency as a function of energy) to be determined. The results of such calibration observations should be stored as a CCNMxxxx = SPECRESP dataset. However, should such measurements reveal that a discrepancy with previous calibrations which is identified with (or interpreted as) a mis-calibration of the effective area of the optics, h/w & GOF teams are urged to isolate and also supply an updated Effective Area dataset to the HEASARC. Since such discrepancies are often the result of uncertainties in the Vignetting function, Method B (Section 1.1) is recommended for initial in-flight datasets also. Only when the calibration is considered to be well understood and stable, is it recommended that the Effective Area information be reformatted to use Method A. When such a time occurs should be the descision of the h/w & GOF teams, and a new Effective Area BCF using Method A (and any new CCNMxxxx = VIGNET and CCNMxxxx = OBSCFACT BCFs necessary) be delivered to the HEASARC.

1.3  Dataset vs Task Summary

Due to the complexity of the Effective Area of an instrument as a function of energy (as the result of sharp discontinuities due to atomic processes etc. ), such a calibration dataset is not easily parameterized. Thus, whilst theoretically possible, it is recommended that an Effective Areas dataset is not described by a virtual calibration file.

1.4  Software Considerations

Data Files:
In both Methods A & B outlined in Section 1, interpolation between the θXMAXMA grid points is usually required. By default, downstream software will use a simple 2-dimensional linear interpolation when calculating the Effective Area between θXMAXMA grid points. Thus the θXMAXMA grid should be of sufficient resolution to enable this to be a reasonable approximation.

As discussed in the general guidelines for calibration files (CAL/GEN/92-003), it is strongly recommended that the energy grid is of sufficient resolution and carefully chosen such that interpolation of this parameter is not required. However, in cases where interpolation is required, as simple 1-dimensional linear interpolation will be performed (which will clearly be inaccurate close to sharp features).

Virtual Files:
Not applicable (see Section 1.3).

1.5  Relationships to Other Calibration Datasets

Downstream s/w should assume further calibration input is required for an Effective Area dataset under the following conditions:

An Effective Area dataset is used in the construction of the following calibration datasets:

2  Effective Data File Formats

The HEASARC FITS Working Group (HFWG) Header-Data Unit (HDU) keywords and values for this type of dataset are:

These are valid for all datasets described in this section, and should be present in the header of the extension containing the EffArea dataset.

2.1  Summary of Effective Area file formats versions

The following versions of file formats for an EffArea dataset have been defined:

2.2  The Effective Area Extension (HDUVERS = '1.0.0')

One file for each telescope containing a single BINTABLE FITS extension. The BINTABLE only has a single row, using arrays for the 5 necessary columns.

Note: this format was formally known as EARVERSN = '1992a', and is still occasionally refered to as such.

Extension Header
Beyond the standard FITS keywords required, and the HDU keywords/values given in Section 2, the following keywords/values are mandatory:

and the following keywords/values are mandatory for CIF purposes (see CAL/GEN/92-011): and the following are optional to supply further information:

Data Format:
The data within the extension is organised as a BINTABLE with the following columns:

  1. Elow, a fixed-length REAL vector (array, each element within which is 4-byte) containing the lower energy bounds of the energy bins.
    The FITS column name is ENERG_LO.
    The recommended units are keV.

  2. Ehigh, a fixed-length REAL vector (array, each element within which is 4-byte) containing the upper energy bounds of the energy bins.
    The FITS column name is ENERG_HI.
    The recommended units are keV.

  3. θXMA, a fixed-length REAL vector (array, each element within which is 4-byte) containing the off-axis angles.
    The FITS column name is THETA (but see below)
    The recommended units are arcmin.

  4. φXMA, a fixed-length REAL vector (array, each element within which is 4-byte) containing the azimuthal angles.
    The FITS column name is PHI (but see below).
    The recommended units are arcmin.

  5. EffArea, a fixed-length REAL vector (array, each element within which is 4-byte) containing the effective area at each E,θXMAXMA grid point.
    The FITS column name is EFFAREA.
    The order of data storage is EffArea (E,θXMAXMA), where E represents the Elow and Ehigh arrary (see below).
    The recommended units are cm2.

These are summarized in Table 1.

Table 1: Summary of the OGIP format for Effective Areas (EARVERSN = 1992a).

to (filename).(ext)

HDUVERS: 1.0.0
EXTNAME : EFFECTIVE AREA (suggested, not required)
Description: Effective areas (including vignetting and obscurration effects) as a function of energy and off-axis & azimuthal angle.
An alternate spatial coordinate frame may also be used (see text).
Optional columns containing the statistical and systematic error arrays are not shown.
1 23 4 5
Low energy High energyOff-axis Azimuthal Effective Areas
bounds bounds anglesangles
Elow Ehigh θXMA φXMA EffArea
format of each column
4-byte 4-byte 4-byte 4-byte 4-byte
real real real real real
array array array array array
total number of elements per row
i i j k i ×j ×k
column name

Points to Note & Conventions

3  Virtual File Formats & Allowed Standalone Tasks

As noted in Section 1.3, given the difficulty parameterizing the Effective Area in energy-space, it is not recommended that such datasets are stored as Virtual Calibration Files.

4  Related Software

The following list of subroutines/tasks are available:

5  Example FITS headers

Below are several examples of files currently available within the HEASARC caldb. Note that the authors of datasets are encouraged to supply copious COMMENT cards to aide human readers.

5.1  ROSAT 

Follows is the header from an extension containing an EARVERSN=1992a dataset. The effective area data is stored in column 4 and is a function of 729 energies and 14 off-axis angles, THETA. There is no PHI dependence for this dataset. From the iCTYP4 (and also implied by the TDIM4) keyword, it can be seen that ENERGY is the 1st axis/dimension of the EFFAREA data array, and THETA the 2nd axis/dimension.

XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                46712 / width of table in bytes
NAXIS2  =                    1 / number of rows in table
PCOUNT  =                    0 / size of special data area
GCOUNT  =                    1 / one data group (required keyword)
TFIELDS =                    4 / number of fields in each row
TTYPE1  = 'ENERG_LO'           / Lower boundaries of energy bins
TFORM1  = '729E    '           / data format of the field: 4-byte REAL
TUNIT1  = 'keV     '           / physical unit of field
TTYPE2  = 'ENERG_HI'           / Upper boundaries of energy bins
TFORM2  = '729E    '           / data format of the field: 4-byte REAL
TUNIT2  = 'keV     '           / physical unit of field
TTYPE3  = 'THETA   '           / Spatial coord grid: dimension 1
TFORM3  = '14E     '           / data format of the field: 4-byte REAL
TUNIT3  = 'arcmin  '           / physical unit of field
TTYPE4  = 'EFFAREA'            / Effective Area dataset
TFORM4  = '10206E  '           / data format of the field: 4-byte REAL
TUNIT4  = 'cm**2   '           / physical unit of field
EXTNAME = 'EFFECTIVE AREA'     / name of this binary table extension
HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUDOC  = 'CAL/GEN/92-019'     / format definition document
HDUVERS = '1.0.0   '           / Version of family of formats
HDUCLAS1= 'RESPONSE'           / dataset relates to instrument response
HDUCLAS2= 'EFF_AREA'           / dataset is an effective area
CSYSNAME= 'XMA_POL '           / spatial coord system used in this dataset
1CTYP4  = 'ENERGY'             / 1st axis of EFFAREA is energy
2CTYP4  = 'COORD-1'            / 2nd axis of EFFAREA is coord-1
TELESCOP= 'ROSAT   '           / mission/satellite name
INSTRUME= 'XRT     '           / instrument/detector name
FILTER  = 'NONE    '           / filter in use
COMMENT   Dataset assumed to be independent of PHI
TDIM4   = '(729,14)'           / Ordering of n-d EFF_AREA array
1CTYP4  = 'ENERGY  '           / Axis of 1st dimension of EFF_AREA array
2CTYP4  = 'THETA   '           / Axis of 2nd dimension of EFF_AREA array
EARVERSN= '1992a   '           / OGIP classification of FITS format
HISTORY    Extension written by WTEAR1 1.1.0
COMMENT   The following keywords are required for the OGIP CALDB
CCLS0001= 'BCF     '           / OGIP class of calibration file
CDTP0001= 'DATA    '           / OGIP type of dataset (DATA, TASK etc)
CCNM0001= 'EFFAREA '           / OGIP codename for this type of cal file
CVSD0001= '01/06/90'           / Dataset validity start date (UTC)
CVST0001= '00:00:00'           / Dataset validity start time (UTC, of day CVSD)
CDES0001= 'XRT Effective Area (version 1); 729 energies vs 14 off-axis angles'
CBD10001= 'THETA(0-60.0)arcmin'/ dataset parameter boundary
CBD20001= 'PHI(0-360)deg'      / dataset parameter boundary
CBD30001= 'ENERG(0.0546-3.01)keV'/ dataset parameter boundary
COMMENT   NOTES: 1994 Jul 21       (Ian M George, HEASARC)
COMMENT   ------------------
COMMENT   This dataset was converted to OGIP FITS format by 
COMMENT   Ian M George (HEASARC) from the ASCII file 
COMMENT          area_b_1.asc 
COMMENT   supplied by Steve Snowden (ROSAT GOF, NASA/GSFC). 
COMMENT   The area_b_1.asc file consists of the (total) spectral 
COMMENT   response for PSPCB. The current dataset was therefore created 
COMMENT   by DIVIDING the area_b_1.asc dataset by:
COMMENT      the gas efficiency:             pspc_v1.gas_eff
COMMENT      the window transmission:        pspcb_v1.wind_trans
COMMENT   The area_b_1.asc dataset has also been converted to 
COMMENT   an OGIP FITS format as is stored in file
COMMENT      pspcb_v1.spec_resp


Information regarding on-line versions of any of the following references with an OGIP Memo number (ie documents starting OGIP/.. or CAL/..) can most easily be found via the WorldWide Web by following the links from the URL:

Most OGIP Calibration Memos of general community interest will eventually appear as articles in Legacy, but are also available on request from The Office of Guest Investigator Programs, Code 668, NASA/GSFC, Greenbelt, MD 20771, USA.

George, I.M. & Zellar, R.S., 1992.

George, I.M., Arnaud, K.A., Pence, W. & Ruamsuwan, L., 1992. Legacy, 2, 51.

George, I.M., & Arnaud, K.A., 1992.

George, I.M., Zellar, R.S. & Pence, W., 1992.

George, I.M., Pence, W. & Zellar, R.S., 1992.

George, I.M., Zellar, R.S. & White, N.E., 1992.

George, I.M. & Zellar, R.S., 1992.

George, I.M. & Zellar, R.S., 1992.


The following useful links are available (in the HTML version of this document only):


1The result of multiplying the Effective Area of the mirror/collimator assembly by the transmission due to any filters & detector windows along the optical path, and by the efficiency of the detector, is referred to as the Spectral Response of the instrument within the HEASARC caldb

File translated from TEX by TTH, version 3.13.
On 5 May 2004, 09:33.