OGIP Calibration Memo CAL/GEN/92-022

THE OGIP FORMAT FOR OBSCURATION FACTOR (COLLIMATOR RESPONSE) FILES
(OBSVERSN = 1992a)

Ian M George & Ron S Zellar

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

Version: 1994 Aug 08

SUMMARY

This document describes the standard format adopted by the OGIP for the storage of the obscuration factor (a.k.a. collimator response) 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 08	All	General Review/up-dates

1 Introduction

Within the OGIP caldb, the term Obscuration Factor refers to the energy-independent reduction in the collecting area of an instrument as one moves off-axis (normalized to unity on-axis) due purely to the geometry of the collecting surface(s) and surrounding support structures. Elsewhere, the Obscuration Factor is also sometimes referred to as the 'Collimator Reponse' or 'Geometric Vignetting Function'.

Notes:

From the above definition, the Obscuration Factor (or 'collimator efficiency') 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 off-axis Obscuration Factor (and also by the reciprocal of the off-axis Vignetting Function if appropriate - see CAL/GEN/92-021)

1.1 Storage Options

In the general case, an Obscuration Factor calibration dataset consists of a 2-dimensional grid, ObscFact, with the axes defining the position relative to the optical axis (i.e. off-axis & azimuthal angles θ_XMA,φ_XMA), in detector coordinates (e.g. θ_XMA, φ_XMA), or potentially any other spatial coordinate frame. Below we assume the former for convenience only. There are no other major storage options.

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
An Obscuration factor dataset is required for scanning, collimated detectors. Virtual calibration files are generally 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 (see CAL/GEN/92-021) and CCNMxxxx = OBSCFACT datasets.

Post-launch
The Vignetting function (either alone, or including the effects of obscuration) alone 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 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 obscuration factor dataset, h/w teams are urged isolate and also supply an updated obscuration factor dataset/algorithm to the HEASARC.

1.3 Dataset vs Task Summary

It is often fairly straightforward to parameterize the obscurration factor 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). This is recommended wherever possible.

1.4 Software Considerations

Data Files:
Interpolation between the spatial coordinate grids (eg theta_XMA,φ_XMA) grid points is usually required. By default, downstream software will use a simple 2-dimensional linear interpolation when calculating the Obscuration factor between θ_XMA,φ_XMA grid points. Thus the θ_XMA,φ_XMA grid should be of sufficient resolution to enable this to be reasonable approximation.

Virtual Files:
No specific issues.

1.5 Relationships to Other Calibration Datasets

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

condition:
Never.

An Obscuration Factor dataset is used in the construction of the following calibration datasets:

A CCNMxxxx = TVIGNET dataset (for imaging instruments only), containing the total vignetting function of the optics (see CAL/GEN/92-021).
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 = 'OBSFACTOR'/'1.1.0'
(this format is also known OBSVERSN = 1992a)
described in Section 2.1.

2.1 The Obscuration Factor Extension (OBSVERSN = 1992a)

Description:
One extension for each telescope in a BINTABLE format with a single row of 3 columns: two containing the spatial position grid points, and one containing the Obscuration Factors (relative to an on-axis value of unity).

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)
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 (see CAL/GEN/92-008):

TELESCOP - the name of the satellite/mission.
Allowed values are given in OGIP/93-013.
INSTRUME - the name of the telescope mirror, collimator assembly or detector (as appropriate).
Allowed values given in OGIP/93-013.
DETNAM - the name of the sub-instrument (eg quadrant of the telescope mirror assembly, sub-detector identifier etc as appropriate). This keyword is only required in cases where the INSTRUME keyword does not provide sufficient information.
Allowed values given in OGIP/93-013.
CCLS0001 (=BCF) - the OGIP class of this calibration file
CDTP0001 (=DATA) - the OGIP class of the data type
CCNM0001 (=OBSCFACT) - the OGIP codename for the contents (see also CAL/GEN/92-011)
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:

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

θ_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.
ObscFact, a fixed-length REAL vector (array, each element within which is 4-byte) containing the obscuration factor at each θ_XMA,φ_XMA grid point.
The FITS column name is OBSCFACT.
The order of data storage is ObscFact (θ_XMA,φ_XMA)
(unitless).

These are summarized in Table 1.

Table 1: Summary of the OGIP format for Mirror/Collimator Assembly Obscuration Factors (OBSVERSN = 1992a).

Extension
to (filename).(ext)

HDUCLAS1: RESPONSE
HDUVERS1: 1.0.0
HDUCLAS2: OBSFACTOR
HDUVERS2: 1.1.0
EXTNAME : OBSFACT (suggested, not required)
Description: Energy independent obscuration factors for an XMA or Collimator as a function of spatial position (eg off-axis & azimuthal angles).
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

contents
Off-axis	Azimuthal	Obscuration
angles	angles	Factors

θ_XMA	φ_XMA	ObscFact

format of each column
4-byte	4-byte	4-byte
real	real	real
array	array	array

total number of elements per row
i	j	i×j

column name
THETA	PHI	OBSFACT

Points to Note & Conventions

The ordering of the columns is of course arbitrary, however that used here is recommended.
An alternate spatial coordinate frame may be used, in which case
- the values of the CSYSNAME keyword should be replaced by the appropriate string listed in CAL/GEN/92-003.
- and/or (if necessary) the THETA & PHI column names replaced by more suitable alternatives if a different coordinate notation is employed.
The parameter-space limitations on the dataset involving the following pname strings are recommended to be specified via the CBDn0001 keywords (see CAL/GEN/92-011):
- 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 ObscFact 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 ).
The order of ObscFact(θ_XMA,φ_XMA) whereby θ_XMA changes fastest (see also CAL/GEN/92-003) was chosen pseudo-arbitrarily. 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 ObscFact (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 ObscFact (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 Obscuration, ObscFact(θ_XMA,φ_XMA), for a given off-axis position θ_XMA,φ_XMA.
Output:
The format of the o/p file should be one of the allowed data formats given in Section 2.
Note:
None

3.1 VCF Requirements

Description:
See CAL/GEN/92-013.

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

CSYSNAME - the spatial coordinate system used by the standalone task

along 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

those required for all virtual files listed in CAL/GEN/93-013, and the following mandatory 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 wtobf1.f (callib) writes an OBSVERSN = 1992a dataset (Section 2.1)

5 Example FITS headers

... section incomplete

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.

George, I.M. & Angelini, L., 1993. OGIP Memo OGIP/93-013. f

f available on-line from the anon ftp account on legacy.gsfc.nasa.gov.

File translated from T_EX by T_TH, version 3.49.
On 8 Apr 2004, 10:59.