The following documents may also be of use:

• BCF & CPF Calibration File Guidelines
  CAL/GEN/92-003 (George & Zellar)

• Calibration Index Files
  CAL/GEN/92-008 (George, Pence & Zellar)

• Mandatory FITS Keywords for Calibration Files
  CAL/GEN/92-011 (George, Zellar & Pence)

• Virtual Calibration Files
  CAL/GEN/92-013 (George, Zellar & White)

• The OGIP format for 2-d PSFs
  CAL/GEN/92-027 (George & Yusaf)

1  Introduction

Within the HEASARC caldb the term "Point Spread Function" (PSF) is used to refer to the spatial/angular spreading of incident photons from a point source caused by the instrument (detector and/or mirror). In the most common and simple case, imperfections in the surface smoothness and shape of the mirrors result in incident photons from cosmic sources not being perfectly focussed on the focal plane. Thus the number of events detected as a function of position in the focal plane is not the idealized delta-function at the expected position, but has a characteristic shape (depending upon the optics and detectors in use) with a finite "width". More generally, the PSF also can include spreading of events due to "geometrical" effects (eg obscuring structures, the detector surface not laying exactly on the focal plane, including coma), and effects within the detector (eg lateral charge-cloud drift in gas experiments), etc.

Thus, generally a point-source at infinity gives rise to a 2-dimensional image of finite size. Within the the HEASARC caldb such a dataset is refered to as a 2DPSF, and the FITS file format for such calibration datasets are described in CAL/GEN/92-027 (George & Yusaf). In this memo we concentrate on the 1-dimensional (spatially) calibration datasets, commonly refered to as Radial Point Spread Functions, representing azimuthally averaged values of a 2DPSF, centred on the theoretical point of focus based on an idealized optical path. In practice the centroid of the 2DPSF is often used instead of the theoretical position of focus.

The HEASARC CALDB currently recognizes two types of datasets relating to the storage of the radial point spread function of an instrument:

• Radial Point Spread Function (RPSF) datasets; each element of which essentially describes the probability of an event (which was successfully detected by the detector) being detected at a position which lies within a given annulus centred on the theoretical position of focus. The dataset is normalized to either a single event (giving the true probability per unit area for each annulus - the prefered method for calibration datasets), or a given number of 'total' events (giving the expected/observed number of counts per unit area for each annulus - often useful for observational datasets).

• Radial Encircled Energy Function (REEF) datasets; each element of which describes the fraction of the 'total' events (when integrated out to a large/infinite radius) contained within circles of increasing radii centred on the theoretical position of focus.

Finally, it should be noted that for most instruments, the azimuthal averaging involved in their construction means that neither RPSF nor REEF (calibration datasets) are suitable for a detailed scientific investigation as to how an observed image of a given source is extended. Rather, both types of dataset provide:

• a 'first-look' indication as to whether a given observational image is spatially extended beyond that expected due to the instrumental response, and/or

• (assuming an image is indeed due to a point source)
  • a method of determining what fraction of the (source) counts lie within a given radius,

  • how to correct a count rates for this fact,

  • where the background starts to dominate,

  • what size 'detection cell' to use to be most sensitive to detecting sources,

  • etc

1.1  Storage Options

Due to the range of effects refered to above, in the general case, both RPSF and REEF datasets consist of a 4-dimensional grid, with 1 axis giving the "radius" (R, the angular distance from the theoretical point of focus), 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) - at which each RPSF dataset is valid.

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. Obviously emphasis is placed on 'calibration' RPSF or REEF datasets (ie datasets which are likely to be used as 'standard calibrations' by users and/or software, and/or are likely to be delivered to the HEASRAC caldb). Consequently, a number of the issues discussed here and in the document as a whole are not/less applicable to observational datasets (ie datasets derived from non-calibration, Guest Observer observations - particularly in the case of RPSF datasets).

General
In both the case of RPSFs and REEFs, virtual calibration files are recommended (see Sections 1.3 & 4).

Pre-launch
Prior to launch, the spatial/angular spreading of a point source is usually measured at a (limited) number of positions and/or photon energies during ground calibration experiments and/or combined with theoretical (eg ray-tracing) models to produce the datasets. In many case these results can be parameterized such that a virtual calibration file (Sections 1.3 & 4) can be produced.

Post-launch
In orbit, the pre-launch datasets are usually confirmed by making a limited number of pointings/raster-scans of a known bright point-source. Again, often the results from these datasets can be parameterized such that a virtual calibration file (Sections 1.3 & 4) can be created.

1.3  Dataset vs Task Summary

As stated above, it is often fairly straightforward to parameterize both a RPSF and REEF dataset 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 4.

