/ ciao4.17 / ahelp / src_psffrac.html

Jump to: Description · Examples · Parameters · Changes in CIAO 4.14.2 (April 2022) release · Changes in CIAO 4.12.3 (July 2020) release · Changes in CIAO 4.7.2 (April 2015) release · Caveats · About Contributed Software · Bugs · See Also

AHELP for CIAO 4.17

src_psffrac

Context: Tools::Response

Synopsis

Compute approximate PSF fraction in circular source region

Syntax

src_psffrac  infile region outfile [energy] [psffile] [verbose]
[clobber]

Description

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.

Examples

Example 1

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

Example 2

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

Parameters

name	type	def	min	max	reqd
infile	file				yes
region	string				yes
outfile	file				yes
energy	string	broad
psffile	file	CALDB
verbose	integer	0	0	1
clobber	boolean	no

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.

Band names

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
broad	0.5	7.0	2.3
soft	0.5	1.2	0.92
medium	1.2	2.0	1.56
hard	2.0	7.0	3.8
ultrasoft	0.2	0.5	0.4
wide	n/a	n/a	1.5

wide

The "wide" energy band can only be used with HRC.

Explicit value

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.

Caveats

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.

Bugs

There are no known bugs for this tool.