`add_grating_orders' is a script which lets the user add up positive and
negative diffraction orders of a given grating spectrum, and their
associated ARFs.
Optionally the output spectrum can be grouped.
The script splits the PHA2 file into two (negative and positive) PHA spectra
using the CIAO tool "dmtype2split". Then it combines a series of "dmtcalc"
and "dmpaste" commands, performing math operations bewtween columns of these
two 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 (a) the input PHA2 file, the order to be coadded
(i.e. 1, 2 or 3, for a default ACIS-HETG or -LETG PHA2 file),
(b) the grating arm (i.e. HEG, MEG or LEG), (c) the ARFs of the negative
and positive orders to coadd, and (d) optionally, the grouping type and
specifications (see "ahelp dmgroup").
Source counts from the two input source and background spectra are simply
added together, and written out into the output PHA file.
The values of the keywords BACKSCAL, BACKSCUP and BACKSCDN in the header
of the output PHA file are hard-coded in the script and are equal to 1.0,
4.5, 4.5 for ACIS, and 1.0, 5.0 and 5.0 for HRC input spectra, respectively.
This is correct only for input negative and positive spectra extracted with
default extraction region sizes for both source and background.
If non-default source and/or background extraction region
have been used to extract the negative and positive spectra in the input PHA2
file, then the BACKSCUP and BACKSCDN keywords of the output PHA file should
be edited and properly set to the ratios of the width of the
background-up and background-down regions to the width of the source region,
respectively.
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 added together and
written out into the output ARF file.
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.
The keyword ANCRFILE in the header of the output PHA is edit and given the
output ARF filename.
The keywords EXPOSURE, INSTRUMEN, GRATING and TG_PART are just copied from
the headers of the two splitted temporary PHA files into the headers of the
output files (PHA and ARF). The keyword TG_M is not propagated into the
header of the output PHA file.
Parameter=order (string required filetype=input)
Order of the grating spectra to extract and add together.
Parameter=garm (string required filetype=input)
Grating Arm (HEG, MEG or LEG).
Parameter=garfm (string required filetype=input)
Negative order grating effective area.
Parameter=garfp (string required filetype=input)
Positive order grating effective area.
Parameter=root (string required filetype=output)
Root name for the output files root.pha and root.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}