Extract Coadded and Grouped Nth-Order Source & Background Spectra and ARFs

CIAO 4.5 Science Threads

Overview

Synopsis:

The add_grating_orders script sums the positive and negative diffraction orders of a given grating spectrum, and the associated ARFs. The output spectrum can be grouped if desired.

Purpose:

To create a coadded positive and negative order grating spectrum and ARF for ACIS/HETG, ACIS/LETG, or HRC/LETG observational data.

Related Links:

Analysis Guide for Chandra High Resolution Spectroscopy: an in-depth discussion of grating analysis.

Last Update: 3 Dec 2012 - Review for CIAO 4.5; no changes

Get Started
- How to handle the RMFs
Run add_grating_orders
Summary
Parameter files:
- add_grating_orders
History

Get Started

Download the sample data: 459 (HETG/ACIS-S, 3C 273)

unix% download_chandra_obsid 459 pha2

This thread assumes that you have created positive and negative grating ARFs for your dataset. This process is illustrated in the threads for building ACIS/HETG, ACIS/LETG, HRC-S/LETG, or HRC-I/LETG ARFs.

The data to be combined must have been taken with the same instrumental configuration:

ACIS-HETG-HEG
ACIS-HETG-MEG
ACIS-LETG-LEG
HRC-LETG-LEG

How to handle the RMFs

The RMF files for the observation should, ideally, not be summed, and so they must be considered before adding the orders together.

If the data being used are all near on-axis (as they usually are for gratings), then the RMFs made for one observation can be used for the summed spectrum file.

If RMFs are different enough to matter, then the orders should not be summed at all. Analyze the spectra simultaneously instead. Note that RMFs are nearly indistinguishable for ACIS/HETG, but they might differ near plate boundaries for LETG data.

Note: The combine_grating_spectra script does combine input RMFs when associated ARFs are also available (it writes an ARF- and exposure-weighted summed RMF), however the caveats listed above still apply.

Run add_grating_orders

The script executes the following tools in order:

dmtype2split: to split the PHA2 spectrum into two temporary positive and negative order spectra with PHA1-like format.
dmtcalc: to rename columns in the two temporary PHA1 files, and to build two temporary single-order ARFs with renamed columns.
dmpaste: to merge the two temporary PHA1 spectra and ARFs. gspec
dmtcalc: to add together positive and negative spectra and ARFs.
dmcopy: to build a final coadded spectrum (with a PHA1-like format) and a coadded ARF.
dmgroup: to group the coadded positive and negative order spectrum (if needed).

In this example, we build coadded 1st-order source and background MEG spectra and a 1st-order ARF. Then the source spectrum is grouped by a factor of 10 (to learn more about the several options for gtype, see ahelp dmgroup. Note that the adaptive grouping ("ADAPTIVE") may take a long time on large PHA files):

unix% punlearn add_grating_orders
unix% pset add_grating_orders pha2=acisf00459N004_pha2.fits
unix% pset add_grating_orders order=1
unix% pset add_grating_orders garm=MEG
unix% pset add_grating_orders garfm=acisf00459MEG_-1_garf.fits
unix% pset add_grating_orders garfp=acisf00459MEG_1_garf.fits
unix% pset add_grating_orders gtype=BIN
unix% pset add_grating_orders gspec=10
unix% pset add_grating_orders root=459

unix% add_grating_orders
Input PHA2 spectrum (acisf00459N004_pha2.fits): 
Order of the grating spectra to extract and add together (1): 
Grating Arm (HEG, MEG or LEG) (MEG): 
Negative order grating ARF (acisf00459MEG_-1_garf.fits): 
Positive order grating ARF (acisf00459MEG_1_garf.fits): 
Root name for output files (459): 

Input pha2 file is: acisf00459N004_pha2.fits
Using MEG grating ARF order 1: acisf00459MEG_-1_garf.fits
Using MEG grating ARF order 1: acisf00459MEG_1_garf.fits
The root filename for the output file is: 459


The coadded, grouped output spectrum is named 459_MEG_1_BIN10.pha
The coadded Effective Area is named 459_MEG_1.arf

The content of the parameter file may be checked using plist add_grating_orders.

Summary

The thread is now complete. The coadded 1st-order spectra are contained in the PHA1-like file named 459_MEG_1_BIN10.pha; the coadded +/- 1st order ARF is named 459_MEG_1.arf.

To load this data into Sherpa, see the Introduction to Fitting PHA Spectra thread.


Parameters for /home/username/cxcds_param/add_grating_orders.par


          pha2 = acisf00459N004_pha2.fits Input PHA2 spectrum
         order = 1                Order of the grating spectra to extract and add together
          garm = MEG              Grating Arm (HEG, MEG or LEG)
         garfm = acisf00459MEG_-1_garf.fits Negative order grating ARF
         garfp = acisf00459MEG_1_garf.fits Positive order grating ARF
          root = 459              Root name for output files
        (gtype = BIN)             Spectrum grouping type
        (gspec = 10)              Spectrum grouping specs (NONE,10,etc)
      (clobber = no)              Clobber existing output files?
      (verbose = 0)               Debug Level(0-5)
         (mode = ql)

History

14 Dec 2004	updated for CIAO 3.2: created Downloading add_grating_orders section
06 Dec 2005	reviewed for CIAO 3.3: no changes
01 Dec 2006	reviewed for CIAO 3.4: no changes
23 Jan 2008	updated for CIAO 4.0: `add_grating_orders` v2.0 (specify an output block name of "SPECTRUM" in the `dmtype2split` commands, `kernel` parameter removed from `dmtcalc` and `dmpaste`); Sherpa syntax updated; Sherpa link points to Beta website
30 May 2008	add_grating_orders v2.6 (Unix head and tail commands replaced by `pget` and `dmkeypar`)
06 Jun 2008	added How to handle the RMFs section
12 Feb 2009	reviewed for CIAO 4.1: no changes
06 May 2009	check the version of the CIAO scripts package instead of the individual script
14 Jan 2009	updated for CIAO 4.2: ObsID 459 file versions
12 Jan 2011	reviewed for CIAO 4.3: no changes
09 Jan 2012	reviewed for CIAO 4.4: no changes
03 Dec 2012	Review for CIAO 4.5; no changes