1.4  Software Considerations

Data Files:
In the case of both RPSF and REEF datasets, 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 RPSF/REEF 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

... section incomplete

2  RPSF Data File Formats

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

• HDUCLASS = 'OGIP'
  - the name of the organization that defined this file format.

• HDUDOC = 'CAL/GEN/92-020'
  - the name of the document describing the format (ie this document)

• HDUCLASn
  - giving the HDUCLAS hierarchy for this format.
  • HDUCLAS1 = 'RESPONSE'

  • HDUCLAS2 = 'RPRF'

  • HDUCLAS3 = (see below)

  • HDUCLAS4 = (see below)

2.1  Summary of RPSF file formats versions

The following versions of file formats for a RPSF dataset have been defined:

• HDUVERS = '1.0.0' (Section 2.2)
  This format is currently still VALID.
  It was designed primarily for calibration datasets, but can be used for GO datasets.

• HDUVERS = '2.0.0' (Section 2.3)
  This format is currently still VALID.
  It was designed primarily for GO datasets, but can be used for calibration datasets.

2.2  The Radial PSF Extension (HDUVERS = '1.0.0')

Description:
One file for each telescope/instrument combination containing a single BINTABLE FITS extension. The BINTABLE only has a single row, using arrays for the 8 necessary columns.

Note: this format was formally known as RPSFVERS = '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:

• TELESCOP - the name of the satellite/mission.
  Allowed values are given in CAL/GEN/92-011.

• INSTRUME - the name of the telescope mirror/detector assembly.
  Allowed values are given in CAL/GEN/92-011.

• HDUVERS = '1.0.0' - giving the version of the format.

• HDUCLAS3 - further describing the scientific content of the dataset, specifically regarding the origin of the dataset. The allowed values are:
  • HDUCLAS3 = 'OBSERVED' - indicating the RPSF dataset has been generated from an observational dataset.

  • HDUCLAS3 = 'PREDICTED' - indicating the RPSF has been generated using a theoretical model.

• HDUCLAS4 - further describing the scientific content of the dataset, specifically regarding the contents of the dataset. The allowed values are:
  • HDUCLAS4 = 'TOTAL' - indicating the RPSF dataset includes counts from the 'source' as well as any counts from the 'background'

  • HDUCLAS4 = 'NET' - indicating the RPSF dataset has been background-subtracted

• TDIMnnn - the number of elements and ordering (see CAL/GEN/92-003) of each multi-dimensional array.
  Only the RPSF, AREA_WGT & (if present) the RPSF_ERR columns here (with nnn=7,8 & 9 in the example below).

• iCTYPnnn - The axis labels for dimension i (i = 1, 2, 3, 4) of the RPSF, AREA_WGT & (if present) the RPSF_ERR columns. In the example given below, nnn = 7, 8 & 9 respectively, and
  • 1CTYP7 = 'SPATIAL_OFFSET'

  • 2CTYP7 = 'COORD-1'

  • 3CTYP7 = 'COORD-2'

  • 4CTYP7 = 'ENERGY'

  • 1CTYP8 = 'SPATIAL_OFFSET'

  • 2CTYP8 = 'COORD-1'

  • 3CTYP8 = 'COORD-2'

  • 4CTYP8 = 'ENERGY'

  • 1CTYP9 = 'SPATIAL_OFFSET'

  • 2CTYP9 = 'COORD-1'

  • 3CTYP9 = 'COORD-2'

  • 4CTYP9 = 'ENERGY'

  (see CAL/GEN/92-003 for further details).

• CREFnnn = The column referencing keyword for each multi-dimensional array.
  Only the RPSF, AREA_WGT & (if present) the RPSF_ERR columns here (with nnn=7,8 & 9 in the example below) giving:
  • CREF7 = '(RAD_LO:RAD_HI,THETA,PHI,ENERG_LO:ENERG_HI)'

  • CREF8 = '(RAD_LO:RAD_HI,THETA,PHI,ENERG_LO:ENERG_HI)'

  • CREF9 = '(RAD_LO:RAD_HI,THETA,PHI,ENERG_LO:ENERG_HI)'

  in the example below.

• CSYSNAME - the spatial coordinate system in use
  Allowed values are given in CAL/GEN/92-003)
  (CSYSNAME = 'XMA_POL' is assumed in the example below)

• PIXSIZE - the angular size of (one side) of the pixels in units of decimal degrees.

• BACKGRND - the background count rate in units of counts per pixel (where the pixel size is definded by PIXSIZ). If no underlying instrument or cosmic background is expected, then a value of zero should be entered.

