Last modified: December 2022

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/mktgresp.html
AHELP for CIAO 4.16

mktgresp

Context: Tools::Response

Synopsis

Create ARF and RMF files for each spectral order and grating arm in a TypeII PHA file

Syntax

mktgresp  infile evtfile outroot [orders] [wvgrid_arf] [wvgrid_chan]
[asolfile] [bpixfile] [mskfile] [dtffile] [pbkfile] [dafile] [osipfile]
[parallel] [nproc] [verbose] [clobber]

Description

The 'mktgresp' tool will create the ARF and RMF for each spectral order and grating arm in a Type II PHA file. It runs the mkgrmf tool and the fullgarf script with the appropriate inputs using the energy and channel grids.

For ACIS data, the default PHA files will have 12 spectra for HETG: +/- 3 orders for each MEG and HEG, and 6 for LETG: +/- 3 orders. Since HRC lacks energy resolution, the spectra cannot be order separated so there are only 2 spectra: +/- 1 which represents the contribution from all orders.

The tool will automatically try to locate the auxiliary files needed to make the response products: aspect solution, bad-pixel file, mask, dead time factors (HRC only), and parameter block (ACIS only). If any of these cannot be found, it will produce an error and users will need to set the file name via the parameter file.


Examples

Example 1

unix% mktgresp acis_repro_pha2.fits acis_repro_evt2.fits acis_repro

The ARF and RMF for each spectral order and grating arm in the input PHA file is created using the default energy and channel grids.

unix% /bin/ls acis_repro*.arf acis_repro*.rmf
acis_repro_heg_m1.arf  acis_repro_heg_p2.arf  acis_repro_meg_m3.arf
acis_repro_heg_m1.rmf  acis_repro_heg_p2.rmf  acis_repro_meg_m3.rmf
acis_repro_heg_m2.arf  acis_repro_heg_p3.arf  acis_repro_meg_p1.arf
acis_repro_heg_m2.rmf  acis_repro_heg_p3.rmf  acis_repro_meg_p1.rmf
acis_repro_heg_m3.arf  acis_repro_meg_m1.arf  acis_repro_meg_p2.arf
acis_repro_heg_m3.rmf  acis_repro_meg_m1.rmf  acis_repro_meg_p2.rmf
acis_repro_heg_p1.arf  acis_repro_meg_m2.arf  acis_repro_meg_p3.arf
acis_repro_heg_p1.rmf  acis_repro_meg_m2.rmf  acis_repro_meg_p3.rmf

Example 2

unix% mktgresp hrc_repro_pha2.fits hrc_repro_evt2.fits hrc_repro
orders=-3,-2,-1,1,2,3

Since HRC does not have sufficient energy resolution to sort orders, the grating PHA file calls the spectra the +1, and -1 orders, but they are actually sum of all spectral orders. For proper analysis, users should include the higher order ARFs and RMFs in their analysis. The "orders" parameter can be set to the list of orders required (typically up to 8th to cover the array). (Note: both positive and negative orders must be specified.)

unix% /bin/ls hrc_repro*.arf hrc_repro*.rmf
hrc_repro_leg_m1.arf  
hrc_repro_leg_m1.rmf  
hrc_repro_leg_m2.arf  
hrc_repro_leg_m2.rmf  
hrc_repro_leg_m3.arf  
hrc_repro_leg_m3.rmf  
hrc_repro_leg_p1.arf  
hrc_repro_leg_p1.rmf  
hrc_repro_leg_p2.arf
hrc_repro_leg_p2.rmf
hrc_repro_leg_p3.arf
hrc_repro_leg_p3.rmf

Parameters

name type def min max units reqd stacks
infile file         yes  
evtfile file         yes  
outroot file         yes  
orders string INDEF       no  
wvgrid_arf string compute     Angstrom no  
wvgrid_chan string compute     Angstrom no  
asolfile file         no yes
bpixfile file         no  
mskfile file         no  
dtffile file         no  
pbkfile file         no  
dafile file CALDB       no  
osipfile file CALDB       no  
parallel boolean yes       no  
nproc integer INDEF 1     no  
verbose integer 1 0 5      
clobber boolean no          

Detailed Parameter Descriptions

Parameter=infile (file required)

Input type II pha file

The input type II PHA file produced by either tgextract or tgextract2.

Parameter=evtfile (file required)

Input event file

