Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/statmap.html
AHELP for CIAO 4.15

statmap


Synopsis

Compute simple statistics for events in each map region.

Syntax

statmap  infile mapfile outfile [column] [statistic] [xcolumn]
[ycolumn] [verbose] [clobber]

Description

`statmap' is used to compute simple statistics (mean, median, sum, min, max, or count) of a column in an input event file based on how they have been spatially grouped via the input map file. For example, users can use this script to compute the mean energy of the events that have been adaptively binned with dmnautilus, dmradar, or another adaptive binning tool.

Caution: Interpreting Results

The output from statmap should not be interpreted directly as a "temperature map". While some authors (David et al. 2009, ApJ, 705, 624) have developed techniques to "calibrate" the kind of mean energy maps this tool can produce, the intent of this tool is to provide a quick analysis to help guide users to perform more detailed analysis (ie spectral fitting). Users can use this tool to identify regions where the energy changes (eg "cool cores") but the actual temperatures should be derived more robustly.


Examples

Example 1

unix% statmap acis_evt.fits adaptive_bin.map median_energy.map

With the defaults, the tool will compute the median energy of the events from the input event file, acis_evt.fits, for each region in the input mapfile, adaptive_bin.map. The output image, median_energy.map, will be an image whose pixels values are the median energy.

Example 2

unix% dmnautilus "acis_evt.fits[ccd_id=7,energy=500:7000][bin sky=4]"
abin.img snr=10 method=4 outmaskfile=abin.map
unix% statmap "acis_evt.fits[ccd_id=7,energy=500:7000]" abin.map
median_energy.map stat=median column=energy

The first command in this example uses the dmnautilus tool to compute an adaptively binned image where each bin contains at least 100 counts (implied by snr=10). The 2nd command then runs statmap to compute the mean energy in each bin by using abin.map file produced by dmnautilus.

Example 3

unix% dmnautilus "acis_evt.fits[ccd_id=7,energy=500:7000][bin sky=4]"
abin.img snr=10 method=4 outmaskfile=abin.map
unix% statmap "acis_evt.fits[ccd_id=7,energy=500:7000]" abin.map
number_events.map stat=count column=energy

The same as the previous example, but now using statistic=count. The output image will now show the number of events (count) in each of the bins.


Parameters

name type ftype def min max reqd
infile file input       yes
mapfile file input       yes
outfile file output       yes
column string   energy      
statistic string   median      
xcolumn string   x      
ycolumn string   y      
verbose integer   1 0 5  
clobber boolean   no      

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

The input event file.

The input event file (table) must have columns: X, Y, and the "column" parameter.

Parameter=mapfile (file required filetype=input)

The input map file.

The input map file must be a 2D image whose integer pixel values are used to identify which pixels are to be grouped together when computing the requested statistic.

This could for example be the "outmaskfile" created by dmnautilus or dmradar.

Only pixel values greater than 0 (>0) are considered to be grouped. Pixels less than or equal to zero (<=0) are not considered to be grouped and will be ignored.

Parameter=outfile (file required filetype=output)

The output statistics map image file.

The output image will be the same size as the input "mapfile". The pixels values will be the "statistic" computed for the specified "column" from the pixels in the "infile". The same statistic value is used for all the pixels with the same ID (ie mapfile value). So for example with the defaults, the output file will have the median energy of the events in each region, producing a pseudo temperature map.

Parameter=column (string default=energy)

Which column to compute statistics about

The name of the column in the "infile" event table about which to compute the requested statistic.

Parameter=statistic (string default=median)

The choice of statistic to compute

The choice of statistic options is:

Parameter=xcolumn (string default=x)

The column name to use for the X-coordinate

Parameter=ycolumn (string default=y)

The column name to use for the Y-coordinate

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

dm
dmfiltering
tools
dmappend, dmcontour, dmellipse, dmfilth, dmimg2jpg, dmimgadapt, dmimgblob, dmimgcalc, dmimgdist, dmimgfilt, dmimghist, dmimghull, dmimglasso, dmimgpick, dmimgpm, dmimgproject, dmimgreproject, dmimgthresh, dmmaskbin, dmmaskfill, dmnautilus, dmregrid, dmregrid2, dmstat, evalpos, imgmoment, mean_energy_map, pileup_map