Synopsis
Create map from stack of input regions.
Syntax
mkregmap infile regions outfile [binimg] [coord] [verbose] [clobber]
Description
The tool take an image and a stack of region descriptions. The regions can be multiple files, multiple rows in a single file, or a list individual shapes. The output image pixel values indicate which region each pixel is inside. If a pixel is inside more than one region, the last region number is used.
Examples
Example 1
% mkregmap img.fits "region1.fits,region2.fits,region3.fits" reg.map
Three region files are supplied as input using commas (",") to separate them. The output map file will contain values 1, 2, or 3 if the pixels in the input image, img.fits, are inside any of those regions. The outfile, reg.map, stores this information, and will have pixels equal to zero (0) if they are not included in any of the regions, or if the input pixels were NaN. We could also use the "region(filename)" syntax
"region(region1.fits),region(region2.fits),region(region3.fits)"
or use the "@stack_filename" syntax
% cat my_region.lis region1.fits region2.fits region3.fits circle(3288,6778,100) % mkregmap region=@my_region.lis
Note: Users should be careful when using the "@" syntax with list files located in different directories. The "@-" syntax may be need to suppress appending the directory name to the stack elements.
Example 2
% mkregmap img.fits "pgrid(4096,4096,0:1000:100,0:360:360)" pgrid.map
Here we use the polar-grid, "pgrid", stack syntax to create a set of 10 annuli, all centered at (4096,4096), with radii that go from 0 to 1000 pixels in 100 pixel steps.
Example 3
% dmellipse img.fits out=ellipse.out fraction="lgrid(0.05:1.0:0.025)" % dmsort ellipse.out ellipse_sort.fits key=-component % mkregmap img.fits "ellipse_sort.fits[#row=igrid(1:100:1)]" ellipse.map
Here we start by using dmellipse to generate a set of ellipses which enclose from 5% to 100% of the flux in the input image. We then reverse sort these based on the COMPONENT column value (ie in descending order). These are then fed into mkregmap to create an elliptical-annulus map. We sorted the values since the inner most region (5%) is typically fully enclosed by the larger fractions and since mkregmap uses the last region when regions overlap, we need it to be at the end of the stack.
Example 4
% mkregmap xmm.fits @region.lis xmm.map coord="pos"
Not all images have a "sky" coordinate system that the scripts can understand. Some images likes those from XMM data products contain a "pos" coordinate system.
Users can use dmlist with the "cols" option to see the coordinate axis name needed to use the script.
Parameters
name | type | ftype | def | min | max | reqd | stacks |
---|---|---|---|---|---|---|---|
infile | file | input | yes | ||||
regions | string | yes | yes | ||||
outfile | file | output | yes | ||||
binimg | file | output | |||||
coord | string | sky | |||||
verbose | integer | 1 | 0 | 5 | |||
clobber | boolean | no |
Detailed Parameter Descriptions
Parameter=infile (file required filetype=input)
Input image.
Null and NaN pixels, as well as those pixels outside the image subspace will not be grouped. Otherwise the pixel values are ignored, just the size and dimensions of the image are used.
Parameter=regions (string required stacks=yes)
Stack of regions
Each region in the stack is assigned an ID, from 1 to N. The output image is set to the region ID if the pixel is inside the region. If multiple regions overlap, the last region in the stack will be used to set the group ID (highest region ID).
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=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=coord (string default=sky)
Axis name to filter input image
Not all images have a "sky" coordinate system. For example XMM images typically have a "pos" coordinate system. Users can use the dmlist command with the "cols" option to determine the column name to filter on.
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?
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
- concept
- subspace
- dm
- dmfiltering, dmmasks, dmregions
- tools::aspect
- dither_region
- tools::core
- dmappend
- tools::detect
- get_src_region
- tools::gratings
- tg_create_mask
- 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, merge_too_small, pathfinder, vtbin
- tools::region
- bkg_fixed_counts, convert_ds9_region_to_ciao_stack, dmcontour, dmellipse, dmgroupreg, dmimghull, dmimglasso, dmmakereg, psf_contour, rank_roi, regphystocel, roi, splitroi
- tools::response
- mean_energy_map, pileup_map
- tools::statistics
- dmstat, imgmoment, statmap