/ ciao4.16 / ahelp / rank_roi.html

Jump to: Description · Examples · Parameters · Changes in the scripts 4.15.2 (April 2023) release · About Contributed Software · See Also

AHELP for CIAO 4.16

rank_roi

Context: Tools::Region

Synopsis

Assign overlapping region area to highest ranking source.

Syntax

rank_roi  infile roifiles outfile [method] [verbose] [clobber]

Description

The `roi' tool is typically run with the parameter group=exclude which produces source regions with exclude any nearby overlapping sources. The issue is that the overlapping area is never assigned to any source region so the data in that region are not included any data analysis.

The `rank_roi' tool is a post processing step which takes the `roi' output files and assigns the overlapping area to the highest ranking source region. Source regions can be ranked based on several criteria: most flux, least flux, largest area, smallest area, brightest pixel or faintest pixel.

The output from `rank_roi' is a new stack of region files with the overlapping area assigned to the highest ranking source. The output root name must contain a Python string format token to represent the region number.

The `rank_roi` input file, infile, is used to calculate the ranking. It will typically be an image of either the counts or flux.

Note: For this algorithm to be useful, the `roi' tool had to have been run with group=exclude. Otherwise, the output will always be identical to the input.

Examples

Example 1

% roi infile=wav_src.fits outsrc="src_%04d.reg" group=exclude
target=target mode=h clob+
% rank_roi infile=broad_thresh.img roifile="src_*.reg"
outfile="rank_src_{:04d}.reg" method=max

This example shows the `roi' tool being run on a source list file using group=exclude. This will produce region that will exclude nearby overlapping source regions. The `roi' output root contains the C-formatting style '%04d' which gets replaced with the region number (4-digits with leading zeros).

The `rank_roi' tool is then used to assign the overlapping area to one of the source regions. The source with the maximum counts, obtained from the input image, broad_thresh.img, is given the highest ranking and assigned the overlapping area.

Example 2

In this example we show an longer example with actual numbers. We start by creating a region file with 2 overlapping source regions (ellipses):

$ cat << EOM > ciao.reg
ellipse(3972,4444,43,38,175)
ellipse(3945,4501,46,40,128)
EOM
$ dmmakereg region="region(ciao.reg)" out=ciao.fits ker=fits clob+

We then run the `roi' tool with group=exclude

$ roi ciao.fits outsrc="ciao_%d.src" group=exclude clob+ mode=h

`roi' writes out each source to a separate file based on the outsrcfile name template; the "%" is replaced by the source number. We can look at each file to verify the regions overlap and that each region is excluded from the other

$ dmlist ciao_1.src data,clean
Region Block: Ellipse(3972,4444,43,38,175)&!Ellipse(3945,4501,46,40,128)
#  POS(X,Y)                                 SHAPE              R[2]                                     ROTANG[2]                                COMPONENT
                       3972.0      4444.0 Ellipse                                    43.0        38.0                                175.0 NaN          1
                       3945.0      4501.0 !Ellipse                                   46.0        40.0                                128.0 NaN          1

and

$ dmlist ciao_2.src data,clean
Region Block: Ellipse(3945,4501,46,40,128)&!Ellipse(3972,4444,43,38,175)
#  POS(X,Y)                                 SHAPE              R[2]                                     ROTANG[2]                                COMPONENT
                       3945.0      4501.0 Ellipse                                    46.0        40.0                                128.0 NaN          1
                       3972.0      4444.0 !Ellipse                                   43.0        38.0                                175.0 NaN          1

Since the regions exclude each other, the area inbetween them is not assigned to any source region. Data in that overlapping area is not used in later data analysis.

We now use the `rank_roi` tool to assign the area to the source with the most counts based on the input image: broad_thresh.img.

$ rank_roi infile=broad_thresh.img roi="ciao_?.src" out="rank_ciao_{}.src" method=max clob+
rank_roi
          infile = Test/sim/sim.img.gz
        roifiles = ciao_?.src
         outfile = rank_ciao_{}.src
          method = max
         clobber = yes
         verbose = 1
            mode = ql

Loading ROI files
2 ROI files parsed
Checking clobber
Checking infile (image v. table)
Computing metric for all ROIs
Determining which ROIs should get overlap area
Writing out new roi files

The stack of roi input files, roifiles, is processed and ranked based on the method parameter; max means maximum counts|flux based on the infile image. The file names for the output files are generated based on the outfile name template. Note: the outfile must include a Python string format token, ie something inside of curly brackets, eg {} or {:04d}.

We can then check the output files and we see that the 1st region

$ dmlist rank_ciao_1.src data,clean
Region Block: Ellipse(3972,4444,43,38,175)&!Ellipse(3945,4501,46,40,128)
#  POS(X,Y)                                 SHAPE              R[2]                                     ROTANG[2]                                COMPONENT
                       3972.0      4444.0 Ellipse                                    43.0        38.0                                175.0 NaN          1
                       3945.0      4501.0 !Ellipse                                   46.0        40.0                                128.0 NaN          1

still has the 2nd region excluded from it. It has a lower rank than the 2nd region. The 2nd region looks like

$ dmlist rank_ciao_2.src data,clean
Region Block: Ellipse(3945,4501,46,40,128)
#  POS(X,Y)                                 SHAPE              R[2]                                     ROTANG[2]                                COMPONENT
                       3945.0      4501.0 Ellipse                                    46.0        40.0                                128.0 NaN          1

Since this region has the highest rank it has claimed the overlapping region area (thus no regions are excluded from it).

Parameters

name	type	ftype	def	min	max	reqd	stacks
infile	file	input				yes	no
roifiles	file	input				yes	yes
outfile	file	output				yes	no
method	string		max			no	no
verbose	integer		1	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input stacks=no)

An image or event list.

The infile is filtered by each region and statistics are gathered to compute the regions' rank.

Parameter=roifiles (file required filetype=input stacks=yes)

The stack of roi region files.

Users can use any standard CIAO stack syntax to provide the list of roi region files: "@file.lis", wildcards (*, ?), etc. All the regions must be supplied ; if they are not then overlaps involving any omitted regions will not be checked.

The regions should have been created using roi's group=exclude parameter setting. Using any of the other methods results in the output files just being copies of the input files.

Parameter=outfile (file required filetype=output stacks=no)

The output file name template.

The outfile template value must contain a Python string formatting token. The token is replaced by the region number when the files are written. Typically the value will be "{}" or "{:04d}".

Parameter=method (string not required default=max stacks=no)

The metric used to determine the regions' ranks.

The overlapping region area is assigned based on the method parameter:

max : the region with the largest flux
min : the region with the least flux
bright : the region with the brightest pixel (maximum, maximum pixel value)
faint : the region with the faintest pixel (minimum, maximum pixel value)
big : the region with the largest area
small : the region with the smallest area

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

Amount of tool chatter level.

Running with verbose=2 or higher will print the metric for each region.

Parameter=clobber (boolean default=no)

Overwrite output files if they already exist?

Changes in the scripts 4.15.2 (April 2023) release

Fix the case when multiple regions have the same value for metric computed by the method parameter. For example, the regions enclose the same brightest pixel, or if the regions have equal area. In this case, the overlap region will be assigned to only one of the regions. The previous behavior could have assigned the overlap area to all the regions or to none of the regions depending on the method parameter.

When provided an event file, make sure that the same parameters are used when binning into an image. Difference in the grid could lead to inconsistencies when computing the metric.

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.