/ ciao4.17 / ahelp / mkacisrmf.html

Jump to: Description · Example · Parameters · Bugs · See Also

AHELP for CIAO 4.17

mkacisrmf

Synopsis

Generate an RMF for Chandra imaging data

Syntax

mkacisrmf  infile outfile wmap energy channel chantype ccd_id chipx
chipy gain [asolfile] [obsfile] [logfile] [contlvl] [geompar] [thresh]
[clobber] [verbose]

Description

The mkacisrmf tool generates an OGIP-style RMF file appropriate for analysis of Chandra ACIS imaging data. The response matrix file (RMF) encapsulates the mapping between the physical properties of incoming photons (such as their energy) and their detected properties (such as detector pulse heights or PHA) for a given detector. This mapping is stored in the form of a 2-D matrix. Spectral fitting packages like Sherpa, XSPEC, and ISIS use this redistribution function (the matrix), plus an accompanying effective area function (the ARF), to predict the counts per channel produced by a given spectral model for the source.

mkacisrmf should be used in place of mkrmf for all -120 ACIS data taken in (V)FAINT mode that have the time-dependent gain adjustment and CTI correction applied. It may also be used for GRADED mode data on the back-illuminated chips (ACIS-S1 and S3) only. Read the Creating ACIS RMFs why topic for more information.

mkacisrmf calculates the RMF on user-defined grids in energy (units of keV) and channel (units of PHA or PI) using tabulated ACIS response calibration information. The user may choose to create an RMF for a single position on a given ACIS CCD, or, alternatively, an RMF which represents the weighted sum of the response function over a given spatial extraction region. In general, the response of the detector is a function of position on the CCD and such weighted RMFs (WRMFs) may be more appropriate for analysis of extended sources.

To construct weighted RMFs, mkacisrmf uses weighting information contained in a FITS image of the field in CCD detector coordinates. Such an image is called a weights map (WMAP) and can be created from the events data with dmcopy or during the spectral extraction process with dmextract. The WMAP created by the tool sky2tdet may also be used, but its precision will cause mkacisrmf to run very slowly. The RMF doesn't change quickly enough to require the detail of a sky2tdet WMAP; nearly identical results are obtained with a dmextract or dmcopy WMAP.

Users have the option of creating RMFs appropriate for either PHA or PI extracted ACIS spectra. For the case of PI RMFs, the information in the input gain file is used to scale from PHA channels to PI channels dynamically during the RMF computation. If a WMAP or OBSFILE file created in CIAO is specified, mkacisrmf will utilize keyword information in the header to locate the appropriate gain file in the CALDB automatically. If an RMF for a single position is desired, the gain file must be specified explicitly.

Examples of the various options for creating RMFs can be found in the CIAO science threads.

The tool mkacisrmf is an entirely new method for creating ACIS response matrices. Unlike its predecessor mkrmf, this tool separates the RMF calculation process into two components: an "ideal" component which describes the CCD spectral response prior to the effects of charge transfer inefficiency (CTI) degradation, and a spatially varying component which incorporates the changes in the response produced by CTI. Accompanying the new tool is a new CCD analysis reference data (ARD) input file which describes both the ideal CCD response and the spatial variation produced by CTI. This new approach provides a number of improvements in speed and accuracy and will become the default tool for ACIS RMF generation once a full set of ACIS response calibration products is available.

Output format

The output RMF is a standard FITS file and contains two extensions. The MATRIX extension consists of the actual energy to detector channel mapping and is an MxN matrix where M and N correspond to the sizes of the grids selected by the user. The EBOUNDS extension is a set of vectors giving the upper and lower energy bounds for each detector channel and is determined from information in the gain file. The EBOUNDS information is used by packages such as Sherpa, XSPEC, and ISIS for plotting purposes. It is not used directly for fitting. The mkacisrmf output format retains the HEASARC OGIP 92-002 standard for 2-D RMFs, and is fully compatible with Sherpa, XSPEC, and ISIS.

Running mkacisrmf

There are two different ways of running mkacisrmf depending on whether the user wishes to create a weighted RMF or an RMF appropriate for a single position on one of the ACIS CCDs.

Creating an RMF to match an extracted spectrum

In this scenario, the user has extracted a spectrum from a given region using dmextract and wishes to compute a matching RMF. For example, the sequence:

  dmextract \
  "data_evt2.fits[(x,y)=circle(4232, 3289,30)][bin pi=1:1024:1]" \
  src_pi.fits  wmap="det=8"

  mkacisrmf infile=CALDB                \
            outfile=wrmf.fits           \
            energy=0.3:10.0:0.01        \
            channel=1:1024:1            \
            chantype=PI                 \
            wmap=src_pi.fits            \
            gain=CALDB                  \
            asolfile=asol.fits

