OGIP Calibration Memo CAL/GEN/92-027

OGIP Calibration Memo CAL/GEN/92-027

THE OGIP FORMAT FOR 2-D (IMAGE) POINT SPREAD FUNCTION DATASETS

Ian M George & Rehana Yusaf

Mail Code 668,
NASA/GSFC,
Greenbelt,
MD 20771.

Version: 1995 Jan 19

SUMMARY

Ths document describes the standard formats adopted by the OGIP for the storage of the 2-diemnsional Point Spread Function (2DPSF) datasets.

Intended audience: primarily OGIP programmers & hardware teams.

Log of Significant Changes

Release	Sections Changed	Brief Notes
Date

1992 Jul 24	First Draft	(within memo CAL/GEN/92-003)
1993 Oct 03	All	Separation from CAL/GEN/92-003
1994 Jan 12	All	Revised & added HDUCLASn info
1995 Jan 25	All	Made compatible with `LaTeX2HTML` software
2004 Apr 01	All	Made compatible with tth

1 Introduction

Within the OGIP 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 δ-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 OGIP caldb such a dataset is refered to as a 2DPSF, and it is the FITS file format for such calibration datasets which are described here. The corresponding file formats for the analogous 1-dimensional calibration datasets (based upon azimuthally averaged values of a 2DPSF, centred on the theoretical point of focus based on an idealized optical path) are described in CAL/GEN/92-020 (George & Yusaf).

1.1 Storage Options

... section incomplete

1.2 Dataset Origins & Storage Recommendations

... section incomplete

General

... section incomplete

Pre-launch

Post-launch

1.3 Dataset vs Task Summary

... section incomplete

1.4 Software Considerations

... section incomplete

Data Files:
... section incomplete

Virtual Files:
... section incomplete

1.5 Relationships to Other Calibration Datasets

... section incomplete

2 2DPSF Data File Formats

The OGIP FITS Working Group (OFWG) 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-027'
- the name of the document describing the format (ie this document)
HDUCLASn
- giving the HDUCLAS hierarchy for this format.
- HDUCLAS1 = 'IMAGE'
- HDUCLAS2 = 'PSF'
- 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 2DPSF dataset.

2.1 Summary of 2DPSF file formats versions

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

HDUVERS = '1.0.0' (Section 2.2)
This format is currently still VALID, and can be used for calibration datasets.

2.2 The PSF Extension (HDUVERS = '1.0.0')

Description:
A 2-dimensional array either in the Primary FITS array or in an IMAGE extension.

Extension Header
Beyond the standard FITS keywords required, and the HDU keywords/values given in Section 2, the following keywords/values are mandatory:

CTYPE1 & CTYPE2 - the names of the coordinates represented by the first and second axes
CRPIX1 & CRPIX2 - the locations of a reference point along the first and second axes in units of the axis index. These value is based upon counters which run from 1 to NAXIS1/NAXIS2 with an increment of 1 per pixel. The reference point values need not be that for the center of a pixel nor lie within the actual data array.
CRVAL1 & CRVAL2 - the values of the coordinate system specified by the corresponding CTYPE keyword at the reference point given by the CRPIX keywords in units specified by the CUNIT keywords.
CDELT1 & CDELT2 - the length of one side of the pixel at the reference point given by the CRPIX keywords in units specified by the CUNIT keywords.
CUNIT1 & CUNIT2 - the units of the physical quantities specified by the CTYPE keywords.
Allowed values are given in CAL/GEN/93-001.
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 PSF dataset has been generated from an observational dataset.
- HDUCLAS3 = 'PREDICTED' - indicating the PSF 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 PSF dataset includes counts from the 'source' as well as any counts from the 'background'
- HDUCLAS4 = 'NET' - indicating the PSF dataset has been background-subtracted
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 PSF 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 PSF 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 PSF 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 PSF 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 PSF dataset. Essentially the value of this keyword can provide the 'normalization' of an observed dataset. It is strongly urged that the PSF supplied to the OGIP 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 OGIP caldb (see CAL/GEN/92-011; George, Zellar & Pence 1992):,

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 = '2D_PSF' - 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

Data Format:
A 2-dimensional array either in the Primary FITS array or in an IMAGE extension.