The input event file with the extraction region attached. This file is also used to locate the auxiliary files with the information stored in the header.

Parameter=outroot (file required)

Output path and root file name for the products

The output file name will be

${root}_${arm}_${pm}${order}.${type}

where ${root} is this parameter. ${arm} is the grating arm: 'leg', 'meg', or 'heg'. ${pm} is 'p' for positive/plus orders and 'm' for minus/negative orders. ${order} is the integer order number: for ACIS the default PHA file will have orders '1', '2', and '3'. For HRC, only '1'. The ${type} identifies the file as either 'arf' or 'rmf'.

Parameter=orders (string not required default=INDEF)

The list of orders to create grating responses.

By default, orders="INDEF", mktgresp will create response file for each order (tg_m) value in the infile spectrum. However, for HRC/LETG observations, users may want to create higher order responses and/or ACIS users may want to only create first order responses (especially for faint sources). If this parameter is set, the orders listed will be created for each grating arm (tg_part) and source in the infile.

Parameter=wvgrid_arf (string not required default=compute units=Angstrom)

Wavelength grid of rmf and arf

Wavelength grid for the arf specification string. This string may specify compute, a file, or an explicit energy grid. For example, to use a grid for the MEG that ranges from 1 to 41.96 angstroms with 8192 channels set. The units for this parameter is angstroms.


  wvgrid_arf="1.0:41.96:#8192"

This is the same grid that you would get with


  wvgrid_arf=compute

The default grids for the three grating types are

Grating type wvgrid_arf
MEG 1.0:41.96:#8192
HEG 1.0:21.48:#8192
LEG 1.0:205.8:#16384

Parameter=wvgrid_chan (string not required default=compute units=Angstrom)

Enter channel-side wavelength grid [angstroms]

Specification string for the channel side wavelength grid. This string may specify compute, a file, or an explicit energy grid. In general this is set to be the same as the arf grid. However, there is no compelling reason that the fitting engine needs the ARF and the RMF on the same grid so this has been left as a user adjustable parameter. The units for this parameter is angstroms.

Parameter=asolfile (file not required stacks=yes)

Names of aspect solution file(s).

If blank, the script will use the information in the header of the event file to try to locate the correct file. If it cannot then the user must set the file name explicitly.

Parameter=bpixfile (file not required)

Name of bad pixel file.

If blank, the script will use the information in the header of the event file to try to locate the correct file. If it cannot then the user must set the file name explicitly.

Parameter=mskfile (file not required)

Names of instrument mask file.

If blank, the script will use the information in the header of the event file to try to locate the correct file. If it cannot then the user must set the file name explicitly.

Parameter=dtffile (file not required)

HRC Only. Name of dead time factors, dtf, file.

If blank, the script will use the information in the header of the event file to try to locate the correct file. If it cannot then the user must set the file name explicitly.

Parameter=pbkfile (file not required)

ACIS only. Names of parameter block, pbk, file.

If blank, the script will use the information in the header of the event file to try to locate the correct file. If it cannot then the user must set the file name explicitly.

Parameter=dafile (file not required default=CALDB)

ACIS only. Name of the dead area calibration file.

The default, CALDB, will retrieve the correct file from the calibration database. If blank, then the dead area calibration will be omitted from the ARF.

Parameter=osipfile (file not required default=CALDB)

Order sorting calibration file

The order sorting calibration file contains information needed to construct the ARF. The default, CALDB, will retrieve the correct file from the calibration database.

Parameter=parallel (boolean not required default=yes)

Run code in parallel using multiple processors?

If multiple processors are available, then this parameter controls whether the tool should run various underlying tools in parallel.

If parallel=yes and verbose>0 users will see that arm+orders will be run in a random order.

Parameter=nproc (integer not required default=INDEF min=1)

Number of processors to use

If parallel=yes, then this controls the number of processes to run at once. The default, INDEF, will use all available processors. The value cannot be larger than the number of processors.

If parallel=yes and verbose>0 users will see that arms+orders will be run in a random order.

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

Amount of information printed to the terminal

Parameter=clobber (boolean default=no)

Should existing files be removed?


Changes in the scripts 4.15.0 (December 2022) release

Removed work-around for HRC-I + HETG response matrix. Previously needed to set detector to ACIS to create a diagonal matrix, now mkgrmf allows for creating HRC diagonal matrices.

Changes in the scripts 4.14.2 (April 2022) release