will extract a spectrum from within the indicated region and create a weighted RMF appropriate for that region. Here, the wmap option in the call to dmextract creates a weight map (see the documentation for dmextract) which mkacisrmf will use to create a counts weighted RMF over the extraction region, applying the fiducial offsets in the aspect solution file to determine the correct chip coordinates. The "infile" parameter is set to "CALDB" and mkacisrmf uses the information in the header of the input wmap file to determine the appropriate Phase 2 response calibration file to use. The energy grid for the RMF is given in keV and in this example ranges from 0.3 to 10.0 keV in 5 eV increments. The channel grid in this case uses PI channels.

Similarly, the gain parameter should be set to "CALDB" as well in order to ensure that an appropriately matched gain file is used. Every Phase 2 response calibration file has corresponding matched gain file in the CALDB.

Setting the "infile" parameter to a value of CALDB, in conjunction with an input wmap file, is the best way to ensure that the most appropriate Phase 2 response calibration file is used for a given dataset. As with any CALDB file, updated files are added to the CALDB to correct problems found with existing files; however, by using the CALDB value for the "infile" parameter, mkacisrmf will automatically select the appropriate file. This method is the recommended way of constructing RMFs with mkacisrmf.

Creating an RMF at a specific location

For this case, it is assumed the user wishes to create an RMF file for a specific location on one of the ACIS CCDs, independent of a given dataset or extraction region. In such a situation, the user has two ways for doing so. One is that user explicitly supply the values to the "infile" and "gain" parameters, since the tool does not have access to the information in a header to determine which file should be used. For example, the sequence:

  mkacisrmf \
  infile="$CALDB/data/chandra/acis/p2_resp/acisD2000-01-29p2_respN0006.fits" \
            outfile=c7_645_10_rmf.fits           \
            wmap=none                            \
            energy=0.3:10.0:0.01                 \
            channel=1:1024:1                     \
            chantype=PI                          \
            ccd_id=7                             \
            chipx=645                            \
            chipy=10                             \
  gain="$CALDB/data/chandra/acis/det_gain/acisD2000-01-29gain_ctiN0006.fits"

creates an RMF at a position of (645, 10) in CHIP coordinates on CCD 7. Again, the user must ensure that the appropriate matching gainfile is used. The energy and channels grids are the same as in the previous example. Note that when specifying the input response and gain files explicitly, the path to these files must be included.

The other way is that user supplies a value to "obsfile" parameter while setting "infile" and "gain" to "CALDB",

  mkacisrmf infile=CALDB                         \
            outfile=obsf.fits                    \
            wmap=none                            \
            energy=0.3:10.0:0.01                 \
            channel=1:1024:1                     \
            chantype=PI                          \
            ccd_id=7                             \
            chipx=645                            \
            chipy=10                             \
            gain=CALDB                           \
            obsfile=obsf_cti.fits

so three header keywords in "obs_cti.fits",

      0030 CTI_CORR             YES                            String       
      0031 CTI_APP              PPPPPNPNPP                     String       
      0032 DATE-OBS             2000-01-29T20:00:00            String

will be extracted. mkacisrmf feeds the 3 queries to CALDB search engine, and a pair of matching ARD and gain files are automatically retrieved and located. An RMF at a position of (645, 10) in CHIP coordinates on CCD 7 will be created.

Example

dmextract \
"data_evt2.fits[(x,y)=circle(4232, 3289,30)][bin pha=1:4096:2]" \
src_pha.fits wmap="[bin detx=4250:4350,dety=4000:4100]"

mkacisrmf infile=CALDB outfile=wrmf.fits energy=0.3:10.0:0.01
channel=1:4096:2 chantype=PHA wmap=src_pha.fits gain=CALDB
asolfile=asol.fits

