Compute approximate PSF fraction in circular source region
src_psffrac infile region outfile [energy] [psffile] [verbose] [clobber]
src_psffrac will compute an approximate value of the fraction of the PSF in circular regions at the specified monochromatic energy.
The tool takes the input region and will convert it to physical coordinates. It then converts the sky X,Y to Chandra mirror spherical coordinates, theta and phi. The radius of the circular regions, also now in physical pixels, is converted to arcseconds. These, together with the energy, are used to determine the PSF fraction. Source and background designations in the region file are ignored.
The output is a table with the following columns: 'shape', 'x', 'y', 'r', 'component', 'ra', 'dec', 'theta', 'phi', 'detx', 'dety', 'chip_id', 'chipx', 'chipy', 'psffrac', and 'bg_psffrac'. The bg_psffrac (background PSF fraction) is set to 0.0.
src_psffrac my_evt.fits "circle(4096,4096,10)" out.fits
The script will use the header information in my_evt.fits to convert (4096,4096) to an off-axis location and to convert the 10 pixel radius into arcsec. The output wil then contain a PSFFRAC column that represents the fraction of the PSF at 2.3 keV (default broad band energy) in a circle of that radius.
% dmlist out.fits"[cols x,y,r,theta,phi,psffrac]" data,clean # X Y R THETA PHI PSFFRAC 4096.0 4096.0 10.0 0.00579832374861 303.2998378920 0.96479740607505
src_psffrac my_evt.fits ciao.reg "out.dat[opt kernel=text/simple]" energy=1.0
Determine the PSF fraction at 1.0 keV for the circle defined in the region file 'ciao.reg'. The output file has been forced to be an ASCII file rather than the default FITS format.
% cat out.dat #TEXT/SIMPLE # SHAPE X Y R COMPONENT RA DEC THETA PHI DETX DETY CHIP_ID CHIPX CHIPY PSFFRAC BG_PSFFRAC circle 3800.0 4250.0 13.44000000000 1 246.8692985823 -24.55239375230 2.737798789146 230.9289380755 3886.062132065 3837.288881915 0 836.4909624943 863.8606465350 9.6849649464539e-01 0.0
Detailed Parameter Descriptions
Parameter=infile (file required)
An input event file or image. The file is used to get the world coordinates and detector information, including SIM information, necessary for the coordinate transforms.
Parameter=region (string required)
region definition: must be circular regions
The script only works for regions that contain a single circle shape. Multiple regions can be input using the CIAO stack syntax. Example of valid inputs include:
circle(4096,4096,10) ciao.reg region(ds9.reg) @region.lis
The tool will error out if circle regions are not supplied.
Parameter=outfile (file required)
Output file name
The output file will contain various coordinate transforms from the input X,Y as well as the final "psffrac" and "bg_psffrac" values. "bg_psffrac" is always set to 0.
The output will contain one row for each circle in the input region specification.
Parameter=energy (string default=broad)
Single energy band
A band can be given using a name (which will use the appropriate definitions from the Chandra Source Catalog) or by explicit limits.
The following names - based on the definitions from the Chandra Source Catalog - can be used; energies are given in keV and the effective energy is the monochromatic energy used to calculate the PSF fractions:
|Band name||Minimum Energy||Maximum Energy||Effective Energy|
The "wide" energy band can only be used with HRC.
A single value, in units of keV, can also be specified. For consistency with other tools, you can also used the format lo:hi:eff - where lo, hi and eff give the minimum, maximum and effective energies to use for the band (values are in keV).
Parameter=psffile (file default=CALDB)
PSF Calibration file
The name of the PSF calibration file. The default "CALDB" will instruct the tool to locate the file appropriate for the dataset in the Calibration Database.
Parameter=verbose (integer default=0 min=0 max=1)
Amount of tool chatter
Parameter=clobber (boolean default=no)
Remove outfile if it already exists?
Changes in CIAO 4.14.2 (April 2022) release
Removed dependence on old region module and some general code clean up. No functional change.
Changes in CIAO 4.12.3 (July 2020) release
The input file can now be an image or an table. The energy value used is now stored in the ENERGY keyword.
Changes in CIAO 4.7.2 (April 2015) release
Standard HISTORY records have been added for this tool.
REEF File Calibration Approximations
The Chandra point spread function varies significantly across the field of view and also as a function of energy. It becomes highly elliptical and contains many sharp features that makes providing an accurate 2D analytic model impossible. The calibration file used, the REEF (radially enclosed energy fraction) file, was created assuming a flat detector. This is accurate for HRC and for ACIS-7, but the other ACIS CCDs are tilted and cause additional asymetries.
About Contributed Software
This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions - such as how to ensure that the parameter file is available.
There are no known bugs for this tool.
- dmmasks, dmregions
- aconvolve, acrosscorr, aprates, arestore, arfcorr, convert_ds9_region_to_ciao_stack, dither_region, dmcontour, dmcoords, dmfilth, dmgroupreg, dmimgdist, dmimgfilt, dmimghull, dmimglasso, dmmakereg, dmregrid, dmstat, get_src_region, install_marx, lim_sens, make_psf_asymmetry_region, mkbgreg, mksubbgreg, psf_project_ray, psfsize_srcs, roi, simulate_psf, splitroi, src_psffrac, srcextent, srcflux, tg_create_mask