Skip to the navigation links
Last modified: December 2009

URL: http://cxc-newtest.cfa.harvard.edu/ciao4.2/add_grating_spectra.html
AHELP for CIAO 4.2

add_grating_spectra

Context: tools

Synopsis

Add two, source and background, grating PHA spectra, averages the corresponding ARFs, and group the coadded spectrum.

Syntax

add_grating_spectra pha1 pha2 garf1 garf2 root [gtype] [gspec]
[clobber] [verbose]

Description

WHAT THE TOOL DOES

`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".

WHAT THE USER SHOULD SUPPLY

The user supplies input PHA grating spectra and ARFs, and, optionally, the grouping type and specifications (see "ahelp dmgroup").

OUTPUT SOURCE SPECTRUM

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)).

OUTPUT AVERAGED EFFECTIVE AREA

The two effective areas are weighted by the relative exposure, f1 = (exp1/exp); f2 = (exp2/exp) [where exp = (exp1+exp2)], and added together.

OUTPUT BACKGROUND SPECTRA

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).

GROUPING THE OUTPUT SPECTRUM

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.

HEADER KEYWORDS IN THE OUTPUT 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.

Example 1

add_grating_spectra pha1=spec1.pha pha2=spec2.pha garf1=eff_area_1.arf
garf2=eff_area_2.arf root=test1 gtype=NONE gspec verbose=2

Add together source and background spectra in spec1.pha and spec2.pha, and the corresponding ARFs in eff_area_1.arf and eff_are_2.arf. The output spectrum is not grouped. Output spectrum and ARF are named test1_<configuration>_<order>_NONE.pha and test1_<configuration>_<order>.arf.

Example 2

add_grating_spectra pha1=spec1.pha pha2=spec2.pha garf1=eff_area_1.arf
garf2=eff_area_2.arf root=test2 gtype=BIN gspec=10 verbose=2

Add together source and background spectra in spec1.pha and spec2.pha, and the corresponding ARFs in eff_area_1.arf and eff_are_2.arf. The output spectrum is grouped by a factor of 10. Output spectrum and ARF are named test2_<configuration>_<order>_BIN10.pha and test2_<configuration>_<order>.arf.

Example 3

add_grating_spectra pha1=spec1.pha pha2=spec2.pha garf1=eff_area_1.arf
garf2=eff_area_2.arf root=test3 gtype=NUM_CTS gspec=20 verbose=2

Add together source and background spectra in spec1.pha and spec2.pha, and the corresponding ARFs in eff_area_1.arf and eff_are_2.arf. The output spectrum is grouped, allowing a minimum of 20 source counts per new bin. Output spectrum and ARF are named test3_<configuration>_<order>_NUM_CTS10.pha and test3_<configuration>_<order>.arf.

Parameters

name type ftype reqd
pha1 string input yes
pha2 string input yes
garf1 string input yes
garf2 string input yes
root string output yes
gtype string   no
gspec string   no
clobber boolean   no
verbose integer   no

Detailed Parameter Descriptions

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.

Parameter=gtype (string not required)

The grouping type (NONE, BIN, SNR, NUM_BINS, NUM_CTS, or ADAPTIVE). See "ahelp dmgroup" for details.

Parameter=gspec (string not required)

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.

Parameter=clobber (boolean not required)

Clobber existing output files?

Specifies if existing output files should be overwritten.

Parameter=verbose (integer not required)

Controls amount of information to print (0-5).

The verbose parameter provides debugging information; verbose = 0 is usually fine.

CHANGES IN ADD_GRATING_SPECTRA 3.6

Syntax for head command

The head commands were replaced by the CIAO tool "dmkeypar". The file output is not affected.

CHANGES IN ADD_GRATING_SPECTRA 3.5

Syntax for head command

The syntax of the head command was updated to include the "-n" flag. The file output is not affected.

CHANGES IN ADD_GRATING_SPECTRA 3.4

The dmkeypar tool is used in place of Unix "tail".

CHANGES IN CIAO 4.0/ADD_GRATING_SPECTRA 3.3

The "kernel" parameter was removed from dmtcalc and dmpaste in CIAO 4.0.

NOTES

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 the installation instructions page for help on installing the package.

Bugs

See the bugs page for this script on the CIAO website for an up-to-date listing of known bugs.

See Also

calibration
ardlib
tools
acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, acisspec, add_grating_orders, asphist, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, merge_all, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsf, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, rmfimg, specextract

Last modified: December 2009