• ENERG_LO - the minimum energy (in keV) for which the the RPSF dataset was constructed or is valid. The value -99.0 indicates that the value is unknown.

• ENERG_HI - the maximum energy (in keV) for which the the RPSF dataset was constructed or is valid. The value -99.0 indicates that the value is unknown.

• CHANMIN - the minimum detector channel number for which the the RPSF dataset was constructed or is valid. The value -99.0 indicates that the value is unknown.

• CHANMAX - the maximum detector channel number for which the the RPSF dataset was constructed or is valid. The value -99.0 indicates that the value is unknown.

• CHANTYPE - the type of detector channels CHANMIN & CHANMAX are expressed in, with the allowed values:
  • CHANTYPE = 'PHA' - for 'raw' detector channels

  • CHANTYPE = 'PI' - for (corrected) 'Pulse Invariant' detector channels

• SUMRCTS - the sum of the raw counts 'under' the RPSF dataset. Essentially the value of this keyword can provide the 'normalization' of an observed dataset. It is strongly urged that the RPSF supplied to the HEASARC caldb be normalized to 1 count (ie SUMRCTS = 1.0).

and the following keywords/values are mandatory for CIF purposes ONLY if the dataset is ever to be included as a calibration file within the HEASARC caldb (see CAL/GEN/92-011):

• CCLS0001 - the OGIP class of this calibration file, with allowed values:
  • CCLS0001 = 'BCF' - for Basic Calibration datasets

  • CCLS0001 = 'CPF' - for Calibration Product datasets

• CDTP0001 - the OGIP class of the data type, with allowed values:
  • CDTP0001 = 'DATA' - for 'true' datasets

  • CDTP0001 = 'TASK' - for 'virtual' calibration datasets

• CCNM0001 = 'RPSF' - the OGIP codename for the contents

• CBDn0001 - the parameter-space limitations of the dataset (see below)

• CVSD0001 - calibration validity start date

• CVST0001 - calibration validity start time

• CDES0001 - a descriptive string of the calibration dataset

• RPSFVERS = '1992a' - the OGIP version of the FITS format in use

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

1. R_low, a fixed-length REAL vector (array, each element within which is 4-byte) containing the lower radial bounds of the annular bins as measured from the nominal point of focus.
   The FITS column name is RAD_LO.
   The recommended units are arcmin.

2. R_high, a fixed-length REAL vector (array, each element within which is 4-byte) containing the upper radial bounds of the annular bins as measured from the nominal point of focus.
   The FITS column name is RAD_HI.
   The recommended units are arcmin.

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

6. 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.

7. RPSF, a fixed-length REAL vector (array, each element within which is 4-byte) containing the RPSF measurement at each R,θ_XMA,φ_XMA,E grid point.
   The FITS column name is RPSF.
   The order of data storage is RPSF (R,θ_XMA,φ_XMA,E), where R & E represent the R_low and R_high E_low and E_high arrays respectively (see below).
   The recommended units are per square arcmin.

8. A_wgt, a fixed-length REAL vector (array, each element within which is 4-byte) containing an area weighting factor at each R,θ_XMA,φ_XMA,E grid point.
   The FITS column name is AREA_WGT.
   The order of data storage is A_wgt (R,θ_XMA,φ_XMA,E), where R & E represent the R_low and R_high E_low and E_high arrays respectively (see below).
   No units (dimensionless)

These are summarized in Table 1.

HDUCLASS: OGIP
HDUDOC: CAL/GEN/92-020
HDUVERS: 1.0.0
HDUCLAS1: RESPONSE
HDUCLAS2: RPRF
HDUCLAS3: see text
HDUCLAS4: see text
EXTNAME : RPSF (suggested, not required)
Description: Radial Point spread Function datasets (including errors, if required) as a function of radial angular distance from centroid, energy, off-axis & azimuthal angle.
An alternate spatial coordinate frame may also be used (see text).
Format: BINTABLE

column
1	2	3	4	5	6	7	8
contents
Inner	Outer	Off-axis	Azimuthal	Low energy	High energy	Radial	Area
Radius	Radius	angles	angles	bounds	bounds	PSF data	Weigthing
Rlow	Rhigh	θXMA	φXMA	Elow	Ehigh	RPSF	Awgt
format of each column
4-byte	4-byte	4-byte	4-byte	4-byte	4-byte	4-byte	4-byte
real	real	real	real	real	real	real	real
array	array	array	array	array	array	array	array
total number of elements per row
i	i	j	k	m	m	i ×j ×k ×m	i ×j ×k ×m
column name
RAD_LO	RAD_HI	THETA	PHI	ENERG_LO	ENERG_HI	RPSF	AREA_WGT

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/92-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 (see CAL/GEN/92-003).

  Spatial coordinate frames cannot be 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 (see CAL/GEN/92-003):
  • 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 of the dataset consider necessary.

