Synopsis

Determine if a source is extended within a confidence interval.

srcextent  srcfile outfile [psffile] [regfile] [shape] [srcsize]
[imgsize] [binfactor] [mincounts] [minthresh] [clobber] [verbose]

Description

Calculate the size and associated uncertainty of a photon-count source image or list of source images using the Mexican Hat Optimization (MHO) algorithm (Houck 2007). The uncertainty is a 90% confidence estimate derived from Monte Carlo trials using MARX simulated data.

If a point-spread function (PSF) image is supplied, the tool also makes a determination about whether the source is extended within the confidence interval.

The MHO algorithm looks for a source approximately centered in the image with approximate coordinates taken from an input region specifier. It then derives the parameters of the elliptical Gaussian which is most strongly correlated with the source image. The elliptical Gaussian parameters [center position (x,y), 1-sigma semi-axes (a,b) and position angle (theta)] are derived by maximizing the Mexican-Hat wavelet transform. The tool also computes sqrt((1/2)(a^2+b^2)) as an 'apparent size' estimate which is more robust than the individual semi-major and semi-minor axis values.

The tool applies the MHO algorithm to both PSF and source images, and then tests whether the two apparent sizes are consistent given the image statistics. It derives an estimate of source 'intrinsic size' as the radius (sigma) of the gaussian that, when convolved with the PSF gaussian, would have the same size as the observed source image.

The tool processes the PSF first, if it is present, and uses the result as an initial guess to guide fitting on the source image. If no PSF is provided, the user must supply an initial guess for the image size in the srcsize parameter. For best results, this initial guess should be within about a factor of three of the actual source size.

The PSF and source data may be provided either as event files or images. Event data are preferred. If using an image, it is necessary to crop the image so the source centroid is at the image center to provide appropriate estimates.

Confidence Limits on the Position Angle

The tool currently does not calculate the confidence limits on the position angle. They will always be reported as INDEF in the output:

 Source Observed Size: 1.10 " @ PA 16.87 deg at pixel coords 3531.8, 3782.3
  90% Confidence intervals: (1.04 -- 1.17) @ (INDEF -- INDEF)

For technical details on how the tool works, please see the documents

http://cxc.harvard.edu/csc/memos/files/Houck_source_extent.pdf http://cxc.harvard.edu/csc/memos/files/Houck_intrinsic_size.pdf

Example 1

srcextent srcfile="acisf00635_000N001_r0001b_regevt3.fits"
outfile="acisf00635_000N001_r0001b_out3.fits"
psffile="acisf00635_000N001_r0001b_psf3.fits"
regfile="acisf00635_000N001_r0001_reg3.fits"

Calculate the source, PSF, and intrinsic source size from a source event file, normalized PSF image, and a FITS region file.

Example 2

srcextent srcfile="acisf00635_000N001_r0001b_regevt3.fits"
outfile="acisf00635_000N001_r0001b_out3.fits"
psffile="acisf00635_000N001_r0001b_psf3.fits" regfile="ellipse.reg"

Calculate the source, PSF, and intrinsic source size from a source event file, normalized PSF image, and an ASCII region file.

Example 3

srcextent srcfile="acisf00635_000N001_r0001b_img3.fits"
outfile="acisf00635_000N001_r0001b_out3.fits"
psffile="acisf00635_000N001_r0001b_psf3.fits"

Calculate the source, PSF, and intrinsic source size from a source image and a normalized PSF image. With no input regfile, the tool assumes that the source image is exactly centered in the input image.

Example 4

srcextent srcfile="acisf00635_000N001_r0001b_regevt3.fits"
outfile="acisf00635_000N001_r0001b_out3.fits"
psffile="acisf00635_000N001_r0001b_projrays3.fits"
regfile="acisf00635_000N001_r0001_reg3.fits"

Calculate the source, PSF, and intrinsic source size from a source event file and a PSF event file.

Example 5

srcextent srcfile="acisf00635_000N001_r0001b_img3.fits"
outfile="acisf00635_000N001_r0001b_out3.fits"
psffile="acisf00635_000N001_r0001b_projrays3.fits"
regfile="acisf00635_000N001_r0001_reg3.fits"

