roi

Synopsis

Generates source and background regions from source list

roi  infile fovregion streakregion outsrcfile radiusmode bkgradius
[group] [targetbkg] [srcfactor] [srcfunction] [bkgfactor] [bkgfunction]
[bkgfactarg] [maxpix] [fovres] [streakres] [ignore_streaksrc]
[compute_conf] [evtfile] [num_srcs] [clobber] [verbose]

Description

`roi' reads in the positional and shape information from a FITS-format source list and creates a source region and a background region for each non-overlapping source region.

In parts of the field where the sources are close together, it is possible that the individual source regions will overlap. These are considered a single-source region, as any fitting/analysis will require some special treatment to separate the sources.

The group parameter controls whether these blended sources are output as a single (possibly large) group (in which case there could be fewer output regions than sources in the input list), or whether each source is output individually with only the sources it is blended with included (which leads to the same source being output in possibly multiple files; the first source is always unique). A third algorithm - a variant on the individual-output method - is to include the target source, but have all the other blended sources excluded.

The background regions are co-located at the source position with a radius determined by the radiusmode and bkgradius parameters. If radiusmode="mul", then the background radius will be bkgradius multiplied by the input R radius. If radiusmode="add", it will be R + bkgradius. The shape and angle are propagated from input source list.

Sources that are located in the background region of another source are excluded from that background region.

Algorithm

For each input source, the bounding box is found. If the bounding boxes for any two sources overlap, then the common area is searched pixel-by-pixel to see if any pixels fall in the region describing both sources. If so, then a singe source region is output. The maxpix parameter controls the number of pixels in the pixel-by-pixel search. If the regions are large and have a large overlap, this can be a very computationally-intensive process. If there are more than "maxpix" pixels, then the resolution is increased until the number of pixels checked is less than maxpix. Note that a single source region may contain many sources if the field is crowded.

Examples

Example 1

roi infile=srclist.fits outsrc="src%d.fits" radiusmode=mul bkgradius=2
group=group

Finds the unique source regions in srclist.fits. It outputs the source lists into files names src1.fits to srcN.fits. Background regions whose radius is twice the input radius are output in the second extension of each file.

Example 2

roi infile=srclist.fits outsrc="src%d.fits" radiusmode=mul bkgradius=2
group=individual

Repeating the previous example with "group=individual" means that there will be one file for each source listed in srclist.fits. Blended sources will included in multiple output region files.

Example 3

roi infile=srclist.fits outsrc="src%d.fits" radiusmode=mul bkgradius=2
group=individual fovregion="region(fov1.fits)"
streakregion="region(streak.reg)"

Repeating the previous example with "group=individual" means that there will be one file for each source listed in srclist.fits. Blended sources will included in multiple output region files.

Regions will be restricted to the field of view defined in fov1.fits. The readout streak defined in streak.reg will be excluded.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input FITS sourcelist

The input sourcelist must be in FITS format and contain X, Y, and R columns.

Parameter=fovregion (string required)

The field-of-view region

If a source region extends off the field of view, it may be necessary to include the FOV edge in the region definition, e.g. to restrict a background region to the FOV. The FOV region gets included in the definition of any region that intersects it (source or background).

The fov1.fits file is part of the standard Chandra data distribution. It can also be created by running the skyfov tool.

Parameter=streakregion (string required)

Region the defines the readout streak.

For ACIS data, bright sources can leave a trail of events along the CHIP-Y location that are commonly referred to as the "readout streak"; see ahelp acisreadcorr and ahelp acis_streak_map.

The acis_streak_map tool creates a region file that outlines the streak. roi can use the region defined in the streakregion to omit the streak from background regions. This is necessary because the streak is typically quite bright compared to the background and has completely different characteristics (spectrum, timing, etc).

Parameter=outsrcfile (file required filetype=output)

Output source region filename template

The output files are standard FITS REGION format. The number of files created depends on the group method used. Each file contains two extensions: one for the source region [srcreg] and one for the background region [bkgreg].

The outsrcfile name is used to construct each filename. It must contain a "%d" or other printf syntax (see man printf) to allow the tool to number the files. The %d will be replaced with the COMPONENT value for each source from the input source list.

Parameter=radiusmode (string required default=mul)

How is background radius determined

The background radius can either be a fixed annulus (add) or can be a multiple (mul) of the input radius.

Parameter=bkgradius (real required default=3)

Background radius factor

Number added to (add) or multiplied by (mul) the input radius to determine background radius.

Parameter=group (string default=group)

Controls how blended sources are output.

If sources are blended (overlapping) then the tool can output three different kinds of source (and associated background) lists.

• In the 'group' method, all the friends-of-friends sources are output in a single region file. So if A touches B and B touches C; you get a file with regions A, B, and C. NOTE: targetbkg="all" is required when using group="group".
• In the 'individual' method, only the sources that touch the "target" source are output. In the A touches B and B touches C example you get 3 regions output: A with B, B with A and C, and C with B.
• In the 'exclude' method, the "target" source is included, but the touching sources are excluded. In the A-B-C example, the output will have 3 regions, A and not-B, B and not-A and not-C, C and not-B.

Parameter=targetbkg (string default=all)

Make background around all srcs in region or just target?

The background can either be a single shape co-located at the 'target' shape (in the individual and exclude grouping methods) or can be a collection of shapes co-located at each of the sources in the src region. For the 'group' method, the 'all' background is required, as there is no 'target' source.

Parameter=srcfactor (real default=0)

Scale overlapping sources

This parameter control the scaling of overlapping sources in the region. This scaling factor is either added to or multiplies the overlapping source radii based on the srcfunction parameter setting.

See also bkgfactor and bkgfunction parameters.

Parameter=srcfunction (string default=add)

Scaling function for overlapping sources

This parameter controls whether the srcfactor is added to the source radii ("add") or whether it multiplies the source radii ("mul").

See also bkgfactor and bkgfunction parameters.

Parameter=bkgfactor (real default=0)

Background factor applied to the inner background radius

The background region is always an annulus around the source. The outer radius is controlled by the radiusmode and bkgradius parameters. The inner radius is controlled by the bkgfactor and bkgfunction parameters.

The inner background radius is determined by either adding bkgfactor number of pixels to the source radius or by multiplying the source radius by bkgfactor. The bkgfunction controls which operation is performed.

The default settings (bkgfunction="add" and bkgfactor="0") mean that the inner background radius is coincident with the source radius. If bkgfactor=1, for example, the tool will leave a one-pixel gap between source and background.

Parameter=bkgfunction (string default=add)

Controls how inner background radius is computed.

See the bkgfactor parameter description for more information.

Parameter=bkgfactarg (string default=target)

Apply bkgfactor and bkgfunction to "all" sources in the background or just the "target" source.

Parameter=maxpix (integer default=INDEF min=1)

Number of pixels allowed in overlap checking

When determining overlapping shapes, a pixel list is created at single-pixel resolution. If the number of pixels in that list is greater than 'maxpix', the resolution is increased by one and the processed repeated until the number of pixels is less than 'maxpix'. If the value is set to 'INDEF' (the default), then there is no maximum.

Parameter=fovres (real default=1)

Pixel resolution when determining if fovregion intersects any regions.

Parameter=streakres (real default=0.25)

Pixel resolution when determining if streakregion intersects any region.

Parameter=ignore_streaksrc (boolean default=yes)

Should the readout streak be ignored in the source regions?

If set to "yes" (the default), the readout streak is only excluded from the background regions. Setting ignore_streaksrc=no excludes the streak from both the source and background regions.

Since the streak by definition will run through a source, it is usually not a good idea to remove the streak from the source (only from the background). But there may be instances where it is desired, since the source is likely suffering from pileup in this case.

Parameter=compute_conf (boolean default=yes)

Compute confused state?

If set to "yes", the tool will compute the confused state of each source region; that is whether the source overlaps other sources or their backgrounds. The result is stored in the "CONFUSED" keyword. If set to no, the confused state is skipped and the keyword is omitted from the output files.

Parameter=evtfile (file not required filetype=input)

Optional input event file

If an event file is supplied, then the ROI_CNTS and ROIBCNTS in the output files will contain the number of counts in the source and background regions, respectively. If no evtfile is supplied, these will be 0.

Parameter=num_srcs (integer default=)

After the tool is run, this parameter contains the number of output files created.

Parameter=clobber (boolean default=no)

Remove existing output files?

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

Amount of tool verbosity.

Illustrative example

Suppose you have the following regions defined

ellipse(100,100,12,12,0)  # A
ellipse(110,110,12,12,0)  # B
ellipse(120,120,12,12,0)  # C
ellipse(140,140,12,12,0)  # D

(The # and the identifying letter are not part of the region definition.) So, A overlaps B. B overlaps A and C. C overlaps B. D will fall into the background of C. In the examples below, Al, Bl, Cl and Dl represent the background regions around A, B, C, and D respectively.

group='group' and targetbkg='all'

In this case, two output files are created.

group='group' and targetbkg='target'

This is not a valid parameter combination, as group="group" can only be used with targetbkg='all'.

group='exclude' and targetbkg='target'

In this case, you get one file for each source listed. Neighboring sources are excluded. The background only is around the target source.

group='exclude' and targetbkg='all'

In this case, you get one file for each source listed. Neighboring sources are excluded, background is from all sources.

group='individual' and targetbkg='target'

In this case, you get one file for each source listed. Neighboring sources are included.

group='individual' and targetbkg='all'

In this case, you get one file for each source listed. Neighboring sources are included, background is from all sources.

Bugs

Caveats

roi only supports ellipses and rotated boxes

The roi tool only supports infile with the SHAPE column set to ellipse or rotbox.

While the tool may seem to work with some other shapes (circle, annulus, pie), the output likely are not what was intended or expected.

The fovregion and streakregion may be arbitrary regions (polygons, etc).

See Also

concept

subspace

dm

dmmasks, dmregions

tools

celldetect, convert_ds9_region_to_ciao_stack, create_bkg_map, dither_region, dmcontour, dmgroupreg, dmimgdist, dmimgfilt, dmimghull, dmimglasso, dmmakereg, get_src_region, mkbgreg, mksubbgreg, roi, splitroi, tg_create_mask, tgdetect, tgidselectsrc, tgmatchsrc, vtpdetect, wavdetect, wrecon, wtransform