OGIP Calibration Memo CAL/GEN/92-021

OGIP Calibration Memo CAL/GEN/92-021

THE OGIP FORMAT FOR "VIGNETTING" FUNCTIONS
(VIGVERSN = 1992a)

Ian M George & Ron S Zellar

Mail Code 668,
NASA/GSFC,
Greenbelt,
MD20771.

Version: 1994 Aug 09

SUMMARY

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
Date

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

1 Introduction

A calibration dataset containing the Vignetting Function is only required for imaging instruments using mirrors¹. However within the OGIP caldb, the term Vignetting Function can mean one of two things:

Case A: The vignetting function of the mirror assembly only as a function of energy and off-axis position (normalized to unity on-axis);
Case B: The vignetting function of the mirror assembly (as for Case A), but multiplied by the (energy-independent) obscuration factor (or 'collimator response' or 'geometric vignetting function') appropriate for each off-axis position.

These are distinguished within the caldb using different codenames for the value of the mandatory CCNMxxxx keyword (see below).

Notes:

From the above definition, the Vignetting Function lies in the range 0 - 1.0. Thus when one wishes to convert (say) the observed count rate of an off-axis source to the count rate one would have expected had the source been observed on-axis, the observed count rate should be multiplied by the reciprocal of the appropriate off-axis Vignetting Function.

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.

General
In both Cases A & B above, virtual calibration files are recommended (see Sections 1.3 & 3).
Case A is at all times prefered.

Pre-launch
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.

Post-launch
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 θ_XMA,φ_XMA grid points is usually required. By default, downstream software will use a simple 2-dimensional linear interpolation when calculating the Vignetting Function between θ_XMA,φ_XMA grid points. Thus the θ_XMA,φ_XMA 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:

condition:
CCNMxxxx = VIGNET, indicating the contents of the Vignetting Function BCF datset does not include the effects of obscuration.
requirement:
a CCNMxxxx = OBSCFACT calibration dataset giving the obscuration factor at the requested off-axis position (see CAL/GEN/92-022).
alternative:
If no such calibration sets are available within the caldb, then either the user should be informed, and the s/w task stopped, or (if appropriate) a CCNMxxxx = SPECRESP dataset searched for within the caldb with the corresponding implications to the subsquent operation of downstream s/w.

A Vignetting Function dataset is used in the construction of the following calibration datasets:

A CCNMxxxx = EFFAREA dataset, containing the effective area of the optics (see CAL/GEN/92-019)
A CCNMxxxx = SPECRESP dataset, containing the total spectral response of an instrument (see George et al 1992, and CAL/GEN/92-002a).

2 Data File Formats

The dataset file formats currently allowed are:

HDUCLAS1/VERS1 = 'RESPONSE'/'1.0.0'
HDUCLAS2/VERS2 = 'VIGNET'/'1.1.0'
(this format is also known VIGVERSN = 1992a)
described in Section 2.1.

2.1 The Vignetting Factor Extension (VIGVERSN = 1992a)

Description:
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:

HDUCLASS = 'OGIP' - the name of the organization that defined this file format.
HDUCLASn - giving the HDUCLAS hierarchy for this format (with the values given above)
HDUVERSn - giving the HDUVERS hierarchy for this format (with the values given above)
TDIMnnn - the number of elements and ordering (see CAL/GEN/92-003) of each multi-dimensional array.
Only the VIGNET column here (with nnn=5 in the example below).
CSYSNAME - the spatial coordinate system in use (see CAL/GEN/92-003; George & Zellar 1992)
(CSYSNAME = XMA_POL is assumed in the example below)

and the following keywords/values are mandatory for CIF purposes:

TELESCOP - the name of the satellite/mission.
Allowed values are given in CAL/GEN/92-011.
INSTRUME - the name of the telescope mirror assembly.
Allowed values given in CAL/GEN/92-011.
CCLS0001 (=BCF) - the OGIP class of this calibration file
CDTP0001 (=DATA) - the OGIP class of the data type
CCNM0001 - the OGIP codename for the contents (see also CAL/GEN/92-011)
- CCNM0001 = VIGNET, if the vignetting function has not been multiplied by the energy-independent obscuration factor (i.e. Case A from Section 1);
- CCNM0001 = TVIGNET, if the dataset consists of the total vignetting function (i.e. includes the obscuration factor: Case B from Section 1).
  This is the default, and should be used in cases where no obscuration factor is necessary for an instrument.
CBDn0001 - the parameter limitation of the dataset (see below)
CVSD0001 - calibration validity start date
CVST0001 - calibration validity start time
CDES0001 - a descriptive string of the calibration dataset

and the following mandatory to supply further information:

