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:
- RA and DEC : original location expressed in decimal degrees
- THETA and PHI : off axis angle away from and around the optical axis
- DETX and DETY : Chandra Focal Plane coordinates
- CHIP_ID, CHIPX, CHIPY : Chandra instrument coordinates. If the optional SIM keywords are missing from the infile, these coordinates will not be accurate.
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