/ ciao4.17 / ahelp / psf_contour.html

Jump to: Description · Examples · Parameters · Relation to acis_extract · Changes in the scripts 4.16.2 (August 2024) release · Changes in the scripts 4.15.2 (April 2023) release · About Contributed Software · Bugs · See Also

AHELP for CIAO 4.17

psf_contour

Context: tools::region

Synopsis

Create a source region file from a simulated PSF

Syntax

psf_contour  infile outroot pos [method] [energy] [fraction]
[tolerance] [flux] [fovfile] [marx_root] [parallel] [nproc] [verbose]
[clobber]

Description

`psf_contour` simulates a monochromatic PSF at the input source position(s) and then creates a region which encloses the requested fraction of the PSF. This region is appropriate to use a source region for point sources.

The user has several choices for the kind of region to create. These include

contour: a polygon chosen to enclose the requested input fraction. This uses the dmcontour tool.
lasso: similar to `contour` except the edges follow the edge of pixel boundaries. This uses the dmimglasso tool.
convex_hull: the contour is computed to enclose the requested input fraction. Then the convex hull, another polygon, is computed the encloses the coordinates of the contour. As such the PSF fraction will be systematically higher than the PSF fraction requested, though usually the difference will be small. The convex hull will frequently have many fewer vertices and will be more efficient. This uses the dmimghull tool.
fitted_ellipse: the contour is computed to enclose the requested input fraction. Then the coordinates are fit in a least squares sense to an ellipse. The ellipse neither superscribes nor inscribes the polygon points, but rather approximates the polygon. As such, the actual PSF fraction will be slightly different than the original polygon.
ecf_ellipse: Directly finds an ellipse that enclosed the requested fraction of the PSF. This uses the dmellipse tool.

Users can supply an input table with a list of coordinates (R.A. and Dec.) and the script will generate regions for each source position. After the initial regions are created, the script will then check to see if any of the regions overlap. If so, then the script will decrease the requested PSF fraction of both sources and re-generate the regions. This repeats until the overlap is gone or until both sources reach the minimum PSF fraction (0.6, ie 60%). If this happens then the tool will stop trying to shrink the regions any more and will simply exclude the source regions from each other.

Four files are created for each source position:

${outroot}_i${srcno}.projrays : The MARX simulated PSF rays
${outroot}_i${srcno}.psf : The MARX PSF binned into an image and normalized.
${outroot}_i${srcno}.smpsf : The PSF smoothed with a Gaussian. This is the file used to generate the regions.
${outroot}_i${srcno}_src.reg : The output FITS format region file.

Note: since the PSF is being simulated then users can expect to see slightly different results each time this script is run. The random_seed parameter can be use to fix the random seed to generate repeatable results. The fidelity of the PSF can be controlled with the flux parameter. Increasing the flux will provide a better estimate of the PSF at the expense of taking longer to run.

Examples

Example 1

% psf_contour infile=acisf00635_repro_evt2.fits outroot=acis635
pos=246.9665257,-24.6805581 method=contour

In this example the input event file is used to simulate the PSF (at the default energy of 1.0keV) at a single source position, and then the source region is computed as a contour that encloses 90% of the PSF.

Example 2

% psf_contour infile=acisf00635_repro_evt2.fits outroot=acis635
pos=246.9665257,-24.6805581 method=lasso energy=6.7 frac=0.95

This is similar to example 1, except now the PSF is simulated at 6.7keV and the lasso algorithm is used to find the contour that encloses 95% of the PSF.

Example 3

% psf_contour infile=acisf00635_repro_evt2.fits outroot=acis635
pos=my_catalog.dat method=fitted_ellipse

In this example, the source position are taken from the input table: my_catalog.dat, which much contain RA and Dec columns (in decimal degrees). There will be one output file for each individual source listed in the input table. Each source region will be an ellipse that has been fitted to the contour.

Example 4

% psf_contour infile=hrc_repro_evt2.fits outroot=hrc
pos=my_catalog.dat"[cols ra=_raj2000,dec=_dej2000]" fov=hrc.fov

This is similar to the previous example. In this example the input file used to get the source positions has columns _RAJ2000 and _DEJ2000 instead of RA and Dec, so they columns are renamed on-the-fly using the datamodel's [cols ] syntax.

