OGIP Calibration Memo CAL/GEN/92-020
THE OGIP FORMAT FOR
RADIAL POINT SPREAD FUNCTION DATASETS
Ian M George
&
Rehana Yusaf
Mail Code 668,
NASA/GSFC,
Greenbelt,
MD20771.
Version: 1995 Oct 05
|
Release | Sections Changed | Brief Notes |
Date | ||
1992 Jul 24 | First Draft | (within memo CAL/GEN/92-003) |
1993 Oct 03 | All | Separation from CAL/GEN/92-003 |
1994 Jan 12 | All | Revised & added HDUCLASn info |
1995 Jan 19 | All | Made compatible with LaTeX2HTML software |
1995 Feb 10 | All | Fixed typos & ambiguities |
The following documents may also be of use:
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:
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:
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.
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
Pre-launch
Post-launch
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.
Data Files:
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:
... section incomplete
The HEASARC FITS Working Group (HFWG)
Header-Data Unit (HDU) keywords and values for this type of dataset are:
The following versions of file formats for a RPSF
dataset have been defined:
Description:
Note: this format was formally known as RPSFVERS = '1992a', and
is still occasionally refered to as such.
Extension Header
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):
Data Format:
These are summarized in Table 1.
RELATED DOCUMENTATION
CAL/GEN/92-003 (George & Zellar)
CAL/GEN/92-008 (George, Pence & Zellar)
CAL/GEN/92-011 (George, Zellar & Pence)
CAL/GEN/92-013 (George, Zellar & White)
CAL/GEN/92-027 (George & Yusaf)
1 Introduction
It is hopefully clear that both types are intimately related, and
indeed historically both have sometimes both been refered to
as radial point spread functions. However the
HEASARC CALDB
makes a clear distinction.
Detailed image-reconstruction of non-point-source targets should instead
use full 2-dimensional 2DPSF calibration datasets
described in
CAL/GEN/92-027 (George & Yusaf).
1.1 Storage Options
1.2 Dataset Origins & Storage Recommendations
In both the case of RPSFs and REEFs,
virtual calibration files are
recommended (see Sections 1.3 &
4).
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.
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
1.4 Software Considerations
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.
No specific issues.
1.5 Relationships to Other Calibration Datasets
2 RPSF Data File Formats
These are valid for all datasets described in this section, and
should be present in the header of the extension containing the
RPSF dataset.
- the name of the organization that defined this file format.
- the name of the document describing the format
(ie this document)
- giving the HDUCLAS hierarchy for this format.
2.1 Summary of RPSF file formats versions
This format is currently still VALID.
It was designed primarily for calibration datasets,
but can be used for GO datasets.
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')
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.
Beyond the standard FITS keywords required,
and the HDU keywords/values given in Section 2,
the following keywords/values are mandatory:
Allowed values are given in
CAL/GEN/92-011.
Allowed values are given in
CAL/GEN/92-011.
Only the RPSF, AREA_WGT & (if present)
the RPSF_ERR
columns here (with nnn=7,8 & 9 in the example below).
(see
CAL/GEN/92-003
for further details).
Only the RPSF, AREA_WGT & (if present)
the RPSF_ERR
columns here (with nnn=7,8 & 9 in the example below)
giving:
in the example below.
Allowed values are given in
CAL/GEN/92-003)
(CSYSNAME = 'XMA_POL' is assumed in the example below)
and the following mandatory to supply further information:
The data within the extension is organised as a BINTABLE with the
following columns:
The FITS column name is RAD_LO.
The recommended units are arcmin.
The FITS column name is RAD_HI.
The recommended units are arcmin.
The FITS column name is THETA (but see below).
The recommended units are arcmin.
The FITS column name is PHI (but see below).
The recommended units are arcmin.
The FITS column name is ENERG_LO.
The recommended units are keV.
The FITS column name is ENERG_HI.
The recommended units are keV.
The FITS column name is RPSF.
The order of data storage is
RPSF (R,θXMA,φXMA,E),
where R & E represent the
Rlow and Rhigh
Elow and Ehigh arrays respectively (see below).
The recommended units are per square arcmin.
The FITS column name is AREA_WGT.
The order of data storage is
Awgt (R,θXMA,φXMA,E),
where R & E represent the
Rlow and Rhigh
Elow and Ehigh arrays respectively (see below).
No units (dimensionless)
Extension |
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
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.
The HEASARC FITS Working Group (HFWG) Header-Data Unit (HDU) keywords and values for this type of dataset are:
The following versions of file formats for a REEF dataset have been defined:
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:
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):
Data Format:
The data within the extension is organised as a BINTABLE with the
following columns:
These are summarized in Table 2.
Extension |
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
Standalone tasks to perform the following tasks are currently allowed:
Description:
See
CAL/GEN/92-003
&
CAL/GEN/92-013.
Extension Header
Beyond the standard FITS keywords required, the following keywords/values
are mandatory:
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.
The following list of subroutines/tasks are available:
Here we give an example of keywords used in files currently within the CALDB.
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
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
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)
The following useful links are available (in the HTML version of this document only):