2-D PSF à la carte

Introduction This thread shows how to use the two-dimensional PSF parametrisation CCF and the associated SAS software (version 10 or higher) to obtain a customised description of the PSF associated to a given position in the EPIC field-of-view. Expected Outcome This thread shows you: How to extract the parameters describing the PSF from the relevant CCF for a given EPIC instrument, energy, off-axis angle, and azimuthal angle How to use SAS software to obtain a FITS image of a PSF SAS Tasks to be Used calview psfgen Prerequisites None Useful Links This thread makes use of the following LHEASOFT tasks: fkeypar ftabpar fv pget Caveats

---

Introduction

As of SAS v.10, a full 2-D parametrisation of the EPIC PSF ("2-D PSF" hereafter) as a function of instrument, energy, off-axis angle and azimuthal angle has been introduced, covering the whole field-of-view. It models the PSF spokes and the large-scale azimuthal variations, and includes an additional Gaussian core, which accounts for (at most) 2% of the enclosed energy flux in the MOS cameras. This version is not fully scientifically validated, and some areas of the parameter space have still to be explored and/or refined.

The CCF constituents describing the 2-D PSF are XRT[123]_XPSF_0011.CCF and later. The CCF extension containing the parameters describing (part of) the analytical form of the PSF is ELLBETA_PARAMS.

A full description of the 2-D PSF and its current limitations is provided in the CCF release note. It is assumed in the rest of the thread that the reader is familiar with the content of this document.

How to extract the 2-D parameters from the CCF

As all CCF constituents, the 2-D PSF CCF is a FITS file. Its content can be accessed through standard FTOOLS. The easiest way to visualise the content of a FITS file is through the FITS file viewer fv. The following image shows the content of the ELLBETA_PARAMS extension of the XRT1_XPSF_0011.CCF file (the XRT2* and XRT3* files have the same structure) as visualised by fv.

Fig.1: fv view of the 2-D PSF CCF for XRT1. Left panel: the ELLBETA_PARAMS extension: Right panel: the content of the PARAMS column, once the function Expand under the Modify menu is activated. Legenda: ENERGY: the value E₀ of the energy grid node; THETA: the value θ₀ of the off-axis grid node; PHI: the value φ₀ of the azimuthal angle grid node (currently the 2-D PSF parametrisation is not dependent on the azimuthal angle): PARAMS: the parameters describing the King+Gaussian function envelope of the 2-D PSF: 1: the King function core radius r₀ (in arcseconds); 2: the King function power-law slope α; 3: the King function (also the Gaussian function) ellipticity ε; 4: the Gaussian Full Width Half Maximum (in arcseconds); 5: the ratio N between the Gaussian and the King function peak values

Users are recommended to read the fv manual to learn how to use it. However, its Graphical User Interface is rather straightforward, once a file is read with the command:

  fv XRT1_XPSF_0011.CCF &

FITS files can be also accessed through command-line driven FTOOLS. The following example shows how to display on the standard output the value of the power-law slope of the King function corresponding to the following input values: E₀=100 eV; θ₀=0.00261 radians; and φ₀=0:

  ftabpar fitsfile=XRT1_XPSF_0011.CCF+71 column=4 row=4 element=2
  pget ftabpar value

