Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/psfsize_srcs.html
AHELP for CIAO 4.16

psfsize_srcs

Context: Tools::Region

Synopsis

Compute the size of a circle enclosing a specified fraction of PSF.

Syntax

psfsize_srcs  infile pos outfile [energy] [ecf] [psffile] [verbose]
[clobber]

Description

`psfsize_srcs' will compute the size of a circle that encloses the specified fraction of the PSF at the specified energy for each of the input positions.

Users input a position as either a single RA/Dec pair or provide a table with RA and Dec columns. ASCII files can be used as long as they are readable by the DM ASCII kernel. (see ahelp dmascii). The header keyword information in the infile is used to convert the RA and Dec values to mirror coordinates (theta and phi) which are used together with the energy and ecf parameters to determine the output circle size.

The output file is an ASC-FITS-REGION format file with that can be used as input to other CIAO tasks or ds9 can be used to display the regions.


Examples

Example 1

psfsize_srcs evt.fits "10:04:33.8 +41:12:34" myout.fits energy=broad
ecf=0.9

This is an example where the tool computes a circle whose radius encloses 90% of the PSF at 2.3 keV (CSC 'broad' band energy) for the specified RA/Dec value. The information in the evt.fits file is used to setup the coordinate transforms from RA/Dec to mirror coordinates (theta and phi). The output file will contain an ASC-FITS-REGION file with a SHAPE, X, Y, R column. X, Y, and R are all returned in physical pixels.

Example 2

psfsize_srcs evt.fits "151.1410079341,41.2096249008" myout.fits
energy=1.0 ecf=0.9

This example we now specify the energy explicitly as 1.0 keV and use decimal degrees rather than sexagesimal notation.

Example 3

psfsize_srcs evt.fits "wavdetect.fits" myout.fits energy=wide ecf=0.68

In this example the pos parameter is now specified as a file name, in this case the source list output from wavdetect. Since it has RA and Dec columns they will be used. The size of the circle will enclose 68% of the PSF fraction at the Chandra Source Catalog's 'wide' band energy of 1.5keV.

Example 4

psfsize_srcs evt.fits "csc_output.tsv[opt kernel=text/tsv]" myout.fits
energy=broad ecf=0.50

ASCII files can also be input if they are compatible with the DM ASCII kernel. In this example we use an output from the Chandra Source Catalog stored in tab-separated-value format (TSV). This format requires the user specify the kernel option as shown.


Parameters

name type ftype def min max units reqd stacks
infile file input         yes no
pos string         J2000 yes no
outfile file output         yes no
energy string   broad         no
ecf real   0.9 0.0 0.999     no
psffile file input CALDB         no
verbose integer   0 0 5      
clobber boolean   no          

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=no)

Input image or event file

The header keywords in the infile file are used to setup all the coordinate transforms needed to go from celestial coordinates to mirror coordinates. The following keywords need to be present:

INSTRUME, DETNAM, RA_NOM, DEC_NOM, RA_PNT, DEC_PNT, ROLL_PNT, SIM_X*, SIM_Y*, SIM_Z*, DY_AVG*, DZ_AVG*, DTH_AVG*, FIRSTROW**, NROWS**

* are optional, but should be present to get accurate estimates of the CHIP coordinates. They do not affect mirror coordinates nor the output size. ** are also optional. If they are not present, eg for HRC datasets, then the output "near_chip_edge" may be inaccurate for ACIS subarray datasets.

The input file should not be a merged event file or co-added image. In particular the *_NOM and *_PNT values of those products may be insufficient to get the information needed for the coordinate transforms.

Parameter=pos (string required default= units=J2000 stacks=no)

RA and Dec value or filename with RA and Dec values

The input position must be in celestial coordinates. It can either be input as an RA/Dec pair, or as a filename.

Single Set of Values

If a single RA/Dec value pair is input, then they can be in either decimal degrees or in sexagesimal format. Positive declinations expressed in sexagesimal format must include the "+" sign. Decimal degrees should be separated by a comma.

Good Bad
10:04:33.8 +41:12:34 10:04:33.8 41:12:34
10 04 33.8 +41 12 34 10 04 33.8 41 12 34
151.1410079341,41.2096249008 151.1410079341 41.2096249008
151.1410079341,41.2096249008 10 04 33.8,41.2096249008
Filename

If a filename is specified, the tool will look for the columns named "RA" and "DEC". If they do not exist, the first two columns in the file are used. Columns may be renamed on the fly using DM virtual file syntax. The following examples are all valid file names

wavdetect.fits
some_catalog.fits[cols ra=ra_j2000,dec=dec_j2000]
some_catalog.txt[flux=1e-5]
cscview_output.tsv[opt kernel=text/tsv]

Parameter=outfile (file required filetype=output default= stacks=no)

The output file name

The output file is an ASC-FITS-REGION format file that contains the output source size in the "R" (radius) column. As is the convention, the units of the X, Y, and R columns are stored in physical pixels. The SHAPE column is always a 'circle' and the COMPONENT number is simply a integer going from 1 to N, where N is the number of input positions.

The following columns are also created representing the various coordinate transforms:

Parameter=energy (string default=broad stacks=no)

Single energy or CSC energy band

A single energy value or the name of a single energy band may be input.

Band names

The following names - based on the definitions from the Chandra Source Catalog

Band name Effective Energy [keV]
broad 2.3
soft 0.92
medium 1.56
hard 3.8
ultrasoft 0.4
wide 1.5
Single Energy

Alternatively, any single monochromatic energy, in keV can be specified. The value should be between 0.2 and 10.0 keV.

Parameter=ecf (real default=0.9 min=0.0 max=0.999 stacks=no)

Fraction of PSF to enclose

The output region will contain a circle region that encloses this fraction of the PSF. The PSF technically has infinite extent so a value of 1.0 would create an infinitely large region. Typical values will be 0.5 (50%, ie FWHM), 0.68 (68%, ie 1 sigma), and 90%.

Parameter=psffile (file filetype=input default=CALDB stacks=no)

The PSF calibration file name

The name of the Chandra Radially Encircle Energy Fraction calibration file. The default, 'CALDB', will signal the tool to look for the file in the Chandra Calibration Database.

Parameter=verbose (integer default=0 min=0 max=5)

Tool chatter level

Controls the amount of information tool prints to the screen.

Parameter=clobber (boolean default=no)

Remove outfile if it already exists?


Changes in CIAO 4.7.2 (April 2015) release

Standard HISTORY records have been added for this tool. There is also a correction for the "near_chip_edge" calculation for ACIS subarray datasets.

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 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.

See Also

tools::aspect
asp_offaxis_corr
tools::coordinates
dmcoords
tools::download
install_marx
tools::image
aconvolve, acrosscorr, arestore, dmfilth, dmregrid
tools::response
arfcorr, make_psf_asymmetry_region, psf_project_ray, simulate_psf, src_psffrac