• Datasets in which RPSF is independent of φ_XMA (or θ_XMA) should contain PHI = 0.0 (or THETA = 0.0) as a header keyword (or a corresponding alternate keyword if a different coordinate notation is employed).

• Alternative physical units are allowed for all columns of the table as long as they conform to the rules given in OGIP/93-001. The same is true for the physical units associated with the CBDn0001 keywords.

• The order of RPSF (Rad,θ_XMA,φ_XMA, E) whereby the radial parameters change fastest, and the energy parameters slowest was chosen to facilitate access for the most common applications: interpolation in θ_XMA,φ_XMA-space of RPSF vs R_low,R_high arrays. This ordering is further confirmed by the value of the mandatory TDIMnnn keyword for this array (where nnn = 7 in the above example).

• An optional array containing the 1σ statistical error associated with each element of RPSF (if required) should be contained in an additional column named RPSF_ERR.

2.3  The Radial PSF Extension (HDUVERS = '2.0.0')

Description:
One file for each telescope/instrument combination containing a single BINTABLE FITS extension.

THIS SECTION HAS BEEN REMOVED since the format is yet to be officially released

This format was designed primarily with GO datasets in mind, though (accepting the limitations given above) can be used for calibration datasets.

3  REEF Data File Formats

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

• HDUCLASS = 'OGIP'
  - the name of the organization that defined this file format.

• HDUDOC = 'CAL/GEN/92-020'
  - the name of the document describing the format (ie this document)

• HDUCLASn
  - giving the HDUCLAS hierarchy for this format.
  • HDUCLAS1 = 'RESPONSE'

  • HDUCLAS2 = 'REEF'

  • HDUCLAS3 = (see below)

  • HDUCLAS4 = (see below)

3.1  Summary of REEF file formats versions

The following versions of file formats for a REEF dataset have been defined:

• HDUVERS = '1.0.0' (Section 3.2)
  This format is currently still VALID.
  It was designed primarily for calibration datasets, but can be used for GO datasets.

3.2  The Radial Encircled Energy Fraction Extension (HDUVERS = '1.0.0')

Description:
One file for each telescope/instrument combination containing a single BINTABLE FITS extension. The BINTABLE only has a single row, using arrays for the 8 necessary columns.

Note: this format was formally known as REEFVERS = '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 3, the following keywords/values are mandatory:

• TELESCOP - the name of the satellite/mission.
  Allowed values are given in CAL/GEN/92-011.

• INSTRUME - the name of the telescope mirror/detector assembly.
  Allowed values are given in CAL/GEN/92-011.

• HDUVERS = '1.0.0' - giving the version of the format.

• HDUCLAS3 - further describing the scientific content of the dataset, specifically regarding the origin of the dataset. The allowed values are:
  • HDUCLAS3 = 'OBSERVED' - indicating the RPSF dataset has been generated from an observational dataset.

  • HDUCLAS3 = 'PREDICTED' - indicating the RPSF has been generated using a theoretical model.

• HDUCLAS4 - further describing the scientific content of the dataset, specifically regarding the contents of the dataset. The allowed values are:
  • HDUCLAS4 = 'TOTAL' - indicating the RPSF dataset includes counts from the 'source' as well as any counts from the 'background'

  • HDUCLAS4 = 'NET' - indicating the RPSF dataset has been background-subtracted

• TDIMnnn - the number of elements and ordering (see CAL/GEN/92-003) of each multi-dimensional array.
  Only the REEF & AREA_WGT columns here (with nnn = 7,8 in the example below).

• iCTYPnnn - The axis labels for dimension i (i = 1, 2, 3, 4) of the REEF & AREA_WGT columns. In the example given below, nnn = 7 & 8 respectively, and
  • 1CTYP7 = 'SPATIAL_OFFSET'

  • 2CTYP7 = 'COORD-1'

  • 3CTYP7 = 'COORD-2'

  • 4CTYP7 = 'ENERGY'

  • 1CTYP8 = 'SPATIAL_OFFSET'

  • 2CTYP8 = 'COORD-1'

  • 3CTYP8 = 'COORD-2'

  • 4CTYP8 = 'ENERGY'

  (see CAL/GEN/92-003 for further details).

• CREFnnn = The column referencing keyword for each multi-dimensional array.
  Only the REEF & AREA_WGT columns here (with nnn=7 & 8 in the example below) giving:
  • CREF7 = '(RAD_LO:RAD_HI,THETA,PHI,ENERG_LO:ENERG_HI)'

  • CREF8 = '(RAD_LO:RAD_HI,THETA,PHI,ENERG_LO:ENERG_HI)'

  in the example below.

