Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: December 2012

URL: http://cxc.harvard.edu/ciao/ahelp/srcextent.html
AHELP for CIAO 4.9

srcextent

Context: tools

Synopsis

Determine if a source is extended within a confidence interval.

Syntax

srcextent  srcfile outfile [psffile] [regfile] [shape] [x0] [y0]
[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)

Technical Details

  • Measuring Detected Source Extent Using Mexican-Hat Optimization: http://cxc.harvard.edu/csc/memos/files/Houck_source_extent.pdf
  • Estimating Intrinsic Source Size: 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

name type ftype def reqd stacks
srcfile file input   yes yes
outfile file input   yes yes
psffile file input   no yes
regfile file input   no yes
shape string   gaussian no  
x0 real   INDEF no  
y0 real   INDEF no  
srcsize real   0 no  
imgsize real   0 no  
binfactor integer   0 no  
mincounts integer   15 no  
minthresh integer   6 no  
clobber boolean   no no  
verbose integer   3 no  

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=x0 (real not required default=INDEF)

Estimate of x-position in sky coordinates

Parameter=y0 (real not required default=INDEF)

Estimate of y-position in sky coordinates

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

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) 
Tool does not add a history entry to the header.

The tool does not add a history entry to the output file header, which means the dmhistory tool cannot be used to recall the command.

Caveats

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

See Also

tools
aprates, dmstat, lim_sens, srcflux

Last modified: December 2012
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.