Creates a weighted RMF using the weights map contained in the input spectrum file. Similar to the example shown above; however, here the spectrum has been binned in PHA channels and the RMF has been computed on a matching PHA grid. Also, the weights map has been generated at full resolution for a small region surrounding the source of interest (you can find the detx,dety range of the source using 'dmstat evt.fits[sky=region(sky.reg)][cols det]').

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
outfile	file	output				yes
wmap	file	input				yes
energy	string	input				yes
channel	string	input				yes
chantype	string	input	PI			yes
ccd_id	integer	input		0	9	yes
chipx	integer	input				yes
chipy	integer	input				yes
gain	file	input	CALDB			yes
asolfile	file	input
obsfile	file	input	)wmap
logfile	file	output
contlvl	integer	input	100
geompar	file	input	geom
thresh	float	input	1e-6	0.0
clobber	boolean	input	no
verbose	integer	input	0	0	5

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input calibration file

Includes full path and file name or a CALDB query (e.g. infile=CALDB ) if a wmap file is being supplied. The valid file contains upto five data extensions: one or two ideal response tables, one or two multi-region scatter block tabulating analytical function parameters, and a response energy "TWEAK" extension. In the Chandra CALDB, these files are found in the $CALDB/data/chandra/acis/p2_resp/ directory.

Parameter=outfile (file required filetype=output)

Output FITS RMF file

Contains a null primary binary table followed by two extensions: response MATRIX and EBOUNDS.

The MATRIX array in each gridded (e.g. energy) row are compressed so any element value below the cutoff value (specified by "thresh" parameter) will be removed from the array and then normalized to one for that row over the effective channels (PHA/PI). The EBOUNDS arrays are interpolated from the gain table (specified by "gain" parameter) over the full resolution of channels and output in the user-specified bin step.

Parameter=wmap (file required filetype=input)

Input FITS WMAP file

The WMAP can either be stored in the WMAP block of a PHA spectrum file created by dmextract or in an image created with dmcopy. If "wmap=none" or "wmap=" (empty parameter), mkacisrmf will generate a single-region RMF output based on the user's 3-parameter filter specification; otherwise, a weighted PI channel type RMF over multi-response regions will be created.

Parameter=energy (string required filetype=input)

Energy grid in keV

The grid is specified by giving the lower bound, upper bound, and binning step, separated by the ":" character. For example, "energy=0.1:10.0:0.01" bins from 0.1 to 10.0 keV in steps of 0.01 keV.

mkacisrmf checks the energy bounds among the user's input grid, response file and gain file and then picks the output grid that fits all of them. Since the current calibration file does not extend below 0.243 keV, it is not possible for mkacisrmf to create an RMF with bounds lower than that energy.

Parameter=channel (string required filetype=input)

Channel grid in pixels

The grid is specified by giving the minimum, maximum channel, and binning step, separated by the ":" character. For example, "channel=1:4096:1" bins from channel 1 to 4096 in steps of 1.

Parameter=chantype (string required filetype=input default=PI)

Channel type

Determines the output RMF grids, energy vs PHA or energy vs PI. Valid values are PHA and PI; these values are case-sensitive.

Parameter=ccd_id (integer required filetype=input min=0 max=9)

The ACIS chip(s) to filter

This is the first of three parameters to be used as event filter when a wmap is not supplied. mkacisrmf looks up scatter for a single tile region to match the specified filter. This parameter is ignored when an effective wmap value is supplied.

Parameter=chipx (integer required filetype=input)

Detector chipx position [pixels]

This is the second of three parameters to be used as event filter when a wmap is not supplied. mkacisrmf looks up scatter for a single tile region to match the specified filter. This parameter is ignored when an effective wmap value is supplied.

Parameter=chipy (integer required filetype=input)

Detector chipx position [pixels]

This is the third of three parameters to be used as event filter when a wmap is not supplied. mkacisrmf looks up scatter for a single tile region to match the specified filter. This parameter is ignored when an effective wmap value is supplied.

Parameter=gain (file required filetype=input default=CALDB)

Gain file in FITS format

The gain file to be used in creating the RMF. The energy bounds of the spectral response create the EBOUNDS block of the resulting RMF. Also, the supplied gain information is necessary to convert PHA RMF to PI RMF when "chantype=pi" is supplied.

If an RMF for a single position is desired, the gain file (including path) must be specified explicitly.

If a WMAP file specified, the gain parameter may be set to "CALDB" (the default) and mkacisrmf will utilize keyword information in the WMAP header to locate the appropriate gain file in the CALDB automatically. Note that this method selects the newest gain appropriate for the date, NOT the gain file used to process the data; this could lead to mismatched calibration files.

Parameter=asolfile (file filetype=input default=)

Name of FITS file containing the pointing of the telescope in the sky, or the aspect solution.

If the aspect solution file(s) for the observation are provided, the average dither values are used to derive the correct instrument coordinates for an input WMAP in DETX,DETY coordinates.