• CSYSNAME - the spatial coordinate system in use
  Allowed values are given in CAL/GEN/92-003.
  (CSYSNAME = 'XMA_POL' is assumed in the example below)

• PIXSIZE - the angular size of (one side) of the pixels in units of decimal degrees.

• BACKGRND - the background count rate in units of counts per pixel (where the pixel size is definded by PIXSIZ). If no underlying instrument or cosmic background is expected, then a value of zero should be entered.

• ENERG_LO - the minimum energy (in keV) for which the the REEF dataset was constructed or is valid. The value -99.0 indicates that the value is unknown.

• ENERG_HI - the maximum energy (in keV) for which the the REEF dataset was constructed or is valid. The value -99.0 indicates that the value is unknown.

• CHANMIN - the minimum detector channel number for which the the REEF dataset was constructed or is valid. The value -99.0 indicates that the value is unknown.

• CHANMAX - the maximum detector channel number for which the the REEF dataset was constructed or is valid. The value -99.0 indicates that the value is unknown.

• CHANTYPE - the type of detector channels CHANMIN & CHANMAX are expressed in, with the allowed values:
  • CHANTYPE = 'PHA' - for 'raw' detector channels

  • CHANTYPE = 'PI' - for (corrected) 'Pulse Invariant' detector channels

and the following keywords/values are mandatory for CIF purposes ONLY if the dataset is ever to be included as a calibration file within the HEASARC caldb (see CAL/GEN/92-011):

• CCLS0001 - the OGIP class of this calibration file, with allowed values:
  • CCLS0001 = 'BCF' - for Basic Calibration datasets

  • CCLS0001 = 'CPF' - for Calibration Product datasets

• CDTP0001 - the OGIP class of the data type, with allowed values:
  • CDTP0001 = 'DATA' - for 'true' datasets

  • CDTP0001 = 'TASK' - for 'virtual' calibration datasets

• CCNM0001 = 'REEF' - the OGIP codename for the contents

• CBDn0001 - the parameter-space limitations of the dataset (see below)

• CVSD0001 - calibration validity start date

• CVST0001 - calibration validity start time

• CDES0001 - a descriptive string of the calibration dataset

• REEFVERS = '1992a' - the OGIP version of the FITS format in use

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

1. R_low, a fixed-length REAL vector (array, each element within which is 4-byte) containing the lower radial bounds of the annular bins as measured from the nominal point of focus.
   The FITS column name is RAD_LO.
   The recommended units are arcmin.

2. R_high, a fixed-length REAL vector (array, each element within which is 4-byte) containing the upper radial bounds of the annular bins as measured from the nominal point of focus.
   The FITS column name is RAD_HI.
   The recommended units are arcmin.

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

6. 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.

7. REEF, a fixed-length REAL vector (array, each element within which is 4-byte) containing the REEF measurement at each R,θ_XMA,φ_XMA,E grid point.
   The FITS column name is REEF.
   The order of data storage is REEF (R,θ_XMA,φ_XMA,E), where R & E represent the R_low and R_high E_low and E_high arrays respectively (see below).
   No units (dimensionless)

8. A_wgt, a fixed-length REAL vector (array, each element within which is 4-byte) containing an area weighting factor at each R,θ_XMA,φ_XMA,E grid point.
   The FITS column name is AREA_WGT.
   The order of data storage is A_wgt (R,θ_XMA,φ_XMA,E), where R & E represent the R_low and R_high E_low and E_high arrays respectively (see below).
   No units (dimensionless)

These are summarized in Table 2.

HDUCLASS: OGIP
HDUDOC: CAL/GEN/92-020
HDUVERS: 1.0.0
HDUCLAS1: RESPONSE
HDUCLAS2: REEF
HDUCLAS3: see text
HDUCLAS4: see text
EXTNAME : REEF (suggested, not required)
Description: Radial Encircled Energy Function datasets (including errors, if required) as a function of radial angular distance from centroid, energy, off-axis & azimuthal angle.
An alternate spatial coordinate frame may also be used (see text).
Format: BINTABLE

