/ ciao4.17 / ahelp / statmap.html

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

AHELP for CIAO 4.17

statmap

Context: tools::statistics

Synopsis

Compute simple statistics for events in each map region.

Syntax

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

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.

Example 4

unix% eff2evt "acis_evt.fits[energy=500:7000]" fluxed_acis_evt.fits
unix% statmap fluxed_acis_evt.fits abin.map wmedian_energy.map \
stat=wmedian column=energy xcol=x ycol=y wcol=flux

In this example the eff2evt tool is used to compute the flux per event as determined by the energy of the event, the mirrors effective area, and the detector efficiency. The statmap tool is then used to compute a weighted median of the energy column using the flux values as weights. This may be important for very large energy bands where the efficiency of the detectors and/or mirrors changes significantly within the band.

Other weighted options include the weighted average (wmean), weighted max (the energy with the max flux), weighted min (the energy with the min flux), and the weighted sum (sum of energy multiplied by flux).

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
wcolumn	string
clobber	boolean		no
verbose	integer		1	0	5

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:

median : The median value (ie 50% quantile).
mean : The mean or average value (sum(column)/N).
min : The minimum value in the column.
max : The maximum value in the column.
sum : The sum of the values in the column.
counts : The number of value in the column.
wmedian: The weighted median based on the wcolumn weights
wmean: The weighted mean or average values (sum(w*column)/sum(w))
wmin: The column value with the minimum weight
wmax: The column values with the maximum weight
wsum: The sum of the product of column multiplied by weight.

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=wcolumn (string default=)

The column name to use for the weights

This is only used if the statistic is wmedian, wmean, wmin, wmax, or wsum.

Parameter=clobber (boolean default=no)

Delete outfile if it already exists?

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

Amount of chatter from the tool.

Changes in the scripts 4.16.2 (August 2024) release

Added new weighted median, mean, min, max, and sum statistics together with the new wcolumn parameter to specify which column in the input table to use for weights.

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.