VIGVERSN - the OGIP version of the FITS format in use (in this case 1992a)

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

E_low, 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.
E_high, 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.
θ_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.
φ_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.
Vignet, a fixed-length REAL vector (array, each element within which is 4-byte) containing the vignetting + obscuration factor at each E,θ_XMA,φ_XMA grid point.
The FITS column name is VIGNET.
The order of data storage is Vignet (E,θ_XMA,φ_XMA), where E represents the E_low and E_high arrary (see below).
(unitless).

These are summarized in Table 1.

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

Extension
to (filename).(ext)

HDUCLAS1: RESPONSE
HDUVERS1: 1.0.0
HDUCLAS2: VIGNET
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.
Format: BINTABLE

column
1	2	3	4	5

contents
Low energy	High energy	Off-axis	Azimuthal	Vignetting
bounds	bounds	angles	angles	function

E_low	E_high	θ_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
ENERG_LO	ENERG_HI	THETA	PHI	VIGNET

Points to Note & Conventions

The ordering of the columns is of course arbitrary, however that used here is recommended.
The rules and conventions concerning the energy grid (E_low & E_high) given in CAL/GEN/92-003 apply.
An alternate spatial coordinate frame may be used, in which case
- the values of the CSYSnnn keywords should be replaced by the appropriate string listed in CAL/GEN/93-003.
- and/or (if necessary) the THETA & PHI column names replaced by more suitable alternatives if a different coordinate notation is employed. In this case the CSYSNAME keyword is mandatory and should give the column names used.
It is strongly recommended that coordinate frames are not mixed within a given dataset.
The parameter-space limitations on the dataset involving the following pname strings are recommended to be specified via the CBDn0001 keywords:
- pname = THETA - giving the range of off-axis angle for which the dataset is valid;
- pname = PHI - giving the range of azimuthal angle for which the dataset is valid;
(or corresponding alternate values of pname if a different coordinate notation is employed) along with any other limitations the authors consider necessary.
Datasets in which Vignet is independent of either spatial coordinate should NOT contain the corresponding column. It is recommended that a COMMENT card is used within the header to explain this fact to human readers (eg see Section 5.1).
Alternative physical units are allowed for all columns of the table as long as they conform to the rules given in CAL/GEN/93-001. The same is true for the physical units associated with the CBDn0001 keywords.
The order of Vignet (E,θ_XMA,φ_XMA) whereby energy parameters changes fastest, and the azimuthal angle parameter slowest was chosen to facilitate access for the most common applications: interpolation in θ_XMA-space of Vignet vs E_low,E_high arrays. This ordering is further confirmed by the value of the mandatory TDIMnnn and iCTYPnnn keywords (where nnn is the column number, and i the axis number). The rules and conventions governing these keywords are given in CAL/GEN/92-003 (see also Section 5).
The optional arrays containing the 1σ statistical error associated with each element of Vignet (if required) should be contained in additional columns named STAT_MIN (for the negative error) and STAT_MAX (for the positive error).
Similarly, the optional arrays containing the 1σ fractional systematic error associated with each element of Vignet (if required) should be contained in additional columns named SYS_MIN (for the negative error) and SYS_MAX (for the positive error).
The rules and conventions governing such arrays (if present) are given in CAL/GEN/92-003. These arrays are provided here for completeness, and rarely either provided by the h/w teams or used by downstream s/w.

3 Virtual File Formats & Allowed Standalone Tasks

Standalone tasks to perform the following tasks are currently allowed:

Calculate the Vignetting Function, Vignet(E,θ_XMA,φ_XMA) (for both Cases A & B in Section 1) as a function of photon energy (E), for a given off-axis position θ_XMA,φ_XMA and range of energies.
Output:
The format of the o/p file should be one of the allowed data formats given in Section 2.
Notes:
None

3.1 VCF Requirements

Description:
See CAL/GEN/92-003 & CAL/GEN/92-013.

Extension Header
Beyond the standard FITS keywords required, the following keywords/values are mandatory:

CSYSnnn - the spatial coordinate system used by the standalone task

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:

CDTP0001 (=TASK) - the OGIP class of the data type

plus those required for all virtual files listed in CAL/GEN/92-003, and the following mandatory keyword to supply further information:

VIRVERSN - the OGIP version of the virtual FITS format in use (in this case 1992a)

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:

FORTRAN subroutine wtvig1.f (callib)
writes an VIGVERSN = 1992a dataset (Section 2.1)

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
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
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
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
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)
COMMENT

REFERENCES

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.

Footnotes:

¹Collimated 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 T_EX by T_TH, version 3.49.
On 8 Apr 2004, 10:43.