Parameters

name	type	ftype	def	min	max	units	reqd
infile	file	input					yes
outroot	file	output					yes
pos	file	input					yes
method	string		contour
energy	real		1.0	0.3	10.0	keV
fraction	real		0.9	0.6	0.95
tolerance	real		0.01	0.0001	0.1
flux	real		0.01	0.0000001	0.01	photon/cm**2/sec
fovfile	file	input
marx_root	file						no
parallel	boolean		yes				no
nproc	integer		INDEF	1			no
verbose	integer		1	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input image or event file.

The meta-data (header keywords) in the input image or event file is used to setup the MARX simulation and to compute various coordinates.

Parameter=outroot (file required filetype=output)

The root of the output file names

If the output root contains a directory, then that directory must already exist.

Parameter=pos (file required filetype=input)

Input position.

The input position can either be a pair of celestial coordinates or can be a table with RA and DEC values (in decimal degrees).

Parameter=method (string default=contour)

Method used to create the region

The choice of algorithm used to create the region. Options are

contour
lasso
fitted_ellipse
convex_hull
ecf_ellipse

See above for details on each algorithm.

Parameter=energy (real default=1.0 min=0.3 max=10.0 units=keV)

Monochromatic energy at which to simulate the PSF

Parameter=fraction (real default=0.9 min=0.6 max=0.95)

The target fraction of the PSF for the region to enclose.

The actual PSF fraction that the region encloses may be different from this value based on factors such as source crowding (regions are shrunk to avoid overlaps) and choice of region creation method.

Parameter=tolerance (real default=0.01 min=0.0001 max=0.1)

The +/- tolerance on the fraction.

Parameter=flux (real default=0.01 min=0.0000001 max=0.01 units=photon/cm**2/sec)

Photon flux of the point source to simulate the PSF.

The higher the flux the better the fidelity of the PSF simulation, and thus better the region will approximate the "true" PSF. The disadvantage is the increased run-time.

Parameter=fovfile (file filetype=input)

Field of view file name

The final output regions will be intersected with the field-of-view file (if it is supplied). This is important if any of the source regions intersect the edge of the detector; the FOV will clip the region to ensure that the proper geometric area of the region can be computed.

Parameter=marx_root (file not required)

The directory where MARX was installed.

The marx executable should be $marx_root/bin/marx.

If blank, then look for marx in the user's PATH and use that directory for marx_root.

Parameter=parallel (boolean not required default=yes)

Run code in parallel using multiple processors?

If multiple processors are available, then this parameter controls whether the tool should run various underlying tools in parallel.

If parallel=yes, then the script will create the PSFs and perform the initial region creation in parallel. However, the check for overlapping regions then proceeds serially.

Parameter=nproc (integer not required default=INDEF min=1)

Number of processors to use

If parallel=yes, then this controls the number of processes to run at once. The default, INDEF, will use all available processors. The value cannot be larger than the number of processors.

Parameter=verbose (integer default=1 min=0 max=5)

Amount of tool chatter level.

Parameter=clobber (boolean default=no)

Overwrite output files if they already exist?

Relation to acis_extract

This script is inspired by the acis_extract tool developed by the ACIS IPI team at PSU. The algorithm used to select the Gaussian kernel size to smooth the PSF is taken directly from acis_extract.

The actual contouring method in this tool is different than acis_extract (which also includes a contour simplification algorithm). Therefore it is expected that the results between this script and acis_extract will be numerically different but in a statistically insignificant way.

Changes in the scripts 4.16.2 (August 2024) release

marx_root parameter

If marx_root is blank, then look for marx in the user's PATH and derive marx_root from that path.

shrink region logic update

Clean up logic when overlapping sources cannot be shrunk any further and they are excluded from each other. In particular if more than 2 sources overlap the region logic becomes unnecessarily complex (possibly leading to long execution times).

Changes in the scripts 4.15.2 (April 2023) release

The ellipse fitting code can fail under some circumstances, usually when the contour forms a (nearly) perfect circle. The script tries increasing the flux level five times, after which it will now generate a circular region file rather than error out.

Additional updates to simplify code to used to parse the source coordinates.

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.

Bugs

There are no known bugs for this tool.