Skip to the navigation links
Last modified: December 2009

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

add_grating_orders

Context: tools

Synopsis

Add positive and negative diffraction orders of a grating PHA spectra and the corresponding ARFs

Syntax

add_grating_orders pha2 order garm garfm garfp root [gtype] [gspec]
[clobber] [verbose]

Description

WHAT THE TOOL DOES

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

WHAT THE USER SHOULD SUPPLY

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

OUTPUT SOURCE AND BACKGROUND SPECTRUM

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

OUTPUT EFFECTIVE AREA

The two effective areas are added together and written out into the output ARF file.

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

The keyword ANCRFILE in the header of the output PHA is edit and given the output ARF filename. The keyword TG_M is not propagated into the header of the output PHA file.

Example 1

add_grating_orders pha2=spec.pha2 order=1 garm=HEG
garfm=eff_area_m1.arf garfp=eff_area_p1.arf root=test1 gtype=NONE
verbose=2

Add together negative and positive 1st order source and background HEG spectra in spec.pha2, and the corresponding ARFs in eff_area_m1.arf and eff_are_p1.arf. The output spectrum is not grouped. Output spectrum and ARF are named test1.pha and test1.arf.

Example 2

add_grating_orders pha2=spec.pha2 order=3 garm=LEG
garfm=eff_area_m3.arf garfp=eff_area_p3.arf root=test2 gtype=BIN
gspec=10 verbose=2

Add together negative and positive 3rd order source and background ACIS-LEG spectra in spec.pha2, and the corresponding ARFs in eff_area_m3.arf and eff_are_p3.arf. The output spectrum is grouped by a factor of 10. Output spectrum and ARF are named test2.pha and test2.arf.

Example 3

add_grating_orders pha2=spec.pha2 order=3 garm=HEG
garfm=eff_area_m3.arf garfp=eff_area_p3.arf root=test3 gtype=NUM_CTS
gspec=20 verbose=2

Add together negative and positive 3rd order source and background ACIS-LEG spectra in spec.pha2, and the corresponding ARFs in eff_area_m3.arf and eff_are_p3.arf. The output spectrum grouped allowing a minimum of 20 source counts per new bin. Output spectrum and ARF are named test3.pha and test3.arf.

Parameters

name type ftype reqd
pha2 string input yes
order string input yes
garm string input yes
garfm string input yes
garfp string input yes
root string output yes
gtype string   no
gspec string   no
clobber boolean   no
verbose integer   no

Detailed Parameter Descriptions

Parameter=pha2 (string required filetype=input)

Input PHA2 filename.

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.

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_ORDERS 2.6

Syntax for head command

The head command was replaced by the CIAO tool "dmkeypar". The file output is not affected.

CHANGES IN ADD_GRATING_ORDERS 2.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 CIAO 4.0/ADD_GRATING_ORDERS 2.4

It is necessary to specify an output block name of "SPECTRUM" in the dmtype2split commands used by the script. Quotation marks were also added to a dmhedit command so that the correct pathname written in the ANCRFILE header keyword in the output PHA file.

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_spectra, 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