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.
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, merge_too_small, mkregmap, pathfinder, vtbin
- tools::region
- dmcontour, dmellipse, dmimghull, dmimglasso
- tools::response
- mean_energy_map, pileup_map
- tools::statistics
- dmstat, imgmoment