column
1	2	3	4	5	6	7	8
contents
Inner	Outer	Off-axis	Azimuthal	Low energy	High energy	Radial	Area
Radius	Radius	angles	angles	bounds	bounds	PSF data	Weighting
Rlow	Rhigh	θXMA	φXMA	Elow	Ehigh	REEF	Awgt
format of each column
4-byte	4-byte	4-byte	4-byte	4-byte	4-byte	4-byte	4-byte
real	real	real	real	real	real	real	real
array	array	array	array	array	array	array	array
total number of elements per row
i	i	j	k	m	m	i ×j ×k ×m	i ×j ×k ×m
column name
RAD_LO	RAD_HI	THETA	PHI	ENERG_LO	ENERG_HI	REEF	AREA_WGT

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/92-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 (see CAL/GEN/92-003).

  Spatial coordinate frames cannot be 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 (see CAL/GEN/92-003):
  • 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 of the dataset consider necessary.

• Datasets in which REEF is independent of φ_XMA (or θ_XMA) should contain PHI = 0.0 (or THETA = 0.0) as a header keyword (or a corresponding alternate keyword if a different coordinate notation is employed).

• Alternative physical units are allowed for all columns of the table as long as they conform to the rules given in OGIP/93-001. The same is true for the physical units associated with the CBDn0001 keywords.

• The order of REEF (Rad,θ_XMA,φ_XMA, E) whereby the radial parameters change fastest, and the energy parameters slowest was chosen to facilitate access for the most common applications: interpolation in θ_XMA,φ_XMA-space of RPSF vs R_low,R_high arrays. This ordering is further confirmed by the value of the mandatory TDIMnnn keyword for this array (where nnn = 7 in the above example).

• An optional array containing the 1σ statistical error associated with each element of RPSF (if required) should be contained in an additional column named REEF_ERR.

4  Virtual File Formats & Allowed Standalone Tasks

Standalone tasks to perform the following tasks are currently allowed:

• Calculate the Radial Point Spread Function, RPSF(R,θ_XMA,φ_XMA,E) as a function of radius from the nominal point of focus (R), for a given off-axis position θ_XMA,φ_XMA and (range of) photon energy (E).
  Output:
  The format of the o/p file should be one of the allowed data formats given in Section 2.
  Notes:
  None

• Calculate the Radial Encircled Energy Fraction, REEF(R,θ_XMA,φ_XMA,E) as a function of radius from the nominal point of focus (R), for a given off-axis position θ_XMA,φ_XMA and (range of) photon energy (E).
  Output:
  The format of the o/p file should be one of the allowed data formats given in Section 3.
  Notes:
  None

4.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

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

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

Data Format:
See CAL/GEN/92-003 amd CAL/GEN/92-013. The number and type of parameters specified depends solely on the requirements of the associated standalone task.

5  Related Software

The following list of subroutines/tasks are available:

• FORTRAN subroutine wt???.f (callib)
  writes an RPSFVERS = 1992a dataset (Section 2.2)

6  Example FITS headers

Here we give an example of keywords used in files currently within the CALDB.

6.1  ROSAT 

Example 1

WARNING: This dataset has a number of keywords missing.

XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                  200 / 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 =                    5 / number of fields in each row
TTYPE1  = 'RAD_LO  '           / label for field   1
TFORM1  = '10E     '           / data format of the field: 4-byte REAL
TUNIT1  = 'arcmin  '           / physical unit of field
TTYPE2  = 'RAD_HI  '           / label for field   2
TFORM2  = '10E     '           / data format of the field: 4-byte REAL
TUNIT2  = 'arcmin  '           / physical unit of field
TTYPE3  = 'RPSF    '           / label for field   3
TFORM3  = '10E     '           / data format of the field: 4-byte REAL
TUNIT3  = 'count/arcmin**2'    / physical unit of field
TTYPE4  = 'RPSF_ERR'           / label for field   4
TFORM4  = '10E     '           / data format of the field: 4-byte REAL
TUNIT4  = 'count/arcmin**2'    / physical unit of field
TTYPE5  = 'AREA_WGT'           / label for field   5
TFORM5  = '10E     '           / data format of the field: 4-byte REAL
EXTNAME = 'OBS RPSF'           / name of this binary table extension
TDIM1   = '(10)    '           /  Column dimension
TDIM2   = '(10)    '           /  Column dimension
TDIM3   = '(10,1,1)'           /  Column dimension
TDIM4   = '(10,1,1)'           /  Column dimension
TDIM5   = '(10,1,1)'           /  Column dimension
TELESCOP= 'ROSAT   '           / Name of Mission/Telescope
INSTRUME= 'PSPCB   '           / Name of Instrument/Detector
HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUCLAS1= 'RESPONSE'           / dataset is a response function
HDUCLAS2= 'RPRF    '           / dataset is a radial point response function
HDUCLAS3= 'NET     '           / Source only radial point spread function
HDUVERS1= '1.0.0   '           / Version of family of formats
HDUVERS2= '1.0.1   '           / Version of format
RPSFVER = '1993a   '           / OGIP FITS format version
THETA_LO=      -9.90000000E+01 / Value not defined
THETA_HI=      -9.90000000E+01 / Value not defined
ENERG_LO=      -9.90000000E+01 / Value not defined
ENERG_HI=      -9.90000000E+01 / Value not defined
DATE    = '14/04/94'           / FITS file creation date (dd/mm/yy)
HISTORY   ST2RPSF converts from STW -> RPSF format
HISTORY   STW FILE : pros2_3b_cnt.fits
HISTORY   EXTENSION WRITTEN BY WTRPF1 Ver 1.0.1
CREATOR = 'ST2RPSF 1.0.5'      / s/w task which wrote this dataset
PIXSIZE =           1.3889E-04 / In decimal degrees
BACKGRND=       0.00000000E+00 / In counts per pixel
CHANMIN =                   20 / Minimum PI channel for image
CHANMAX =                  100 / Maximum PI channel for image
SUMRCTS =         1.496935E+04 / Sum of raw counts
END

