`add_grating_spectra' is a script which lets the user add up two grating
(PHA) spectra and average their associated ARF.
Optionally the output spectrum can be grouped.
Only combinations of PHA files and ARFs belonging to the same instrumental
configuration (i.e. ACIS-HETG-HEG, ACIS-HETG-MEG, ACIS-LETG-LEG, or
HRC-LETG-LEG), and diffraction order, are allowed.
The script combines a series of "dmtcalc" and "dmpaste" commands, performing
math operations bewtween columns of temporary files, and then merging
the final columns into the output PHA and ARF files. The CIAO tool
"dmgroup" is then eventually run, and some header keywords of the
output files are edited using "dmhedit".
The user supplies input PHA grating spectra and ARFs, and, optionally, the
grouping type and specifications (see "ahelp dmgroup").
Source counts from the two input spectra are simply added together, and
written out in the output file. A new column is written with the statistical
errors, calculated according to the formula: STAT_ERR = (1+sqrt(COUNTS+0.75)).
The two effective areas are weighted by the relative exposure, f1 =
(exp1/exp); f2 = (exp2/exp) [where exp = (exp1+exp2)], and added together.
Background spectra are weighted by their relative (exposure-weighted)
extraction area, according to the formula: BGD_UP = BACKSCUP *
[(BGD1/BACSCUP1) + (BGD2/BACKSCUP2)] (and the analogous for the BGD_DN).
In this formula, BACKSCUP1 and BACKSCUP2 are taken from the headers of the
two input pha files, and are the ratios between the width of the background
extraction region and the width of the source extraction region (typically
4.5 for default extraction ACIS-HETG or LETG spectra, and 5.0 for HRC-LETG
spectra).
BACKSCUP (and BACKSCDN) is propagated into the header of the output
spectrum according to the formula: BACKSCUP = 1/(f1/BACKSCUP1 +
f2/BACKSCUP2).
Optionally the output spectrum is grouped, according to the given grouping
type and specifications (see the parameters description, below).
Currently, the following dmgroup group-type options are available: BIN,
NONE, SNR, NUM_BINS, NUM_CTS, and ADAPTIVE (see "ahelp dmgroup"
for details). However, the dmgroup parameters "xcolumn" and "ycolumn" are
hard-coded and fixed to "channel" and "counts", respectively, as appropriate
for standard PHA files.
A number of keywords in the header of both the output PHA and ARF,
are edited. Namely: (a) the keyword EXPOSURE, is given the value
exp=(exp1+exp2); (b) the keyword BACKSCUP and BACKSCDN are edited
according to the above formula (see section on "OUTPUT BACKGROUND SPECTRA");
(c) the keyword ANCRFILE in the header of the output PHA file, is edited
and given the output ARF filename; (d) the keywords INSTRUMEN, GRATING and
TG_PART and TG_M (if any) are just copied from the headers of the input files
into the headers of the output files.
Parameter=pha1 (string required filetype=input)
First input PHA spectrum.
Parameter=pha2 (string required filetype=input)
Second input PHA spectrum.
Parameter=garf1 (string required filetype=input)
Effective Area associated to the first input PHA spectrum, pha1.
Parameter=garf2 (string required filetype=input)
Effective Area associated to the second input PHA spectrum, pha2.
Parameter=root (string required filetype=output)
Root name for the output files
root_<configuration>_<order>_<gtype+gspec>.pha
and root_<configuration>_<order>.arf.
The grouping type (NONE, BIN, SNR, NUM_BINS, NUM_CTS, or ADAPTIVE).
See "ahelp dmgroup" for details.
The grouping specification; form depends on GTYPE. See "ahelp dmgroup"
for details. Note that for the BIN grouping type, gspec corresponds
to the step size of the binning. The min and max of the binning
specification are hard-coded (1:8192 for ACIS, 1:16384 for HRC). Thus,
'10' is a valid gspec, but '1:8192:10' is not and will produce errors.
Clobber existing output files?
Specifies if existing output files should be overwritten.
Controls amount of information to print (0-5).
The verbose parameter provides debugging information;
verbose = 0 is usually fine.
![[CIAO Logo]](../imgs/ciao_logo_navbar.gif){kind=logo}