Points to Note & Conventions

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 off-axis angle for which the dataset is valid;
- pname = PHI - giving the azimuthal angle for which the dataset is valid;
- pname = ENERGY - given the energy range for which the dataset is valid
- pname = CHAN - given the range of PHA detector channels for which the dataset is valid
- pname = PICH - given the range of PI detector channels 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.

3 Example FITS headers

Here we give an example of keywords used for a number of PSF images already in the calibration database.

3.1 ASCA

Example 1

A 2DPSF dataset given in detector coordinates, constructed from observations, background subtracted, valid over a restricted energy range (1.0-2.0 keV) and at specified position in the focal plane (off-axis angle θ = 6.0 arcmin, azimuthal angle φ = 9.0^°), stored in the Primary array.

SIMPLE  =                    T / file does conform to FITS standard
BITPIX  =                  -32 / number of bits per data pixel
NAXIS   =                    2 / number of data axes
NAXIS1  =                   63 / length of data axis   1
NAXIS2  =                   63 / length of data axis   2
EXTEND  =                    T / FITS dataset may contain extensions
COMMENT   FITS (Flexible Image Transport System) format defined in Astronomy and
COMMENT   Astrophysics Supplement Series v44/p363, v44/p371, v73/p359, v73/p365.
COMMENT   Contact the NASA Science Office of Standards and Technology for the
COMMENT   FITS Definition document #100 and other FITS information.
CTYPE1  = 'DETX    '           / GIS detector coordinate system
CTYPE2  = 'DETY    '           / GIS detector coordinate system
CUNIT1  = 'pixel   '           / GIS detector pixels (0.2456 arcmin)
CUNIT2  = 'pixel   '           / GIS detector pixels (0.2456 arcmin)
CRPIX1  =           2.8500E+01 / X axis reference pixel
CRPIX2  =           3.3500E+01 / Y axis reference pixel
CRVAL1  =           1.2850E+02 / coord of X ref pixel
CRVAL2  =           1.2850E+02 / coord of Y ref pixel
CDELT1  =           4.0000E+00 / X axis increment
CDELT2  =           4.0000E+00 / Y axis increment
HDUCLASS= 'OGIP    '           / Extension is OGIP defined
HDUDOC  = 'CAL/GEN/92-020'     / Document containing extension definition
HDUVERS = '1.0.0   '           / Version number of OGIP definition
HDUCLAS1= 'IMAGE   '           / Extension is an image
HDUCLAS2= 'PSF     '           / Extension is a PSF
HDUCLAS3= 'OBSERVED'           / Extension is observed data
HDUCLAS4= 'NET     '           / Extension is background-subtracted
TELESCOP= 'ASCA    '           / Satellite
INSTRUME= 'XRT     '           / Instrument
FILTER  = 'NONE    '           / Filter
CDTP0001= 'DATA    '           / Type of calibration
CCNM0001= '2D_PSF  '           /
CDES0001= 'Smoothed XRT PSF for theta= 6.0 arcmin, phi= 9.0 deg and E= 1- 2 keV'
BACKGRND=              0.0E+00 / background count/pixel
ENERG_LO=              1.0E+00 / min energy used for PSF
ENERG_HI=              2.0E+00 / max energy used for PSF
SUMRCTS =         1.132884E+00 / total counts in image
CBD10001= 'ENERGY( 1- 2)keV'   / Energy range for PSF
CBD20001= 'THETA( 6.0)arcmin'  / Distance from optical axis for PSF
CBD30001= 'PHI( 9.0)deg'       / Azimuthal angle for PSF
COMMENT   GIS images are smoothed before binning with a position-independent
COMMENT   Gaussian with sigma = 0.85,1.35,1.51,1.54,1.64,1.67,1.66,1.60,1.46,
COMMENT   1.18 GIS pixels for the 10 energy bands, respectively, and have
COMMENT   the final resolution of sigma=0.5 arcmin in all energy bands. This
COMMENT   is done to compensate for the GIS energy-dependent detector resolution
CCLS0001= 'BCF     '           / Basic Calibration File
END

Example 2

As for example 1, except stored as a FITS IMAGE extension (and for this eaxmple, a different energy range).

