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