/ ciao4.17 / ahelp / psfsize_srcs.html

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

AHELP for CIAO 4.17

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:

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.