psf

Synopsis

A Python module to calculate the size or enclosed-counts fraction of the Chandra PSF

Description

The psf module is used to calculate an estimate of the size of the Chandra PSF at a given off-axis position and energy, or the enclosed fraction of energy at a given off-axis position and extraction radius.

What does 'size of the PSF' mean?

For this module, the size of the PSF refers to the radius of a circular region that encloses a given fraction of the counts from a point source. The values are calculated by interpolating the values from the REEF file found in the CALDB (Radial Encircled Energy Function described in the OGIP Calibration Memo CAL/GEN/92-020). It is therefore an approximation to the true PSF.

Loading the module

The module can be loaded by saying

import psf

Functions provided by the module

The following functions are provided by the module:

Using the module

The module must be initialized using the psfInit() routine, which returns a value that is then used by the psfFrac() or psfSize() routines. The psfClose() routine is then used to release the resources acquired bu the psfInit() routine.

psfClose(pdata)

The psfClose() routine releases the data read in by the psfInit() routine. It has no return value and is sent one argument, the object returned by psfInit().

psfInit(filename)

This routine reads in the PSF data from the given filename (the CALDB REEF file) and returns an object which is used by the psfFrac() and psfSize() routiens. The psfClose() routine is used to release this information.

psfFrac(pdata, energy, theta, phi, size)

Returns the enclosed-count fraction for a PSF with the given energy (in keV), position (theta in arcminutes and phi in degrees), and size (in arcsec).

psfSize(pdata, energy, theta, phi, ecf)

Returns the radius, in arcsec, for a PSF with the given energy (in keV), position (theta in arcminutes and phi in degrees), and enclosed-count fraction (0 to 1).

Calculating the theta and phi values for a sourec

The dmcoords tool can be used to convert a position (e.g. celestial or in sky coordinates) to the required theta and phi coordinate system (the MSC coordinate system described in "ahelp coords"). Please note that

• the dmcoords output for theta may not be in arcminutes;
• due to the telescope dither there is no unique mapping between off-axis position and sky or celestial location of a source.

Example 1

>>> from ciao_contrib.runtool import calquiz
>>> import psf
>>> calquiz(telescope="CHANDRA", product="REEF")
>>> reef = calquiz.outfile
>>> pdata = psf.psfInit(reef)
# ... do something interesting
>>> psf.psfClose(pdata)

Here we load in the PSF data into the pdata variable, do something with it, then release the data. The following examples can be considered as the "interesting" part of the code above.

Example 2

>>> f2 = psf.psfFrac(pdata, 2, 4, 225, 2)
>>> f3 = psf.psfFrac(pdata, 2, 4, 225, 3)
>>> f4 = psf.psfFrac(pdata, 2, 4, 225, 4)
>>> print("Fractions: {0} {1} {2}".format(f2, f3, f4))
Fractions: 0.778108093119 0.92679541645 0.952283503534

Here we calculate the enclosed-count fractions (ECF) for the radii 2, 3 and 4 arcseconds for a source located at an off-axis angle of 4 arcminutes with a PHI of 225 degrees. The calculation is made at an energy of 2 keV.

Example 3

>>> e5 = psf.psfSize(pdata, 2, 4, 225, 0.5)
>>> e7 = psf.psfSize(pdata, 2, 4, 225, 0.7)
>>> e9 = psf.psfSize(pdata, 2, 4, 225, 0.9)
>>> print("Radii (arcsec): {0} {1} {2}".format(e5, e7, e9))
Radii (arcsec): 1.26743534207 1.76177912951 2.63139134645

Here we calculate the radii where the enclosed-count-fractions of the source are 0.5, 0.7 and 0.9. As with the previous example the source is at 4 arcminutes off-axis angle at PHI of 225 degrees and has an energy of 2 keV.

Example 4

The psfSize() and psfFrac() routines only calcualte a single value, but they can easily be used to calculate a range of values. The following routine (esize) calculates the 90% enclosed-counts fraction for a source at the given theta and phi values for the energy range 0.3 to 9 keV:

def esize(pdata, theta, phi):
    "Calculate the 90% ECF for a range of energies"

    energies = np.arange(0.3, 9.1, 0.1)
    sizes = []
    for e in energies:
        sizes.append(psf.psfSize(pdata, e, theta, phi, 0.9))

    return (energies, np.array(sizes))

which could be used to plot up the curve by saying:

chips> (e, s) = esize(pdata, 8, 345)
chips> add_curve(e, s, ["symbol.style", "none"])
chips> set_plot_xlabel("Energy (keV)")
chips> set_plot_ylabel("Radius (arcsec)")
chips> set_plot_title(r"\theta=8' \phi=345^\textdegree")
chips> add_label(0.1, 0.9, "90%", ["coordsys", PLOT_NORM])

Location of the REEF File

The safest way to access the REEF file need by the psfInit() routine is to use the calquiz tool to query the calibration database:

unix% punlearn calquiz
unix% calquiz telescope=CHANDRA product=REEF mode=h
unix% pget calquiz outfile
/soft/ciao/CALDB/data/chandra/default/reef/hrmaD1996-12-20reefN0001.fits
[1]

where the above output assumes that the environment variable CALDB is set to /soft/ciao/CALDB.

If you have the CIAO Contributed Scripts and Modules package installed then you can use the following Python code to access the file:

import psf
from ciao_contrib.runtool import calquiz
calquiz(telescope="CHANDRA", product="REEF")
reef = calquiz.outfile
pdata = psf.psfInit(reef)

The latest information on the REEF file can be found in the Chandra CALDB website, in particular the HRMA calibration page.

See Also

calibration

ardlib

tools

acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, add_grating_orders, add_grating_spectra, addresp, asphist, combine_spectra, dither_region, dmarfadd, dmextract, eff2evt, fluximage, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, merge_all, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, rmfimg, sky2tdet, specextract