addresp

Synopsis

Add multiple RMFs, weighted by ARFs and exposures; add mutiple ARFs, weighted by exposures.

addresp  infile arffile phafile outfile outarf [type] [method]
[lookupTab] [thresh] [clobber] [verbose]

Description

addresp adds together multiple imaging ARFs (auxiliary response files) and RMFs (response matrix files) to create a pair of merged ARF and RMF files. The tool may be run with just ARF files as input to create a merged ARF.

Each RMF is weighted by the SPECRESP and the exposure of the corresponding ARF. The "EBOUNDS" extension data in the output RMF are a copy of the EBOUNDS from the first RMF in the input stack.

Using method=avg

The effective area column (SPECRESP) in the ARF is weighted by the mean EXPOSURE. The combined ARF SPECRESP values are calculated as:

SPECRESP = sum(SPECRESP_i*t_i) / sum(t_i)/N

Average was the only available method in CIAO 4.3.

The addresp tool may be used with method=avg to combine grating ARFs, creating the same output the dmarfadd tool.

Using method=sum

The effective area column (SPECRESP) in the ARF is weighted by the mean EXPOSURE. The combined ARF SPECRESP values are calculated as:

SPECRESP = sum(SPECRESP_i*t_i) / sum(t_i)

For more detailed information on how the addresp tool works, refer to the "How & Why (or Why Not) to Combine Data" memo (PDF).

Examples

Example 1

ls acis*arf*.fits > arf.lis
ls acis*rmf*.fits > rmf.lis
ls acis*pha*.fits > pha.lis
addresp @rmf.lis @arf.lis @pha.lis rmf.fits arf.fits

Make a list of ARF, RMF, and PHA files in "arf.lis" and "rmf.lis", and "pha.lis", respectively. The files are combined by addresp to create two outputs: rmf.fits and arf.fits

Example 2

addresp infile="" arffile="9100_arf.fits,9810_arf.fits"
phafile="9100.pha,9810.pha" outfile="" outarf=combined_arf.fits

Merge two ARFs to create "combined_arf.fits". The infile and outfile parameters are empty since no RMFs are being combined.

Parameters

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input default= stacks=yes)

Input list of RMF files.

The input list of RMF files to be combined into one output file. The RMF files must have the same DETCHANS header keyword value and the same PI and PHA channels. The RMFs can be supplied as a comma-separated list or in a text file; see "ahelp stack" for more information.

The energy grids must be the same in all the files being combined. When combining both ARFs and RMFs, the input stacks must contain the same number of files.

Parameter=arffile (file required filetype=input default= stacks=yes)

Input list of ARF files.

The input list of ARF files to be combined into one output file. The ARFs can be supplied as a comma-separated list or in a text file; see "ahelp stack" for more information.

The energy grids must be the same in all the files being combined. When combining both ARFs and RMFs, the input stacks must contain the same number of files.

Parameter=phafile (file required filetype=input default= stacks=yes)

Input list of PHA files.

The input list of PHA files which are used to calculate the EXPOSURE and ONTIME header values for the output ARF file. The files can be supplied as a comma-separated list or in a text file; see "ahelp stack" for more information.

Parameter=outfile (file required filetype=output default=)

Output combined RMF or RSP

Each RMF is weighted by the SPECRESP and the exposure of the corresponding ARF. The "EBOUNDS" extension data in the output RMF are a copy of the EBOUNDS from the first RMF in the input stack.

If type=rsp, this is the name for the output RSP file.

Parameter=outarf (file required filetype=output default=)

Output combined ARF

The effective area column (SPECRESP) in the ARFs are weighted by the mean EXPOSURE. The output ARF maintains the same energy grid data of the first ARF in the input stack, and has a merged SPECRESP column.

If type=rsp, this parameter value is not used.

Parameter=type (string not required default=rmf)

Output type: rmf or rsp

Setting type=rsp means that the tool will combine the ARF and RMF into an RSP file instead of making two separate files. The "outfile" value is used as the name of the RSP file, and the "outarf" value is not used.

Parameter=method (string not required default=avg)

ARF merge method: avg or sum

If method=avg, the average of the PHA exposure times is written to the header of the combine ARF. If method=sum, the sum of the PHA exposure times is used.

Parameter=lookupTab (file filetype=input default=)

The header merging table

Rules to merge the headers when more than one file supplied.

Parameter=thresh (float 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.

Parameter=clobber (boolean default=no)

If "yes", then overwrite any existing output file. If a file exists and clobber is set to "no", the tool will exit with an error message.

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

Control the amount of diagnostic output to file from none (0) to a maximum (5).

Bugs

Incorrect RSP RMFs

RSP RMFs, those that are supposed to include the ARF, are incorrect. Users should not use type=rsp.

Bad warning when directory does not exist

The tool will return an unhelpful error message

# addresp (CIAO):
ERROR: failed to ariet ARF ->dm: [ftDatasetCreate]: FITS error 105 

when the output file cannot be created because the directory does not exist.

See Also

calibration

ardlib

concept

merging_rules

psf

psf

tools

acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, addresp, aprates, asphist, combine_grating_spectra, combine_spectra, dither_region, dmarfadd, dmextract, dmimgcalc, dmimgfilt, dmmerge, dmregrid2, eff2evt, fullgarf, hrc_bkgrnd_lookup, hrc_dtfstats, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, readout_bkg, reproject_image, reproject_image_grid, rmfimg, sky2tdet, specextract