Last modified: January 2023

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/splitroi.html
AHELP for CIAO 4.16

splitroi

Context: Tools::Region

Synopsis

Convert the output of roi into a format usable by dmfilth

Syntax

splitroi infiles outhead

Description

This script takes the output of the roi tool - a set of FITS files, one per source, each with a SRCREG and BKGREG block - and converts them into ASCII region files that can be used by dmfilth. Please see the An Image of Diffuse Emission thread for more information.

Unlike most CIAO scripts and tools, this script does not have a parameter file. It will also over-write any existing file; those called outhead + ".src.reg" and outhead + ".bg.reg".

Viewing the output in ds9

The script creates two ASCII region files: outhead.src.reg and outhead.bg.reg. In all but the most-simple cases these files can not be directly viewed by ds9. The dmmakereg tool can be used to convert to a FITS region file, and that can then be read by ds9. For example, assuming that splitroi has been run with the outhead argument set to sources, then

unix% punlearn dmmakereg
unix% dmmakereg "region(sources.bg.reg)" sources.bg.fits
unix% ds9 img.fits -region sources.bg.fits

Examples

Example 1

unix% roi ... outsrcfile=src%d.fits ...
unix% splitroi src\*fits sources

Here we convert the src*fits files created by roi into two ASCII region files - sources.src.reg and sources.bg.reg - which can then be used as the values of the srclist and bkglist parameters of dmfilth. For example:

unix% pset dmfilth srclist=@sources.src.reg
unix% pset dmfilth bkglist=@sources.bg.reg

The \ in src\*fits is needed to ensure that the script, rather than the shell, does the file search. The following example shows other ways that multiple files can be passed through to the script.

Example 2

unix% splitroi src1.fits,src2.fits,src3.fits sources

The first argument supports the CIAO stack syntax, so here we use a comma-separated list of files. An alternative is to use the "@" syntax to read in the names from a file, e.g.

unix% ls -1 sources/src*fits > srcs.dat
unix% splitroi @srcs.dat sources

Changes in scripts 4.15.2 (April 2023) release

Updated to use the new CXC region module which provides increased numerical precision when writing out the region properties.

Changes in scripts 4.11.1 (December 2018) release

Updated to restore the use of the region string "point(0,0)" for empty regions. In CIAO 4.10, the output would contain blank lines for empty regions; blank lines are skipped when the files are processed as stacks which could cause a mismatch in source to background mapping.

Changes in the December 2012 Release

The script has been updated to work in CIAO 4.5.

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.

See Also

concept
subspace
dm
dmmasks, dmregions
tools::aspect
dither_region
tools::background
create_bkg_map
tools::detect
celldetect, get_src_region, vtpdetect, wavdetect, wrecon, wtransform
tools::gratings
tg_create_mask, tgdetect, tgidselectsrc, tgmatchsrc
tools::image
dmimgdist, dmimgfilt
tools::region
bkg_fixed_counts, convert_ds9_region_to_ciao_stack, dmcontour, dmgroupreg, dmimghull, dmimglasso, dmmakereg, psf_contour, rank_roi, regphystocel, roi