/ ciao4.17 / ahelp / centroid_map.html

Jump to: Description · Examples · Parameters · Changes in scripts 4.16.1 (Q1 2024) release · About Contributed Software · Bugs · See Also

AHELP for CIAO 4.17

centroid_map

Context: Tools::Image

Synopsis

Adaptively bin an image using centroid map algorithm

Syntax

centroid_map  infile outfile [numiter] [sitefile] [scale] [verbose]
[clobber]

Description

The centroid_map tool implements an iterative adaptive binning routine. First, the tool determines the location of the local maxima in the input image. The location of these maxima are called 'sites'. It then performs a Voronoi Tessellation to determine the convex hull polygons around each initial site. This is done using the vtbin tool. Next it computes the centroid of the pixel values enclosed in each polygon. Theses centroids are then used as the sites for the next iteration. The tessellation and centroid process is repeated the user-specified number of iterations.

It can be shown that this algorithm will eventually converge (ie the sites do not change between iterations). However, it may converge slowly where most of the sites remain fixed and only a few sites take many iterations to converge. This is why the number of iterations is left as a user parameter. Typical values will be in the 30-150 range.

Users can also supply their own initial site file (rather than use the location of the local maxima). This allows the user to control the initial location of the site and to control the total number of site locations. The number of sites is fixed; neighboring sites cannot 'merge' together.

The input image should be smoothed. Since the tool determines the location of local maxima in a 5x5 pixel neighborhood, the input should be smoothed at least on that scale.

The output from the centroid_map tool is the map file: an image whose pixel values indicate which pixels are grouped together. Users can use the dmmaskbin tool to create a binned imaged.

Examples

Example 1

% aconvolve img.fits sm_img.fits "lib:gaus(2,5,1,3,3)"
% centroid_map sm_img.fits sm_img.map numiter=30
% dmmaskbin sm_img.fits sm_img.map sm_img.img

First the input image is smoothed with a 3-pixel sigma Gaussian. Then we compute the centroid_map using this smoothed image, using 30 iterations.

The dmmaskbin tool is then used to apply the map to the input image to create the rebinned image: sm_img.img.

Example 2

% dmimgadapt img.fits smoothed.fits function=cone counts=50 min=1
max=20 num=20 radscale=linear
% dmimgfilt smoothed.fits local_max function=peak mask="box(0,0,7,7)"
% dmimgblob local_max sites.fits threshold=0.5 srconly=yes
% centroid_map img.fits img.map numiter=50 sitefile=sites.fits

In this example we start by adaptively smoothing the input image. We then locate the local maximum in a larger 7x7 pixel region, and then use dmimgblob to label local max with a unique value to create the sites.fits files.

The sites.fits file is then used to seed the centroid_map algorithm.

Example 3

% python -c 'import sherpa.astro.ui as
ui;ui.load_data("img.fits");ui.set_model("const2d.flat");flat.c0=0.005;u
i.fake();ui.save_image("fake.img",ascii=False,clobber=True)'
% dmimgthresh fake.img fake_thresh.img exp=smimg.fits cut=0.5 value=0
% dmimgblob fake_thresh.img sites.fits thresh=1 srconly=yes
% centroid_map img.fits random.map numiter=30 site=sites.fits
% dmmaskbin img.fits random.map random.img

In this example we want to use a random starting location for the sites. To do this, we use the sherpa fake() command with a flat, 2D constant model with a Poisson rate of 0.005 counts per pixel. We then use the dmimgthresh command to remove sites that are off the detector (in parts of the smoothed image which are zero). Then we use dmimgblob as before to assign a unique label to each site.

The random sites.fits file is then used to initialize the centroid_map algorithm.

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
outfile	file	output				yes
numiter	integer		1	1
sitefile	file	input
scale	string		linear
verbose	integer		1	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input image.

If the sitefile parameter is not specified, then this image should be smoothed so that the algorithm locate statistically significant local maxima (ie not just single isolated events). If the sites file is supplied then this image does not need to be smoothed.

If the input image contains a large number of pixels outside the detector's field-of-view, users should filter the image first to encode the boundary in the file's data-subspace

% dmcopy "img.fits[sky=region(fov.fits)]" img.dss.fits

The centroid_map script will use the information in the file's subspace; making it run faster by avoiding processing the off-detector pixels.

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).

Users can use the dmmaskbin tool to apply this map file to a counts image to obtain an adaptively binned counts image.

Parameter=numiter (integer default=1 min=1)

Number of iterations

The centroid_map will eventually converge to a state where the sites no longer move. However, it can converge very slowly, where only a few sites at the end take a large number of iterations to become fixed. Rather than try to guess when the algorithm has converged "enough", the script uses the numiter parameter to control the number of iterations. Typical values will be on the order of 30 to 150 iterations.

Parameter=sitefile (file filetype=input)

Optional input site file

If not specified, the centroid_map begins by determining the intial site locations by finding all the local maxima in 5x5 regions. This fixes the number of sites, and thus the number of bins in the final output.

Instead, users can supply their own sitefile, based on whatever criteria they wish. This allows the user to control the number of sites and thus the number of bin in the final output.

Parameter=scale (string default=linear)

Scaling applied to pixel values when computing centroid

In images with a large dynamic range of pixel values, very bright pixels can lead to very small groups. By applying a scaling function to the pixel values before computing the centroid it can help the algorithm produce groups with more uniform areas.

The following scaling functions are available

linear
sqrt
squared
asinh

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

Fix problem when input image contains NaNs; those pixel values are now ignored when computing the centroid.

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.