OGIP Calibration Memo CAL/GEN/92-021

(VIGVERSN = 1992a)
Ian M George & Ron S Zellar
Mail Code 668,

Version: 1994 Aug 09


Ths document describes the standard format adopted by the OGIP for the storage of vignetting functions of an instrument as a function of energy, and position.
Intended audience: primarily OGIP 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 04 All Separation from CAL/GEN/92-003
1993 Nov 24 All Added HDUCLASn info
1994 Aug 09 All General Review/up-dates
2004 Apr 01 All made compatible with tth


The following documents may also be of use:

1  Introduction

A calibration dataset containing the Vignetting Function is only required for imaging instruments using mirrors1. However within the OGIP caldb, the term Vignetting Function can mean one of two things: These are distinguished within the caldb using different codenames for the value of the mandatory CCNMxxxx keyword (see below).

1.1  Storage Options

In both Cases A & B above, a Vignetting function dataset consists of a 3-dimensional grid, 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). Both Cases A & B can thus be accomodated within the data formats outlined below (with the only difference being the value of the CCNMxxxx keyword).

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.
In both Cases A & B above, virtual calibration files are recommended (see Sections 1.3 & 3).
Case A is at all times prefered.
Prior to launch, the effects of vignetting and obscuration at off-axis positions are usually measured at a (limited) number of photon energies during ground calibration experiments and/or combined with theoretical (e.g. ray-tracing) models to produce the off-axis correction factors. It is recommended that the Vignetting function and Obscuration factors be stored separately in the form of CCNMxxxx = VIGNET (i.e. Case A above) and CCNMxxxx = OBSCFACT datasets.
The Vignetting function (either alone, or including the effects of obscuration) cannot be directly 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 vignetting function, 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 vignetting function, h/w teams are urged to isolate and also supply an updated vignetting dataset/algorithm to the HEASARC.

1.3  Dataset vs Task Summary

It is often fairly straightforward to parameterize the Vignetting Function of an instrument. As a result such a calibration dataset may often be more easily and economically storted as a virtual calibration file, and an associated standalone s/w task (see CAL/GEN/92-003). Wherever possible, this is recommended. The requirements for such virtual calibration files are discussed in Section 3.

1.4  Software Considerations

Data Files:
In both Cases A & B outlined above, interpolation between the θXMAXMA grid points is usually required. By default, downstream software will use a simple 2-dimensional linear interpolation when calculating the Vignetting Function between θXMAXMA grid points. Thus the θXMAXMA grid should be of sufficient resolution to enable this to be reasonable approximation.
As discussed in 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:
No specific issues.

1.5  Relationships to Other Calibration Datasets

Downstream s/w should assume further calibration input is required for a Vignetting Function dataset under the following conditions:
A Vignetting Function dataset is used in the construction of the following calibration datasets:

2  Data File Formats

The dataset file formats currently allowed are:

2.1  The Vignetting Factor Extension (VIGVERSN = 1992a)

One extension in BINTABLE format for each telescope. The format adopted is identical to that adopted for effective areas (see CAL/GEN/92-019; George & Zellar 1992a), but with the column containing the Effective Area replaced by one containing the Vignetting factor. Thus again the BINTABLE only has a single row, using arrays for the 5 necessary columns.
Extension Header
Beyond the standard FITS keywords required, the following keywords/values are mandatory: and the following keywords/values are mandatory for CIF purposes: and the following mandatory 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. Vignet, a fixed-length REAL vector (array, each element within which is 4-byte) containing the vignetting + obscuration factor at each E,θXMAXMA grid point.
    The FITS column name is VIGNET.
    The order of data storage is Vignet (E,θXMAXMA), where E represents the Elow and Ehigh arrary (see below).

These are summarized in Table 1.
Table 1: Summary of the OGIP format for Vignetting functions (VIGVERSN = 1992a).

to (filename).(ext)

HDUVERS1: 1.0.0
HDUVERS2: 1.1.0
EXTNAME : VIGNET (suggested, not required)
Description: Vignetting functions (normalized to unity on-axis) 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 Vignetting
bounds bounds anglesangles function
Elow Ehigh θXMA φXMA Vignet
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