Parameter=obsfile (file filetype=input default=)wmap)

Name of FITS file containing CTI info

The observation file serves only for CALDB lookup. Its value is default to WMAP if a WMAP file specified. If "infile" and/or "gain" taking value of "CALDB", the obsfile header must contain keywords, "CTI_CORR", "CTI_APP", and observation date, so appropriate ARD and gain information can be automatically retrieved. Note that files which have not been reprocessed since early in the mission will not have the necessary keywords.

Parameter=logfile (file filetype=output)

Log file.

Records all STDERR messages. It also logs any STDOUT for verbose levels of 1 and higher.

Parameter=contlvl (integer filetype=input default=100)

Number of contour levels relative to local function peak.

This number is used to interpolate scatter function along the leveled contours.

Parameter=geompar (file filetype=input default=geom)

Pixlib Geometry parameter file

The pixlib file is used to access the information necessary to map detector pixels to a response region.

Parameter=thresh (float filetype=input default=1e-6 min=0.0 units=)

Minimum value included in the output matrix

All MATRIX elements below this threshold value are excluded from the output file. This is used to reduce the size of the output file. It is suggested that the parameter value is left at its default value.

Parameter=clobber (boolean filetype=input default=no)

Clobber

Overwrites existing files of the same output file name if "yes"

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

Verbosity level

This option allows the user to request a varying level of diagnostic output. Levels range from 0 to 5 with 0 representing no information and 5 representing the most. Verbosity greater than 3 contains information for debugging; most users will not need to set this parameter higher than 3. All messages are written to the log file.

Bugs

Non-standard channel grids

The mkacisrmf tool does not work correctly with arbitrary, non-standard channel grids.

For chantype=PI the channel parameter should always be channel=1:1024:1, for chantype=PHA the channel parameter should always be channel=1:4096:1.

Issue with the WMAP when the source is at a chip edge

If the observation has large dy & dz offsets in the aspect solution file and they are quite variable during the observation, the tool will fail with a CALDB error. The large (and varying) offsets cause the mapping from DET to CHIP coordinates to fail and the tool cannot determine which response calibration file to use in creating the RMF.

Caveats

ERROR: Max egridspec energy=10 above max FEF energy=9.886

mkwarf is required to compute and write a "weightfile" output file which contains FEF regions for use by mkrmf. If the energy range in the input RMF is greater than that in the FEF files, you get an error like:

ERROR: Max egridspec energy=10 above max FEF energy=9.886

Although the comparison to the FEF files is unnecessary in this case, there is currently no way to turn it off (e.g. set the weightfile to "NONE").

Workaround:

In order to avoid the error, it is necessary to define an energy range for mkacisrmf that falls within the boundaries of the FEF files, i.e. approximately 0.28 - 9.8 keV.

ERROR: No non-zero pixels map to valid chip coordinates in the supplied wmap='src.pi[WMAP]' file

The mkacisrmf tool may be used for -110 ACIS data taken on the back-illuminated chips (ACIS-S1 and S3) only.

If the input file contains -110 C data and has the CTI-correction applied but the source is actually on a front-illuminated chip, mkacisrmf fails with an error:

unix% # mkacisrmf (CIAO): ERROR: No non-zero pixels map to valid
chip coordinates in the supplied wmap='src.pi[WMAP]' file

mkacisrmf infile=CALDB outfile=src.wrmf energy="0.3:11.0:0.01"
channel="1:1024:1" chantype=PI wmap=src.pi"[WMAP]" gain=CALDB
clobber=yes verbose=2 mode=h  failed.

Error: Failed to create RMF for evt2.fits[sky=region(src.reg)]

In this case, the user should be using mkrmf to create the RMF file. Refer to the mkacisrmf why topic for more information.

WARNING: Did not find 'GRATTYPE' in supplied header, skipping it

The GRATTYPE is needed for some calibration files in order to distinguish between MEG and HEG. This warning is printed when the keyword is missing from the input file.

However, GRATTYPE is not required by mkacisrmf to select the P2_RESP file, so the warning may be safely ignored.

ERROR: couldn't query SC_MATRIX for CALDB

This error usually indicates that the input dataset was taken at an unsupported focal plane temperature:

unix% dmkeypar source.evt FP_TEMP echo+
0134 FP_TEMP 163.952041630 [K] Real8 Focal Plane Temperature

In this case, the observation was done at -109C. The mkrmf tool should be used to create the RMF file. Refer to the mkacisrmf why topic for more information.