srcextent

Synopsis

Determine if a source is extended within a confidence interval.

srcextent  srcfile outfile [psffile] [regfile] [shape] [x0] [y0]
[srcsize] [imgsize] [theta] [binfactor] [mincounts] [minthresh]
[sigmafactor] [psfblur] [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 fits the PSF first, if it is present. The initial guess at PSF size is given by the estimated 90 percent ECF size. The fit PSF size is then added in quadrature with the value of psfblur to give the size to be compared to the source size. The tool then fits the source image. In this case the initial guess is the size of the input source region times the value of the parameter sigmafactor. For best results, this initial guess should be within about a factor of three of the actual source size. When the input source data is an event file, the data are binned to create an image. The image binning size is 1 pixel or the PSF image pixel size, whichever is smaller.

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)

Technical Details

• Measuring Detected Source Extent Using Mexican-Hat Optimization: https://cxc.harvard.edu/csc/memos/files/Houck_source_extent.pdf
• Estimating Intrinsic Source Size: https://cxc.harvard.edu/csc/memos/files/Houck_intrinsic_size.pdf

Examples

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

A CSC PSF file may be used, with two image blocks, PSF and BINPSF, each with a header keyword BIN. In this case the block with the smaller value of BIN is used.

Parameter=regfile (file 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.

The size of the ellipse is multiplied by the value of the sigmafactor parameter and is used as the initial source size guess for the source data fit (unless srcsize = -1 ). The intent is to scale the ellipse to a 90 percent ECF.

Parameter=shape (string 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=x0 (real default=INDEF)

Estimate of x-position in sky coordinates

Parameter=y0 (real default=INDEF)

Estimate of y-position in sky coordinates

Parameter=srcsize (real 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.

A value of -1 indicates that the initial guess will use the off axis angle value given in the theta parameter to look up the 90-percent ECF size relationship.

Parameter=imgsize (real default=0)

Size of image in arcseconds.

Parameter=theta (real default=0)

Off axis angle in arcmin. Used only if imgsize = -1.

Parameter=binfactor (integer default=0)

Image binning factor

Parameter=mincounts (integer default=15)

Minimum counts inside calculated ellipse threshold

Parameter=minthresh (integer default=6)

Minimum counts for source file threshold

Parameter=sigmafactor (real default=0.533)

Radio of desired sigma to wavdetect guess.

Parameter=psfblur (real default=0.1873)

Additional aspect blur to add in quadrature to PSF ellipse size.

The default value 0.1873 (arcseconds) is appropriate when the ECF lookup is used (srcsize = -1) and the instrument is ACIS.

Parameter=clobber (boolean default=no)

Clobber output file (yes/no)

Parameter=verbose (integer default=3)

Verbosity setting

Extended Source Threshold Criteria

The effect of the PSF blurring is approximated by assuming that the Gaussian sigma values add in quadrature:

sigma_intrinsic^2 + sigma_psf^2 = sigma_observed^2

and where each value has an associated uncertainty. Solving that expression for the intrinsic source sigma:

sigma_intrinsic = sqrt (sigma_observed^2 - sigma_psf^2)

The corresponding uncertainty, delta_sigma_intrinsic, is computed from the measurement uncertainties using standard analytic error propagation methods. A source is then labeled as extended if:

sigma_intrinsic > 5 * delta_sigma_intrinsic 

The threshold value is stored in the lev3_iss.par parameter file, which is a module used by srcextent; "plist lev3_iss" prints the parameter file to the screen.

Bugs

ASCII region files must have more than 1 row.  (30 Jan 2017)

ASCII format region files must contain more than 1 row. This is not a problem for CIAO-format ASCII files saved from ds9, which contain at least 2 rows (first row is a comment identifying the format). This bug only affects region files created by other means.

When using ASCII regions files, CIAO format regions are supported.  (04 Feb 2011)

The tool will fail if there are any non-comment lines in the file other than the region definition:

unix% cat flux.reg
# Region file format: DS9 version 4.1
# Filename: hrcf12810_000N001_repro_evt2.fits[EVENTS]
global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" 
source=1
physical
circle(16483.295,16325.297,24.139931) 

unix% srcextent
...
ValueError: substring not found 

Workaround:

Comment out or delete the additional lines in the file:

unix% cat flux.reg
# Region file format: DS9 version 4.1
# Filename: hrcf12810_000N001_repro_evt2.fits[EVENTS]
#global color=green dashlist=8 3 width=1 font="helvetica 10 normal roman" 
#source=1
#physical
circle(16483.295,16325.297,24.139931) 

Caveats

The srcsize parameter value must be within a factor of 3 of the source size.  (03 Jun 2010)

See Also

tools::composite

srcflux

tools::statistics

aplimits, aprates, dmstat, lim_sens