Remove the internal work-around to set the BPMASK for ACIS data to account for the frame-store shadow bad pixels. (CIAO 4.14 fixes this in ardlib.)

Changes in the scripts 4.14.1 (January 2022) release

The default value for the verbose parameter has been changed from 0 to 1.

Changes in the scripts 4.13.1 (March 2021) release

Ignore the frame-store shadow region

The frame-store shadow is now included when calculating the grating ARFs for ACIS observations. This means that there will a change to the effective area at wavelengths which intersect the bottom edge of the CCD (if any). Please see the ACIS frame-store caveat for more information.

HRC-I+LETG Line Spread Function

Updated to support HRC-I+LETG LSFPARM files if they are available in the CALDB. They are expected to be released in March 2021 with the Chandra CALDB 4.9.5 release.

Changes in the scripts 4.13.0 (December 2020) release

Fix for HRC-I + LETG data sets. There was a mismatch between the channel grid used in the PHA files and the grid used to create the RMF. As of CALDB 4.9.3, there are no grating RMF calibrations for HRC-I so the output is a diagonal RMF.

Changes in the scripts 4.10.3 (October 2018) release

Fix for the Python3 version where it fails to create responses for both HEG and MEG arms when individual orders are specified.

Recognizes when outroot is a directory and adjusts file names so they no longer begin with an underscore or period.

Changes in the scripts 4.10.1 (April 2018) release

Extend the chips used to create the ARF to support offset pointings when zero order is not on ACIS-7.

Changes in the scripts 4.9.4 (July 2017) release

Fix problem cleaning up temporary aspect histogram files under Python 3.

Changes in the scripts 4.9.2 (April 2017) release

The script can now work on TYPE:I (ie single spectra) PHA files.

Change in scripts 4.8.4 (September 2016) release

Updates to allow for ACIS-I + grating configurations.

Changes in scripts 4.7.2 (April 2015) release

The new orders parameter has been added to specify which responses' orders to create. The tool can also now create response files for the different grating orders and arms in parallel using the new nproc and parallel parameters.

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 - such as how to ensure that the parameter file is available.


Bugs

mktgresp fails to create MEG responses if orders parameter is set.

For datasets taken with the HETG inserted, mktgresp is supposed to create response files for all the orders listed for both HEG and MEG gratings. The Python3 edition in CIAO 4.10 of the script fails to create responses for the MEG arm.

The responses are only created for +/-1 HEG. The +/-1 HEG files which are created are correct.

Workaround:

Users can simply run mktgresp after chandra_repro to create the full set of +/- 1,2,3 HEG and MEG responses by setting the orders parameter to an empty|blank string.

unix% chandra_repro 19882 out= 
...
unix% mktgresp infile=19882/repro/acisf19882_repro_pha2.fits \
  evtfile=19882/repro/acisf19882_repro_evt2.fits \
  outroot=19882/repro/tg/acisf19882_repro \
  orders= \
  mode=h clob+

This creates the response files for each spectrum in the pha2.fits file.

Caveats

PHAFRAC column values

The grating ARF files created by mkgarf contain a PHAFRAC column. It is not used by any analysis tools nor is it used when modeling and fitting. It is contains diagnostic information used by the developers.

When the grating ARFs for individual CCDs are combined the dmarfadd tool simply copies the PHAFRAC column from one of the input files to the output. It does not try to combine the values in any way. This is also the case when combining positive and negative orders, and when combining responses from multiple observations.

Therefore, the PHAFRAC values may be different based on the order the files are input tool. Again, since the values are not used, this has user-visable effect.

Warnings related to missing SUM_2X2, OCLKPAIR, FEP_CCD, or ORC_MODE keywords

Users trying to run this tool with old versions of data products, those created with ASCDSVER less than version 8.4.2, may see warnings like


FITSIO status = 202: keyword not found in header
*** ERROR: *** Unable to get the value of `SUM_2X2' in /data/acisf04425_000N003_evt1.fits

Users should consult the Watch Out page for more information on this topic an information on how to upgrade their data products.

See Also

chandra
eventdef
tools::composite
combine_grating_spectra
tools::gratings
detilt, dewiggle, symmetrize, tg_bkg, tg_choose_method, tg_create_mask, tg_findzo, tg_resolve_events, tgdetect, tgdetect2, tgextract, tgextract2, tgidselectsrc, tgmask2reg, tgmatchsrc, tgsplit
tools::table
dmtype2split