where 71 is the number of the ELLBETA_PARAMS extension in the CCF, and the interpretation of the other parameters in ftabpar is left as an exercise to the user. There are several different ways to achieve the same goal (using other FTOOLS such as fdump). The method shown above is - as far as the writer's experience can tell - the most robust to use in scripting.
If the user has no prior knowledge of the column/row/element to which a certain parameter for a certain term [E₀, θ₀, φ₀] correspond, the following loop (in C-shell syntax) may be used as template:

  #
  # Start a loop
  #
  @ i == 1
  #
  # Calculate the number of grid elements in the CCF
  #
  fkeypar fitsfile=/ccf/pub/XRT3_XPSF_0011.CCF+71 keyword=NAXIS2
  set nvalues = `pget fkeypar value`
  #
  # Loop on the grid points
  #
  loop:
  #
  # Determine the energy, off-axis and azimuthal angle corresponding
  # to each grid point
  #
  ftabpar fitsfile=/ccf/pub/XRT3_XPSF_0011.CCF+71 column=1 row=${i}
  set energy = `pget ftabpar value`
  ftabpar fitsfile=/ccf/pub/XRT3_XPSF_0011.CCF+71 column=2 row=${i}
  set theta = `pget ftabpar value`
  ftabpar fitsfile=/ccf/pub/XRT3_XPSF_0011.CCF+71 column=3 row=${i}
  set phi = `pget ftabpar value`
  #
  # Check if the grid point corresponds to the inputs
  # If so, read the corresponding profile power-law slope
  #
  if ("${energy} == ${e_0}" && "${phi} == ${f_0}" && "${theta} == ${t_0}") then
    ftabpar fitsfile=/ccf/pub/XRT3_XPSF_0011.CCF+71 column=4 row=4 element=2
    set slope = `pget ftabpar value`
    goto label_out
  endif
  #
  # End of the loop
  #
  @ i ++
  (if ${i} =< ${nvalues}) goto loop:
  label_out:

How to generate a PSF image for arbitrary [E₀, θ₀, φ₀]

calview

SAS includes a specific GUI tool to visualise CCF constituents: calview. Fig.3 shows the main calview window, which appears upon (C-shell syntax):

  setenv SAS_CCF ccf.cif
  calview &

Fig.3: the main calview window.

In Fig.4 we show two examples of the 2-D PSF generated through calview for different choices of the parameters E₀ and θ₀. Note that the input values in this example do not correspond to any of the predefined energy or off-axis angle grid nodes. calview interpolates between the closest points in the available grid.

Fig.4: Examples of 2-D PSF generated by calview. Left panel: Instrument=EMOS1, Energy=500, Theta=120; Right panel: Instrument=EMOS2, Energy=1750, Theta=600. In both cases: Accuracy Level=ELLBETA.

The PSF files produced by calview are in FITS format, and can therefore be saved on the local disk, or manipulated with standard FTOOLS or ds9 (indeed calview automatically runs ds9 on them). However, these files are produced with a standard size, and cannot be customised to reproduce the exact PSF corresponding to the position of a specific source.

psfgen

The command-line task psfgen has been specifically designed with this purpose in mind. By running:

  psfgen energy=2500 theta=600 xsize=1000 ysize=1000 \
    ccf=ccf.cif output=mos1_psf.img level=ELLBETA instrument='M1'

the user generates a 1000x1000 pixels FITS image mos1_psf.img corresponding to the MOS1 2-D PSF for E₀=2500 eV and θ₀=10 arcminutes (=600 arcseconds). By running:

  psfgen image=mos1.img energy="100 2000 4500" output=mos1_psf.img level=ELLBETA

the user generate a FITS image mos1_psf.img corresponding to the linear combination (with equal weights) of MOS1 PSFs corresponding to E₀=100, 2000, and 4500 eV and the MOS1 field-of-view imaged in mos1.img (this image having been created by xmmselect or evselect, and thus containing the correct DSS). By running:

  psfgen image=mos2.img instrument='M2' ccf=ccf.cif energy="100" region="(DETX, DETY) IN circle(0, 0, 200)" \
    output=mos2_psf.img level=ELLBETA rotate=45 xsize=500 ysize=500

the user generates a FITS image mos2_psf.img of the MOS2 PSF at 100eV corresponding to the circular region in detector coordinates: (DETX, DETY) IN circle(0, 0, 200) and rotated by 45 degrees.

Users can find more information on the usage of psfgen in the on-line SAS documentation

Last Updated: 16 April 2010

---

Caveats The primary reasons for making the 2-D PSF parametrisation available within the CCF at this time are to facilitate the ongoing testing/refinements and to simplify the development of the SAS software that uses it. For this reason, it is not employed as the default PSF by any of the SAS 10 software. We stress very strongly that the use of the 2-D PSF by users is generally deprecated but that if it is used, the resulting analysis should be treated with extreme caution.

---