Example 2

WARNING: This dataset has a number of keywords missing.

XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =                  120 / 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 =                    5 / number of fields in each row
TTYPE1  = 'RAD_LO  '           / label for field   1
TFORM1  = '6E      '           / data format of the field: 4-byte REAL
TUNIT1  = 'arcmin  '           / physical unit of field
TTYPE2  = 'RAD_HI  '           / label for field   2
TFORM2  = '6E      '           / data format of the field: 4-byte REAL
TUNIT2  = 'arcmin  '           / physical unit of field
TTYPE3  = 'RPSF    '           / label for field   3
TFORM3  = '6E      '           / data format of the field: 4-byte REAL
TUNIT3  = 'count/arcmin**2'    / physical unit of field
TTYPE4  = 'RPSF_ERR'           / label for field   4
TFORM4  = '6E      '           / data format of the field: 4-byte REAL
TUNIT4  = 'count/arcmin**2'    / physical unit of field
TTYPE5  = 'AREA_WGT'           / label for field   5
TFORM5  = '6E      '           / data format of the field: 4-byte REAL
EXTNAME = 'OBS RPSF'           / name of this binary table extension
TDIM1   = '(6)     '           /  Column dimension
TDIM2   = '(6)     '           /  Column dimension
TDIM3   = '(6,1,1) '           /  Column dimension
TDIM4   = '(6,1,1) '           /  Column dimension
TDIM5   = '(6,1,1) '           /  Column dimension
TELESCOP= 'ROSAT   '           / Name of Mission/Telescope
INSTRUME= 'PSPCB   '           / Name of Instrument/Detector
HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUCLAS1= 'RESPONSE'           / dataset is a response function
HDUCLAS2= 'RPRF    '           / dataset is a radial point response function
HDUCLAS3= 'NET     '           / Source only radial point spread function
HDUVERS1= '1.0.0   '           / Version of family of formats
HDUVERS2= '1.0.1   '           / Version of format
RPSFVER = '1993a   '           / OGIP FITS format version
THETA_LO=      -9.90000000E+01 / Value not defined
THETA_HI=      -9.90000000E+01 / Value not defined
ENERG_LO=      -9.90000000E+01 / Value not defined
ENERG_HI=      -9.90000000E+01 / Value not defined
DATE    = '18/10/94'           / FITS file creation date (dd/mm/yy)
HISTORY   EXTENSION WRITTEN BY WTRPF1 Ver 1.0.1
COMMENT   DATA OBTAINED FROM RADIAL PROFILE : pros2_3b_cnt.st
COMMENT   THE RADIAL PROFILE DATA IS REBINNED
COMMENT   USING (USER DEFINED) MINIMUM COUNTS/BIN :    20.
COMMENT   LAST BIN CONTAINS LESS THAN MINUMUM COUNTS/BIN
COMMENT   WARNING : INPUT DATASET CONTAINS NEGATIVE COUNTS
PIXSIZE =         1.388900E-04 / pixelsize in deg
BACKGRND=         0.000000E+00 / Background count rate in cts/pixel
CHANMIN =                   10 / Minimum PI channel for image
CHANMAX =                  200 / Maximum PI channel for image
SUMRCTS =         1.496935E+04 / Sum of raw counts
CREATOR = 'RBNRPSF 1.1.1'      / s/w task which wrote this dataset
END

6.2  ASCA

Example 1

