/ ciao4.15 / ahelp / mean_energy_map.html

Jump to: Description · Examples · Parameters · Deprecation of 'pbkfile' parameter · What Can You Do With it? · Changes in CIAO 4.15 · Changes in CIAO 4.15 · Bugs · See Also

AHELP for CIAO 4.15

mean_energy_map

Context: Tools::Response

Synopsis

Creates an image whose pixels are the mean energy of the events

Syntax

mean_energy_map  infile outfile binsize [pbkfile] [tmpdir] [verbose]
[clobber]

Description

`mean_energy_map' takes an input ACIS event file and computes an output image whose pixels are the exposure-corrected mean energy of the events. This is not a temperature map, which traditionally would be constructed by fitting a thermal model to the event pulse height distribution. However, some authors (David et al. 2009, ApJ, 705, 624) have shown how to convert this kind of mean energy map to a temperature map.

mean_energy_map takes the input event file and runs the eff2evt tool to compute the flux for each event where FLUX = ENERGY * Efficiency. dmtcalc is used to separate out the the efficiency (i.e. weight) term. Finally, dmimgcalc is used to create two images: sum(flux) and sum(weight); dividing the two gives the exposure-weighted mean energy of the events in each pixel.

Examples

Example 1

mean_energy_map infile=evt.fits outfile=me_map.fits bin=8

Create the mean energy map from the input event file. Since no energy filter has been applied, all energies will be used. This may signficantly bias the results since high-energy background events will dominate the output.

Example 2

mean_energy_map infile="evt.fits[energy=500:1200]" outfile=me_map.fits
bin=8

Repeating the previous example, but applying an energy filter so that only events in the 500 to 1200 eV range are used. Without any spatial filtering, the entire 8k x 8k ACIS image space is used.

Example 3

mean_energy_map infile="evt.fits[energy=500:1200,sky=region(ds9.reg)]"
outfile=me_map.fits bin=8

A region filter is applied to the input file so that the output image will be just large enough to enclose the specified region.

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
outfile	file	output				yes
binsize	float					yes
pbkfile	string	input				no
tmpdir	file	output				no
verbose	integer		0	0	5
clobber	boolean		no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input ACIS event file

The event file should include an energy filter to remove any high-energy background events. Otherwise, the results may signficantly biased by the background energies.

HRC data does not contain energy information and therefore cannot be used as input to mean_energy_map.

Parameter=outfile (file required filetype=output)

The output image

The output image is in units of eV and represents the exposure-corrected mean energy of the events in each pixel.

Parameter=binsize (float required)

Output image blocking factor

The blocking factor should be chosen such that you get a suitable number of events in each pixel of interest to make the mean be meaningful. Computing the mean of a single event is very noisy. Picking this number will depend on the surface brightness of the source, length of observation, energy distribution, etc.

Parameter=pbkfile (string not required filetype=input)

Deprecated. See below.

Parameter=tmpdir (file not required filetype=output)

Directory name for temporary files

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

The tool chatter level

Parameter=clobber (boolean default=no)

Clobber outfile

Remove outfile if it already exists?

Deprecation of 'pbkfile' parameter

In CIAO 4.6, the ACIS parameter block file is no longer a required input to this tool. Therefore the 'pbkfile' parameter has been deprecated. The parameter has been retained for now but it is non functional.

This change is made possible by a series of header keyword updates that were made in Chandra standard data processing and are replicated in the chandra_repro script. Four new keywords: SUM_2X2, FEP_CCD, ORC_MODE, and OCLKPAIR have been added to the standard ACIS event file, that, in addition to existing keywords, provide the tool the information needed for the ACIS Dead Area calibration.

These keywords are required to use this tool in CIAO 4.6. Data from the archive with ASCDSVER newer than DS8.4.2 will already have these keywords. This will be the default for all but a few early observations. Users with data that was created prior to ASCDSVER=8.4.2 will need to follow one of these paths to use CIAO 4.6.

Retrieve most recent data from Chandra archive. All but a few datasets in the Chandra archive have been reprocessed to include these keywords (the earliest observations). The last bulk reprocessing included several updates including corrections for aspect "drift" within an observation as well as updated timing information. A summary of the updates can be found here: https://cxc.harvard.edu/cda/repro4.html
Reprocess the data through chandra_repro. This will update the headers with the new keywords and ensure that the other calibrations are consistent with the latest CALDB.
Just update the headers using the r4_header_update script. This will just add new keywords to the event file without any other calibration updates.

What Can You Do With it?

The output mean energy map may look noisy, especially if a small binsize was used. You can smooth the map with the aconvolve tool. (The csmooth tool cannot be used, since it requires the pixel values to be integer counts.)

    unix% aconvolve me_map.fits sm_me_map.fits "lib:tophat(2,1,3,3)"

It is also possible to adaptively smooth the mean energy map by first smoothing the counts image, and then using the scales/radii to smooth the mean energy map.

    unix% dmimgadapt evt.fits"[energy=200:3000][bin sky=8]" \
    outfile=smimg.fits counts=100 radfile=radii.fits \
    function=tophat min=0.5 max=30 num=60 radscal=linear clob+

    unix% dmimgadapt me_map.fits adaptsm_me_map.fits \
    inrad=radii.fits function=tophat mode=h clob+

Apply an adaptive binning scheme to the mean energy map to get mean values with an approximately fixed number of events:

    unix% dmnautilus evt.fits"[energy=200:3000][bin sky=8]" \
    outfile=abin.fits snr=10 outmask=msk.fits

    unix% dmmaskbin infile=me_map.fits mask=msk.fits out=abin_me_map.fits

If a conversion from energy to temperature can be written in a simple functional form, then dmimgcalc can be used to perform the conversion.

The example conversion is specific to the data set presented in David et al.

    unix% dmimgcalc sm_me_map.fits none temperature_map.fits \
    op="imgout=(((img1/1000.0)*5.88)-4.61)"

Changes in CIAO 4.15

The header of the new file (the outfile parameter) will now contain the parameter settings for this tool. It can be retrieved with the dmhistory tool or the get_history_records method of the pycrates python library.

The script now writes proper history records

Bugs

There are no known bugs for this tool.