Skip to the navigation links
Last modified: 14 Jan 2009
Where are the PDFs?

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

CIAO 4.2 Science Threads


Last Update: 14 Jan 2009 - updated for CIAO 4.2: ObsID 459 file versions


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. The output spectrum can be grouped if desired.


To generate and group a coadded positive and negative order grating spectrum (for both source and background) and the associated ARF.

Read this thread if:

you are working with ACIS/HETG, ACIS/LETG, or HRC/LETG observational data and would like to add the grating orders.

Related Links:


Get Started

Sample ObsID used: 459 (HETG/ACIS-S, 3C 273)

File types needed: 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:


How to handle the RMFs

The RMF files for the observation should 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.

Downloading add_grating_orders

The thread uses the add_grating_orders script, which is part of the CIAO Scripts distribution. The CIAO scripts package should be the following version or newer:

17 Apr 2009

Please check that you have at least this version of the scripts package installed before continuing. If you do not have the scripts installed or need to update to a newer version, refer to the Scripts page.

Run add_grating_orders

The script executes the following tools in order:

  1. dmtype2split: to split the PHA2 spectrum into two temporary positive and negative order spectra with PHA1-like format.
  2. dmtcalc: to rename columns in the two temporary PHA1 files, and to build two temporary single-order ARFs with renamed columns.
  3. dmpaste: to merge the two temporary PHA1 spectra and ARFs. gspec
  4. dmtcalc: to add together positive and negative spectra and ARFs.
  5. dmcopy: to build a final coadded spectrum (with a PHA1-like format) and a coadded ARF.
  6. 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.


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)              


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

Return to Threads Page: Top | All | Grating

Where are the PDFs?
Last modified: 14 Jan 2009