XTENSION= 'BINTABLE'           / binary table extension
BITPIX  =                    8 / 8-bit bytes
NAXIS   =                    2 / 2-dimensional binary table
NAXIS1  =               733064 / 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 =                    7 / number of fields in each row
TTYPE1  = 'RAD_LO  '           / label for field   1
TFORM1  = '502E    '           / data format of the field: 4-byte REAL
TUNIT1  = 'arcmin  '           / physical unit of field
TTYPE2  = 'RAD_HI  '           / label for field   2
TFORM2  = '502E    '           / data format of the field: 4-byte REAL
TUNIT2  = 'arcmin  '           / physical unit of field
TTYPE3  = 'THETA   '           / label for field   3
TFORM3  = '11E     '           / data format of the field: 4-byte REAL
TUNIT3  = 'arcmin  '           / physical unit of field
TTYPE4  = 'PHI     '           / label for field   4
TFORM4  = '3E      '           / data format of the field: 4-byte REAL
TUNIT4  = 'deg     '           / physical unit of field
TTYPE5  = 'ENERG_LO'           / label for field   5
TFORM5  = '11E     '           / data format of the field: 4-byte REAL
TUNIT5  = 'keV     '           / physical unit of field
TTYPE6  = 'ENERG_HI'           / label for field   6
TFORM6  = '11E     '           / data format of the field: 4-byte REAL
TUNIT6  = 'keV     '           / physical unit of field
TTYPE7  = 'RPSF    '           / label for field   7
TFORM7  = '182226E '           / data format of the field: 4-byte REAL
TUNIT7  = '        '           / physical unit of field
EXTNAME = 'ASCA_PSF'           / name of this binary table extension
TDIM7   = '(502,11,3,11)'      /  Column dimension
1CTYP7  = 'SPATIAL_OFFSET'     /  Axis label
2CTYP7  = 'COORD-1 '           /  Axis label
3CTYP7  = 'COORD-2 '           /  Axis label
4CTYP7  = 'ENERGY  '           /  Axis label
CREF7   = '(RAD_LO:RAD_HI,THETA,PHI,ENERG_LO:ENERG_HI)' /  Column referencing
TELESCOP= 'ASCA    '           / Name of Mission/Telescope
CSYSNAME= 'XMA_POL '           / The spatial coordinate system in use
PIXSIZE =       8.18500004E-04 / The pixel size in decimal degrees
BACKGRND=       0.00000000E+00 / The background count rate in counts/pixe
SUMRCTS =                  1.0 / Sum of counts within a 6 arcmin radius
INSTRUME= 'XRT     '           / Name of Instrument/Detector
HDUCLASS= 'OGIP    '           / format conforms to OGIP standard
HDUCLAS1= 'RESPONSE'           / dataset is a response function
HDUCLAS2= 'RPRF    '           / dataset is a radial point response function
HDUCLAS3= 'PREDICTED'          / Predicted (theoretical) dataset
HDUCLAS4= 'NET     '           / Source only radial point spread function
HDUVERS1= '1.0.0   '           / Version of family of formats
HDUVERS2= '1.0.1   '           / Version of format
AREA_WGT=       1.00000000E+00 / Area Weighting Factor
DATE    = '19/09/95'           / FITS file creation date (dd/mm/yy)
HISTORY   EXTENSION WRITTEN BY WTRPF1 Ver 1.1.0
HDUDOC  = 'CAL/GEN/92-020'     / OGIP memo for File Format definition
RPSFVERS= '1992a   '           / OGIP FITS format version
CCLS0001= 'BCF     '           / OGIP class for this dataset
CCNM0001= 'RPSF    '           / OGIP codename for this dataset
CDTP0001= 'DATA    '           / OGIP datatype for this dataset
CVSD0001= '20/02/93'           / Date when data becomes valid
CVST0001= '02:00:00'           / Time when data becomes valid
CDES0001= 'XRT Radial Point-Spread-Function dataset from Nagoya ray-tracing' /
CBD10001= 'THETA(0,25)arcmin'  /
CBD20001= 'PHI(0,45)deg'       /
CBD30001= 'ENERG(1,10)keV'     /
END 

REFERENCES

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:
/docs/heasarc/caldb/caldb_docs_index.html

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.

Angelini, L., et al., 1992. In preparation.

George, I.M., 1992. Legacy, 1, 56
(CAL/GEN/91-001)

George, I.M. & Zellar, R.S., 1992.
(CAL/GEN/92-003) George, I.M., Zellar, R.S. & Pence, W., 1992.
(CAL/GEN/92-011) George, I.M., Arnaud, K.A., Pence, W. & Ruamsuwan, L., 1992a.
(CAL/GEN/92-002) George, I.M., et al., 1992b.
(CAL/SW/92-004)

USEFUL LINKS TO OTHER HTML PAGES

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

• The HEASARC Home Page
• The OGIP Calibration Database Home Page
• The OGIP FITS Working Group Home Page