Last modified: January 2024

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

merge_too_small

Context: Tools::Image

Synopsis

Adjust input map file to meet some minimum criteria

Syntax

merge_too_small  infile outfile [method] [imgfile] [binimg] [minvalue]
[join] [verbose] [clobber]

Description

The output maps from various adaptive binning routines may contain small, insignificant groups which were the result of filling in the gaps between neighboring groups. The merge_too_small script reassigns these small regions to the smallest neighbor (by default). The script will identify groups with a small geometric area (ie few pixels), or with low number of counts (requires imgfile be supplied).

The deficient groups are merged in to the smallest neighboring group by default; where smallest is the same metric (smallest area or fewest counts). The join parameter can be used to change the logic and assign deficient groups to the largest neighboring group.

The output is a new map file with the deficient regions pixel values replaced with the largest or smallest neighbor.

With method=area, the minvalue is the minimum number of image (ie logical) pixels a group can contain. With method=counts, the minvalue is the minimum sum of pixel values obtained from imgfile. The imgfile typically will be a counts image; however, it could also be exposure corrected and|or background subtracted.

This script does not preserve any morphology imposed by the tool which created the input map. For example, if the input map was created by following some contours, the output map will not adhere to that constraint. Similarly, if the input has some geometric shape (circle, square, hexagon,etc) the output will not preserve that geometry.


Examples

Example 1

% merge_too_small scales.map scales_min10px.map method=area minvalue=10

Takes the input map file, scales.map, and identifies all the groups with 10 or fewer image pixels (ie logical pixels). Those groups are merged into their neighboring groups with the largest area. The updated map file is written to the outfile, scales_min10px.map.

Example 2

% merge_too_small scales_min10px.map scales_min10px+100cts.map
method=counts minvalue=100 imgfile=img.fits

Taking the output from the previous example, we now identify any groups which contain fewer than 100 counts and merge them into their neighbor with the most counts. The imgfile, img.fits, must be supplied so we can obtain the counts.

Example 3

% merge_too_small scales_min10px.map scales_min10px+100cts_min.map
join=max method=counts minvalue=100 imgfile=img.fits

This is the same as the previous example with the addition of setting the parameter join=max. With this change, deficient groups are assigned to the largest adjacent neighbor rather than the largest.


Parameters

name type ftype def min max reqd
infile file input       yes
outfile file output       yes
method string   counts      
imgfile file input        
binimg file output        
minvalue integer     0    
join string   min      
verbose integer   1 0 5  
clobber boolean   no      

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input map file.

The input map file should have integer pixel values. The pixel values indicate which pixels are grouped together by some algorithm. A pixel value of 0 are pixels which are ungrouped (ie outside the image subspace).

The script will identify groups where the area is too small, or the number of counts is too few and will merge those groups into their neighbor with the largest area or counts.

Parameter=outfile (file required filetype=output)

Output map file

The outfile is a map file containing integer pixel values. The pixel values indicate which pixels are grouped together by the algorithm. A pixel value of 0 are pixels which are ungrouped (ie outside the image subspace).

Parameter=method (string default=counts)

Metric used for minimum calculation: counts or area

With method=area, the minvalue is the minimum number of image (ie logical) pixels a group can contain. With method=counts, the minvalue is the minimum sum of pixel values obtained from imgfile. The imgfile typically will be a counts image; however, it could also be exposure corrected and|or background subtracted.

Parameter=imgfile (file filetype=input)

Optional, input counts image

The imgfile is used if method=counts to determine the sum of the pixel values (counts) in each group. The imgfile is also used if binimg is set in which case the script will apply the new map values, outfile, to the imgfile and produce a binned image.

Parameter=binimg (file filetype=output)

Optional, output binned image

If the binimg file is specified, the script will use the input image and the output map file to create a binned version of the input image.

Parameter=minvalue (integer min=0)

The lower limit on counts or area

With method=area, the minvalue is the minimum number of image (ie logical) pixels a group can contain. With method=counts, the minvalue is the minimum sum of pixel values obtained from imgfile.

Parameter=join (string default=min)

Logic to use when joining neighboring groups

With join=min (default), deficient groups are assigned to the smallest adjacent neighbor (using the same counts or area metric determined by the method parameter). With join=max, deficient groups are assigned to the largest adjacent neighbor.

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

Amount of chatter from the tool.

Parameter=clobber (boolean default=no)

Delete outfile if it already exists?


Changes in scripts 4.16.1 (Q1 2024) release

Zero counts

When using method=counts, the tool would skip regions with 0 counts. This has been fixed.

join parameter

Added the join parameter to control the logic to use when assigning small regions to neighbors: largest neighbor (max) or smallest neighbor (min, default). The help file for the initial release of the tool indicated that it was using the join=max logic; however, the actual code was using the equivalent of the join=min logic.

Neighbor Rules

The tool now only considers pixels that share an edge to be neighbors, instead of treating diagonally touching pixel to be neighbors.

Performance

Some internal changes to improve runtime speed.

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.

See Also

dm
dmfiltering
tools::core
dmappend
tools::image
centroid_map, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmradar, dmregrid, dmregrid2, energy_hue_map, evalpos, hexgrid, map2reg, mkregmap, pathfinder, vtbin
tools::region
dmcontour, dmellipse, dmimghull, dmimglasso
tools::response
mean_energy_map, pileup_map
tools::statistics
dmstat, imgmoment, statmap