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.
and
Michael F. Corcoran
CRESST & X-ray Astrophysics Lab
Code 662 NASA/GSFC, Greenbelt, MD20771
and
Universities Space Research Association
10211 Wincopin Circle, Columbia, MD 21044
Version: 2011 Oct 21
SUMMARY
| |
Ths document describes the standard formats adopted by the OGIP for the
storage of the Radial Point Spread Function (RPSF) and
Radial Encircled Energy
Function (REEF) datasets, which describe the radial angular/spatial
response of an instrument as a function of energy, and position.
Intended audience: primarily HEASARC 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 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 |
| 2011 Oct 20 | All (and Appendix) | more typos; added Figure 1 and Appendix |
Contents
1 Introduction
1.1 Storage Options
1.2 Dataset Origins & Storage Recommendations
1.3 Dataset vs Task Summary
1.4 Software Considerations
2 RPSF Data File Formats
2.1 Summary of RPSF file formats versions
2.2 The Radial PSF Extension (HDUVERS = '1.0.0')
3 REEF Data File Formats
3.1 Summary of REEF file formats versions
3.2 The Radial Encircled Energy Fraction Extension (HDUVERS = `1.0.0')
4 Virtual File Formats & Allowed Standalone Tasks
4.1 VCF Requirements
5 Related Software
6 Example FITS headers
6.1 ROSAT
6.2 ASCA
7 Appendix
RELATED DOCUMENTATION
The following documents may also be of use:
1 Introduction
Within the HEASARC CALDB
the term "Point Spread Function" (PSF) (or "Point Response Function", PRF) is used to refer to
the spatial/angular spreading of incident photons from a point source
caused by the instrument (mirror or optical system, and - optionally - the detector).
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 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 Radial Point Spread Functions which give the source surface brightness as a function of
radial distance from the focal point.
These radial point spread functions represent the azimuthally-averaged values of
the detected source surface brightness from
a 2DPSF, centered on the nominal point of focus assuming an idealized optical path.
In practice, the centroid of the 2DPSF is often used instead of
the theoretical position of focus.
Figure
Figure 1: The detector plane in sky coordinates. N is to the top, E to the left. The optical axis is normal to the detector at the point marked by the ×, and the imaged source is represented by the blue circle. The off-axis angle θXMA and azimuthal angle ϕXMA are shown. The azimuthal angle ϕXMA is usually measured from north through east by convention.
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
centered 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
centered on the theoretical position of focus.
Both the RPSF and REEF data historically have been referred to
as radial point spread functions. However, for clarity, the
HEASARC CALDB
distinguishes the two.
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 of the spatial extent of a detected source.
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
- a method of determining what fraction of the (source) counts lie within a given radius,
- the correction of detected count rate for the finite detect cell size to determine the total count rate,
- the region where the background starts to dominate over source counts,
- the requisite size of the "detection cell" to use to be most sensitive to
detecting sources,
- etc.
Detailed image reconstruction of non-point-source targets should use full 2-dimensional 2DPSF calibration datasets
described in
CAL/GEN/92-027 (George & Yusaf).
1.1 Storage Options
The point spread function in general depends on annular distance R from the point of focus, the incident photon energy E, and on the position of the point of focus on the detector, usually given in terms of two angles, the off-axis angle (θXMA) which accounts for the dependence of the RPSF on the angular distance from the optical axis, and an azimuthal
angle (ϕXMA), as shown in figure 1.
When stored in a FITS file, 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 (θXMA and ϕXMA) defining the position relative to the optical axis 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 instrument team.
However, below, are the recommendations of the HEASARC CALDB team based on our experience.
Our emphasis is on "calibration" RPSF or REEF
datasets (ie datasets which are likely to be used as "standard
calibrations" by users and analysis software, and delivered to and stored in
the HEASRAC CALDB). Consequently, a number of the issues discussed here and
in the document as a whole are not applicable to datasets derived from non-calibration, Guest Observer observations.
General
In both the case of RPSFs and REEFs, use of
virtual calibration files are
recommended (see Sections 1.3 &
4) for those cases where the point spread function can be adequately described
by simple functional forms (gaussians, lorentzians, etc.).
Pre-launch
Prior to launch,
the spatial/angular spreading of a point source is measured at a (limited) number of positions and/or photon energies during
ground calibrations and/or modelled analytical
(eg by ray-tracing) to characterize the PSF.
In most cases these results can be parameterized
and stored in a virtual calibration file
(Sections 1.3 & 4).
Post-launch
After launch, the pre-launch PSFs are usually checked and updated using
a limited
number of pointings of known bright point-sources (LMC X-1, Cyg X-3, ζ Pup, etc.) usually at a number of off-axis and azimuthal angles.
Often the results from these observations can be parameterized
such that a virtual calibration file
(Sections 1.3 & 4)
can be created.
1.3 Dataset vs Task Summary
It is often possible
to parameterize
both a RPSF and REEF dataset for a given science instrument.
In these cases the RPSF and/or REEF information may often be economically stored as a virtual calibration file, and an associated
standalone s/w task (see
CAL/GEN/92-003).
Wherever possible, this is recommended.
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 for comparison with a pointed observation.
Most often, analysis
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 be
of sufficient resolution such that interpolation of this parameter is not required.
However, in cases where interpolation is required, as simple
1-dimensional linear interpolation may
be performed,
(which will clearly
which may be inaccurate close to sharp spectral features (detector absorption edges, for example).
Virtual Files:
No specific issues.
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)
These are valid for all datasets described in this section, and
should be present in the header of the extension containing the
RPSF dataset.
Figure
Figure 2: Plot of sample radial point spread function. The PSFs shown are approximated as gaussians with given standard deviations σ values as shown. The PSFs broaden as the source off-axis angle increases. Each PSF is normalized to unity.
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 )
This format is currently still VALID.
It was designed primarily for GO datasets,
but can be used for calibration datasets. NOTE THAT THIS FORMAT WAS NEVER IMPLEMENTED, AND THUS WILL NOT BE DISCUSSED FURTHER.
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
and the following mandatory to supply further information:
- 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:
- Rlow, 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.
- Rhigh, 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.
- θ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.
- Elow, a fixed-length REAL vector (array, each element within
which is 4-byte) containing the lower energy bounds of
the energy bins.
The FITS column name is ENERG_LO.
The recommended units are keV.
- Ehigh, a fixed-length REAL vector (array, each element within
which is 4-byte) containing the upper energy bounds of
the energy bins.
The FITS column name is ENERG_HI.
The recommended units are keV.
- 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
Rlow and Rhigh
Elow and Ehigh arrays respectively (see below).
The recommended units are per square arcmin.
- Awgt, 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
Awgt (R,θXMA,ϕXMA,E),
where R & E represent the
Rlow and Rhigh
Elow and Ehigh arrays respectively (see below).
No units (dimensionless)
These are summarized in Table 1.
Table 1: Summary of the OGIP format for
Radial PSFs (HDUVERS = 1.0.0).
to (filename).(ext)
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
(Elow & Ehigh)
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
Rlow,Rhigh 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.
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)
These are valid for all datasets described in this section, and
should be present in the header of the extension containing the
REEF dataset.
Figure
Figure 3: Plot of sample radial encircled energy function. The REEFs shown are approximated as gaussians with standard deviations σ given as in Figure 2 above. Because the PSFs broaden as the source off-axis angle increases, an extraction cell of a given size captures less of the integrated flux as the source is placed at increasingly larger off-axis positions.
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
and the following mandatory to supply further information:
- 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:
- Rlow, 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.
- Rhigh, 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.
- θ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.
- Elow, a fixed-length REAL vector (array, each element within
which is 4-byte) containing the lower energy bounds of
the energy bins.
The FITS column name is ENERG_LO.
The recommended units are keV.
- Ehigh, a fixed-length REAL vector (array, each element within
which is 4-byte) containing the upper energy bounds of
the energy bins.
The FITS column name is ENERG_HI.
The recommended units are keV.
- 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
Rlow and Rhigh
Elow and Ehigh arrays respectively (see below).
No units (dimensionless)
- Awgt, 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
Awgt (R,θXMA,ϕXMA,E),
where R & E represent the
Rlow and Rhigh
Elow and Ehigh arrays respectively (see below).
No units (dimensionless)
These are summarized in Table 2.
Table 2: Summary of the OGIP format for
Radial EEFs (REEFVERS = 1992a).
to (filename).(ext)
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
(Elow & Ehigh)
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
Rlow,Rhigh 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
along (if desired)
with those keywords/values mandatory for CIF purposes as given in
within the appropriate sub-section of Sections 2
& 3, 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-013,
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
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.
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 MINIMUM 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
REFERENCES
Information regarding on-line versions of any of the following references
with an OGIP Memo number (i.e., documents starting OGIP/... or
CAL/...) can most easily be found via the WorldWide Web by following
the links from the HEASARC CALDB Document Library.
Most OGIP Calibration Memos of general community interest have appeared
as articles in the HEASARC journal Legacy.
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 links may be useful:
7 Appendix
Table 3: Sample PRF and REEF files
| TELESCOP | INSTRUME | HDUCLASS | HDUCLASn | Location |
|
| CHANDRA | HRMA | ASC | HDUCLAS1= 'RESPONSE' | hrmaD1996-11-01wpsfN0001.fits |
| | | HDUCLAS2= 'PSF ' | |
| | | HDUCLAS3= 'WPSF ' | |
| CHANDRA | HRMA | | HDUCLAS1= 'RESPONSE' | hrmaD1996-12-20reefN0001.fits |
| | | HDUCLAS2= 'REEF2 ' | |
| | | HDUCLAS3= 'PREDICTED' | |
| | | HDUCLAS4= 'NET ' | |
| CHANDRA | ACIS | ASC | HDUCLAS1= 'RESPONSE' | acisi1998-11-052dpsf1N0002.fits |
| | | HDUCLAS2= 'PSF ' | |
| | | HDUCLAS3= '2DPSF ' | |
| CHANDRA | HRC | ASC | HDUCLAS1= 'RESPONSE' | hrci1998-11-052dpsf1N0002.fits |
| | | HDUCLAS2= 'PSF ' | |
| | | HDUCLAS3= '2DPSF ' | |
| Swift | XRT | | | swxpsf20010101v004.fits |
| Swift | XRT | | | swxeef20010101v001.fits |
| Suzaku | XRT-I0 | | | ae_xrt0_psf_20090605.fits |
| Fermi | LAT | OGIP | HDUCLAS1= 'RESPONSE' | psf_P6_v11_diff_front.fits |
| | | HDUCLAS2= 'RPSF ' | |
| | | HDUVERS = '1.0.0 ' | |
File translated from
TEX
by
TTHgold,
version 4.00.
On 4 Dec 2012, 11:58.