Standalone tasks to perform the following tasks are currently allowed:

3.1  VCF Requirements

See CAL/GEN/92-003 & CAL/GEN/92-013.
Extension Header
Beyond the standard FITS keywords required, the following keywords/values are mandatory: along (if desired) with those keywords/values mandatory for CIF purposes as given in within the appropriate sub-section of Section 2, with the exception of: plus those required for all virtual files listed in CAL/GEN/92-003, and the following mandatory keyword to supply further information:
Data Format:
See CAL/GEN/92-003 and CAL/GEN/92-013. The number and type of parameters specified depends solely on the requirements of the associated standalone task.

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 OGIP 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 a VIGVERSN=1992a dataset. The vignetting 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 VIGNET 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  = 'VIGNET  '           / Vignetting dataset
TFORM4  = '10206E  '           / data format of the field: 4-byte REAL
EXTNAME = 'VIGNETTING'         / name of this binary table extension
HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUCLAS1= 'RESPONSE'           / dataset relates to instrument response
HDUVERS1= '1.0.0   '           / Version of family of formats
HDUCLAS2= 'VIGNET  '           / dataset is an effective area
HDUVERS2= '1.1.0   '           / Version of format (OGIP memo CAL/GEN/92-021)
HDUCLAS3= 'TOTAL   '           / (includes both vignetting & obscuration)
CSYSNAME= 'XMA_POL '           / spatial coord system used in this dataset
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 VIGNET array
1CTYP4  = 'ENERGY  '           / Axis of 1st dimension of VIGNET array
2CTYP4  = 'THETA   '           / Axis of 2nd dimension of VIGNET array
VIGVERSN= '1992a   '           / OGIP classification of FITS format
HISTORY    Extension written by WTVIG1 1.0.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= 'TVIGNET '           / 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 Vignetting (including obscuration); 729 energies vs 14 theta'
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_2.asc
COMMENT     supplied by Steve Snowden (ROSAT GOF, NASA/GSFC).
COMMENT     The area_b_2.asc file consists of the (total) spectral
COMMENT     response for PSPCB. The current dataset was therefore created
COMMENT     by DIVIDING the area_b_2.asc dataset by:
COMMENT        the gas efficiency:             pspc_v1.gas_eff
COMMENT        the window transmission:        pspcb_v1.wind_trans
COMMENT        AND then by the on-axis effective area
COMMENT           (from within the area_b_2.asc dataset)
COMMENT     The area_b_2.asc dataset has also been converted to
COMMENT     an OGIP FITS format as is stored in file
COMMENT        pspcb_v2.spec_resp
COMMENT     (The pspcb_v1.spec_resp dataset is thought to be identical
COMMENT      to that known as SASS_AREA_B_NEW2.FITS by the SASS s/w)


George, I.M. & Zellar, R.S., 1992. OGIP Calibration Memo CAL/GEN/92-003. f
George, I.M. & Arnaud, K.A., 1993. OGIP Calibration Memo CAL/GEN/92-002a
(addendum to CAL/GEN/92-002). f
George, I.M., Arnaud, K.A., Pence, W. & Ruamsuwan, L., 1992. Legacy, 2, 51.
(CAL/GEN/92-002 f)
George, I.M., Zellar, R.S. & Pence, W., 1992. OGIP Calibration Memo CAL/GEN/92-011. f
George, I.M., Pence, W. & Zellar, R.S., 1992. OGIP Calibration Memo CAL/GEN/92-008. f
George, I.M., Zellar, R.S. & White, N.E., 1992. OGIP Calibration Memo CAL/GEN/92-013. f
George, I.M. & Zellar, R.S., 1992. OGIP Calibration Memo CAL/GEN/92-019.
George, I.M. & Zellar, R.S., 1992. OGIP Calibration Memo CAL/GEN/92-022.
f available on-line from the anon ftp account on legacy.gsfc.nasa.gov.


1Collimated instruments only require a calibration dataset describing the Obscuration factor as a function of off-axis position (see CAL/GEN/92-022).

File translated from TEX by TTH, version 3.49.
On 8 Apr 2004, 10:43.