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.

and

Center for Research and Exploration
in Space Science and Technology,
X-ray Astrophysics Lab, Code 662
NASA/GSFC,
Greenbelt,
MD 20771.

Version: 2011 Nov 11

SUMMARY

Ths document describes the standard formats adopted by the OGIP for the storage of the 2-dimensional 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` software
2011 Nov 11	All	General updates by MFC; added description of Chandra 2DPSFs

1 Introduction
2 2DPSF Data File Formats
    2.1 Summary of 2DPSF file formats versions
    2.2 The PSF Extension (HDUVERS = '1.0.0')
3 Sample FITS Files
    3.1 ASCA
    3.2 Chandra ACIS

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

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 Sample FITS Files

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

Figure Figure 1: ACIS focal plane, showing the coordinate conventions and the overall layout of the imaging (I) and spectrometry (S) arrays.

3.2 Chandra ACIS

The Chandra X-ray Center uses a 2DPSF format to describe the point-spread of the High-Resolution Mirror Assembly (HRMA) on the Chandra X-ray Observatory. These files have been used to build libraries of 2D PSF images for both focal-plane detectors, the Advanced CCD Imaging Spectrometer (ACIS) and High Resolution Camera (HRC). These libraries can be accessed from the Chandra CALDB. The format of these files is described in "The Chandra PSF Library" by Karovska. As discussed on the PSF library page maintained by the Chandra X-ray Center,

The standard PSF library files consist of two dimensional simulated monochromatic PSF images "postage stamps" (energies ranging from 0.277 keV to 8.6 keV), stored in multi-dimensional FITS images (hypercubes) with azimuth and elevation steps (in telescope fixed system) of either 1 arcminute or 5 arcminutes (see the summary of the standard Chandra PSF libraries in the CIAO dictionary). The user can extract a PSF model image from a library file by interpolating within the energy and off-axis angle grids, using the CIAO tool mkpsf (as described in the Create a PSF thread). The PSFs in the standard PSF library files are not derived directly from calibration data, but rather through a ray-tracing routine, with inputs specifying the current Chandra HRMA model. This model seems to replicate the low-energy core and wings of the on-axis PSF well. High energy (greater than 2keV) comparisons of the wings are not yet sufficiently mature enough to draw conclusions.

Interested users can use the Chandra Ray Tracer (CHaRT, available from the RunCHaRT web page) for more detailed simulations.

The structure of a typical 2DPSF file in the Chandra ACIS psf library is:

% fstruct aciss1998-11-052dpsf4N0002.fits.gz
  No. Type     EXTNAME      BITPIX Dimensions(columns)      PCOUNT  GCOUNT
 
   0  PRIMARY                -32     512 512 1 5 3 3             0    1
   1  BINTABLE DEFOCUS_BINS    8     10(2) 1                     0    1
 
      Column Name                Format     Dims       Units     TLMIN  TLMAX
      1 DEFOCUS_BIN                1I
      2 DEFOCUS                    1D                  mm
 
   2  BINTABLE ENERGY_BINS     8     10(2) 5                     0    1
 
      Column Name                Format     Dims       Units     TLMIN  TLMAX
      1 ENERGY_BIN                 1I
      2 ENERGY                     1D                  keV
 
   3  IMAGE    AXAF_2DPSF_CT  32     1 5 3 3                     0    1

In this file, the primary image consists of a 512×512×1×5×3×3 hypercube. The first two dimensions are the spatial dimensions; the first dimension gives the Y direction on the chip, while the second dimension gives the Z dimension on the chip, in pointing coordinates as shown in Figure 1. The third dimension gives the "defocus" of the instrument (set to 0, to indicate that there's no defocus), while the fourth gives the energy range appropriate for the PSF image. The fifth and sixth dimensions give the azimuth and elevation, respectively.

The information regarding the size of the (non-spatial) axes are give by additional extensions following the primary array in the FITS file. In the above example the 1st extension contains the information regarding the defocus bin size while the 2nd extension contains information which specifies the energy binning used to generate the PSF images. The 3rd extension is an image extension which contains information regarding the total number of counts used to create each sub-image in the primary array hypercube.

REFERENCES

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

George, I.M., Zellar, R.S. & Pence, W., 1992. OGIP Calibration Memo (CAL/GEN/92-011).

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