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

Prerequisites

None

Useful Links

This thread makes use of the following LHEASOFT tasks:

Caveats

Last Reviewed: 02 DECEMBER 2021, for SAS v20.0

Last Updated: 31 May 2018

 


PROCEDURE

 

As of SAS v10, 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.

The CCF constituents describing the 2-D PSF are XRT[123]_XPSF_0011.CCF and later. Version 0011 has been used to illustrate this thread. You can check the latest versions of any CCF file by looking into the page List of XMM-Newton Current Calibrations. 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 is provided in Read, Rosen, Saxton & Ramirez 2011, A&A, 534, 34 and 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 E0 of the energy grid node; THETA: the value θ0 of the off-axis grid node; PHI: the value φ0 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 r0 (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: E0=100 eV; θ0=0.00261 radians; and φ0=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 [E0, θ0, φ0] 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 [E0, θ0, φ0]

 

calview
 

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

  setenv SAS_CCF ccf.cif
  calview &

 


Fig.2: the main calview window.
 

In Fig.3 we show two examples of the 2-D PSF generated through calview for different choices of the parameters E0 and θ0. 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. These images are produced using the option View->PSF from the GUI top menu and setting the Accuracy Level to ELLBETA.
 


Fig.3: 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, that is, to reproduce the exact PSF corresponding to the position of a specific source. Three examples are given below.

 

By running:

  psfgen energy=2500 coordtype=TEL x=600 y=0 xsize=1000 ysize=1000 \
     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 E0=2500 eV and θ0=10 arcminutes (=600 arcseconds). Pixels will have a fixed size of 1x1 arcsecond2 for the ELLBETA or EXTENDED models (for other models, e.g. MEDIUM, the pixel size is 1.1x1.1 arcsecond2 .

 

By running:

  psfgen image=mos1.img energy="100 2000 4500" weight="0.2 0.5 0.3" \
     output=mos1_psf.img level=ELLBETA coordtype=eqpos x=188.25 y=64.21

    the user generates a FITS image mos1_psf.img corresponding to the combination (with weights 0.2,0.5,0.3) of MOS1 PSFs of energy E0=100, 2000, and 4500 eV at the celestial position (RA=188.25, DEC=64.21) within the MOS1 field-of-view imaged in mos1.img (this image having been created by xmmselect or evselect, and thus containing the correct DSS), with a default size of 199 x 199 pixels. The image of the PSF will be rotated by the position angle of the observation to have the correct orientation relative to the image mos1.img.

 

By running:

  psfgen instrument='M2' energy="100" coordtype=det x=10000 y=5000 \
     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 of a source positioned at detector coordinate position (detx=10000, dety=5000), rotated by 45 degrees.

 

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


 

Caveats

None