Last modified: March 2023

AHELP for CIAO 4.15


Context: tools::region


Create a source region file from a simulated PSF


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


`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

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:

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.


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.


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

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.

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


There are no known bugs for this tool.

See Also

dmmasks, dmregions
dmimgdist, dmimgfilt
bkg_fixed_counts, convert_ds9_region_to_ciao_stack, dmcontour, dmgroupreg, dmimghull, dmimglasso, dmmakereg, rank_roi, regphystocel, roi, splitroi