Calculate the source, PSF, and intrinsic source size from a source image and a PSF event file.

Example 6

srcextent srcsize=35 srcfile="acisf00635_000N001_r0001b_img3.fits"
outfile="acisf00635_000N001_r0001b_out3.fits"

Calculate the source size from a source image. With no input regfile, the tool assumes that the source image is exactly centered in the input image.

Example 7

srcextent srcfile="acisf00635_000N001_r0001b_regevt3.fits"
outfile="acisf00635_000N001_r0001b_out3.fits" regfile="ellipse.reg"

Calculate the source size from a source event file.

Example 8

srcextent srcsize=50 srcfile="acisf00635_000N001_r0001b_psf3.fits"
outfile="acisf00635_000N001_r0001b_out3.fits"

Calculate the PSF size from a PSF image. With no input regfile, the tool assumes that the source image is exactly centered in the input image.

Example 9

srcextent
srcfile="acisf00635_000N001_r0001b_regevt3.fits,acisf00635_000N001_r0002
b_regevt3.fits"
outfile="acisf00635_000N001_r0001b_out3.fits,acisf00635_000N001_r0002b_o
ut3.fits"
psffile="acisf00635_000N001_r0001b_psf3.fits,acisf00635_000N001_r0002b_p
sf3.fits"
regfile="acisf00635_000N001_r0001_reg3.fits,acisf00635_000N001_r0002_reg
3.fits"

Calculate the source, PSF, and intrinsic source size for each source with a stack of source event files, PSF images, and corresponding region files.

Parameters

Detailed Parameter Descriptions

Parameter=srcfile (file required filetype=input stacks=yes)

Source file, FITS image or FITS event list

If a stack of files is used, the same number of files must be specified in the stack for the srcfile, outfile, psffile, and regfile parameters.

Parameter=outfile (file required filetype=input stacks=yes)

Output file, FITS table

If a stack of files is used, the same number of files must be specified in the stack for the srcfile, outfile, psffile, and regfile parameters.

Parameter=psffile (file not required filetype=input stacks=yes)

PSF file, FITS image or FITS event list

The Chandra HRMA PSF can be simulated with ChaRT and the instrument effects, including detector pixelization, can be simulated with MARX. See the ChaRT website for more information.

If a stack of files is used, the same number of files must be specified in the stack for the srcfile, outfile, psffile, and regfile parameters.

Parameter=regfile (file not required filetype=input stacks=yes)

Region File, ellipse or circle region, in FITS or ASCII

Required for event lists and recommended for image data. When working with image data, if the regfile is omitted, then the source of interest is assumed to be exactly centered in the input image.

ASCII-format region files may only contain CIRCLE and ELLIPSE shapes currently.

If a stack of files is used, the same number of files must be specified in the stack for the srcfile, outfile, psffile, and regfile parameters.

Parameter=shape (string not required default=gaussian)

Source shape [gaussian,disk]

If the shape is "gaussian" the source axes include a factor of 1/sqrt(3). If the shape is "disk", the factor is sqrt(2). Both factors are derived by maximizing the correlation with the elliptical Mexican Hat function with semi-axes, a_i; see Damiani et al 1997.

Parameter=srcsize (real not required default=0)

Crude estimate of source size in arcseconds.

For best results, this initial guess should be within about a factor of three of the actual source size.

Parameter=imgsize (real not required default=0)

Size of image in arcseconds.

Parameter=binfactor (integer not required default=0)

Image binning factor

Parameter=mincounts (integer not required default=15)

Minimum counts inside calculated ellipse threshold

Parameter=minthresh (integer not required default=6)

Minimum counts for source file threshold

Parameter=clobber (boolean not required default=no)

Clobber output file (yes/no)

Parameter=verbose (integer not required default=3)

Verbosity setting

CHANGES IN CIAO 4.2

The parameters "srcsize" and "imgsize" should be provided in units of arcseconds instead of pixels. This change is to be consistent with the output, which is reported in arcseconds.

Bugs

See the bugs page for this tool on the CIAO website for an up-to-date listing of known bugs.

See Also

tools

aprates, dmstat, lim_sens