XTENSION= 'IMAGE   '           / IMAGE extension
BITPIX  =                  -32 / number of bits per data pixel
NAXIS   =                    2 / number of data axes
NAXIS1  =                   63 / length of data axis   1
NAXIS2  =                   63 / length of data axis   2
PCOUNT  =                    0 / number of random group parameters
GCOUNT  =                    1 / number of random groups
CTYPE1  = 'DETX    '           / GIS detector coordinate system
CTYPE2  = 'DETY    '           / GIS detector coordinate system
CUNIT1  = 'pixel   '           / GIS detector pixels (0.2456 arcmin)
CUNIT2  = 'pixel   '           / GIS detector pixels (0.2456 arcmin)
CRPIX1  =           2.8500E+01 / X axis reference pixel
CRPIX2  =           3.3500E+01 / Y axis reference pixel
CRVAL1  =           1.2850E+02 / coord of X ref pixel
CRVAL2  =           1.2850E+02 / coord of Y ref pixel
CDELT1  =           4.0000E+00 / X axis increment
CDELT2  =           4.0000E+00 / Y axis increment
HDUCLASS= 'OGIP    '           / Extension is OGIP defined
HDUDOC  = 'CAL/GEN/92-020'     / Document containing extension definition
HDUVERS = '1.0.0   '           / Version number of OGIP definition
HDUCLAS1= 'IMAGE   '           / Extension is an image
HDUCLAS2= 'PSF     '           / Extension is a PSF
HDUCLAS3= 'OBSERVED'           / Extension is observed data
HDUCLAS4= 'NET     '           / Extension is background-subtracted
TELESCOP= 'ASCA    '           / Satellite
INSTRUME= 'XRT     '           / Instrument
FILTER  = 'NONE    '           / Filter
CDTP0001= 'DATA    '           / Type of calibration
CCNM0001= '2D_PSF  '           /
CDES0001= 'Smoothed XRT PSF for theta= 6.0 arcmin, phi= 9.0 deg and E= 4- 5 keV'
BACKGRND=              0.0E+00 / background count/pixel
ENERG_LO=              4.0E+00 / min energy used for PSF
ENERG_HI=              5.0E+00 / max energy used for PSF
SUMRCTS =         1.195189E+00 / total counts in image
CBD10001= 'ENERGY( 4- 5)keV'   / Energy range for PSF
CBD20001= 'THETA( 6.0)arcmin'  / Distance from optical axis for PSF
CBD30001= 'PHI( 9.0)deg'       / Azimuthal angle for PSF
COMMENT   GIS images are smoothed before binning with a position-independent
COMMENT   Gaussian with sigma = 0.85,1.35,1.51,1.54,1.64,1.67,1.66,1.60,1.46,
COMMENT   1.18 GIS pixels for the 10 energy bands, respectively, and have
COMMENT   the final resolution of sigma=0.5 arcmin in all energy bands. This
COMMENT   is done to compensate for the GIS energy-dependent detector resolution
CCLS0001= 'BCF     '           / Basic Calibration File
END

REFERENCES

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. OGIP Calibration Memo CAL/GEN/92-003.
(available on-line from the anon ftp account on legacy.gsfc.nasa.gov).

George, I.M., Zellar, R.S. & Pence, W., 1992. OGIP Calibration Memo CAL/GEN/92-011.
(available on-line from the anon ftp account on legacy.gsfc.nasa.gov).

George, I.M., Arnaud, K.A., Pence, W. & Ruamsuwan, L., 1992a. (CAL/GEN/92-002).

George, I.M., et al., 1992b. In preparation. (CAL/SW/92-004).

USEFUL LINKS TO OTHER HTML PAGES

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

File translated from T_EX by T_TH, version 3.59.
On 12 Apr 2004, 13:32.

SUMMARY

RELATED DOCUMENTATION

1 Introduction

1.1 Storage Options

1.2 Dataset Origins & Storage Recommendations

1.3 Dataset vs Task Summary

1.4 Software Considerations

1.5 Relationships to Other Calibration Datasets

2 2DPSF Data File Formats

2.1 Summary of 2DPSF file formats versions

2.2 The PSF Extension (HDUVERS = '1.0.0')

3 Example FITS headers

3.1 ASCA

REFERENCES

USEFUL LINKS TO OTHER HTML PAGES