Return to Threads Page: Top | All | Imag Spec

Coadding Spectra and Responses

CIAO 4.17 Science Threads

Overview

Synopsis:

The combine_spectra script sums multiple imaging source PHA spectra, and the associated background PHA spectra and ARF files.

Purpose:

To coadd imaging source and background spectra and the related response files for ACIS imaging observation or the 0th-order of a grating observation.

Last Update: 13 Jan 2021 - Review for CIAO 4.14. No changes.

Getting Started
- About combine_spectra
Running the Script
1. Reading from the Spectrum File Header
2. Listing the Input Files
Fitting
Caveats
History

Getting Started

This thread assumes that you have already extracted spectra and responses by running specextract. The examples use spectra and responses from five observations of NGC 6300 (ObsIds 10289-10293).

Note that combine_spectra can also be run from specextract. When extracting multiple spectra, set combine=yes and the spectra and responses will be coadded.

About combine_spectra

combine_spectra

a summed source spectrum
an exposure-weighted source ARF
an ARF- and exposure-weighted source RMF
an area- and exposure-weighted background spectrum
an exposure-weighted background ARF
an ARF- and exposure-weighted background RMF

The total exposure time and the BACKSCAL keywords are determined from the method and bscale_method parameters. The default is to sum the observation times and to compute backscale using the formula used by the ASCA mission.

Further technical details about how the output files are available in the combine_spectra help file.

Running the Script

The thread shows two sample runs of combine_spectra: letting the script read the filenames from the headers of the spectra and providing a list of all the input files.

When a list of source spectra is the only input provided, the script attempts to read the associated background and response file names from the spectra headers.

In this example, the input files are provided as a comma-separated list:

unix% punlearn combine_spectra
unix% pset combine_spectra src_spectra="10289.pi,10290.pi,10291.pi,10292.pi,10293.pi"
unix% pset combine_spectra outroot=ngc6300

Running the script with verbose=1 shows which files are being combined:

unix% combine_spectra verbose=1
Source PHA files to combine; enter list or '@stack' (10289.pi,10290.pi,10291.pi,10292.pi,10293.pi):
Root name for output files (ngc6300):
Prepared to combine 5 spectra

source PHA: 10289.pi
       ARF: 10289.arf
       RMF: 10289.rmf
    background PHA: 10289_bkg.pi
               ARF: 10289_bkg.arf
               RMF: 10289_bkg.rmf
source PHA: 10290.pi
       ARF: 10290.arf
       RMF: 10290.rmf
    background PHA: 10290_bkg.pi
               ARF: 10290_bkg.arf
               RMF: 10290_bkg.rmf
source PHA: 10291.pi
       ARF: 10291.arf
       RMF: 10291.rmf
    background PHA: 10291_bkg.pi
               ARF: 10291_bkg.arf
               RMF: 10291_bkg.rmf
source PHA: 10292.pi
       ARF: 10292.arf
       RMF: 10292.rmf
    background PHA: 10292_bkg.pi
               ARF: 10292_bkg.arf
               RMF: 10292_bkg.rmf
source PHA: 10293.pi
       ARF: 10293.arf
       RMF: 10293.rmf
    background PHA: 10293_bkg.pi
               ARF: 10293_bkg.arf
               RMF: 10293_bkg.rmf

The following files were created:
  ngc6300_src.pi
  ngc6300_bkg.pi
  ngc6300_src.arf
  ngc6300_bkg.arf
  ngc6300_src.rmf
  ngc6300_bkg.rmf

B. Listing the Input Files

If the file names are not available in the spectrum headers, or if you simply wish to list the files explicitly, each input parameter accepts a comma-separated list or a stack file.

In this run, a number of stack files are created. Each one contains the five filenames for that data product; for example:

unix% cat src.lis
10289.pi
10290.pi
10291.pi
10292.pi
10293.pi

unix% cat src_arf.lis
10289.arf
10290.arf
10291.arf
10292.arf
10293.arf

... repeated for RMF and background files...

The stack file is preceded by an "@" symbol so that the software parses the list of filenames:

unix% punlearn combine_spectra
unix% pset combine_spectra src_spectra=@src.lis
unix% pset combine_spectra src_arfs=@src_arf.lis
unix% pset combine_spectra src_rmfs=@src_rmf.lis
unix% pset combine_spectra bkg_spectra=@bg.lis
unix% pset combine_spectra bkg_arfs=@bg_arf.lis
unix% pset combine_spectra bkg_rmfs=@bg_rmf.lis
unix% pset combine_spectra outroot=ngc6300_stacks

The script is run with verbose=1 again:

unix% combine_spectra verbose=1
Source PHA files to combine; enter list or '@stack' (@src.lis):
Root name for output files (ngc6300_stacks):
  
Prepared to combine 5 spectra

source PHA: 10289.pi
       ARF: 10289.arf
       RMF: 10289.rmf
    background PHA: 10289_bkg.pi
               ARF: 10289_bkg.arf
               RMF: 10289_bkg.rmf
source PHA: 10290.pi
       ARF: 10290.arf
       RMF: 10290.rmf
    background PHA: 10290_bkg.pi
               ARF: 10290_bkg.arf
               RMF: 10290_bkg.rmf
source PHA: 10291.pi
       ARF: 10291.arf
       RMF: 10291.rmf
    background PHA: 10291_bkg.pi
               ARF: 10291_bkg.arf
               RMF: 10291_bkg.rmf
source PHA: 10292.pi
       ARF: 10292.arf
       RMF: 10292.rmf
    background PHA: 10292_bkg.pi
               ARF: 10292_bkg.arf
               RMF: 10292_bkg.rmf
source PHA: 10293.pi
       ARF: 10293.arf
       RMF: 10293.rmf
    background PHA: 10293_bkg.pi
               ARF: 10293_bkg.arf
               RMF: 10293_bkg.rmf

The following files were created:
  ngc6300_stacks_src.pi
  ngc6300_stacks_bkg.pi
  ngc6300_stacks_src.arf
  ngc6300_stacks_bkg.arf
  ngc6300_stacks_src.rmf
  ngc6300_stacks_bkg.rmf

Fitting

The RESPFILE and ANCRFILE header keywords have been updated in the combined spectrum file to point to the combine background and responses:

unix% dmlist ngc6300_src.pi header | grep FILE
0102 BACKFILE             NONE                           String
0103 CORRFILE             none                           String
0104 RESPFILE             ngc6300_src.rmf                String
0105 ANCRFILE             ngc6300_src.arf                String

If the background files are available, the BACKFILE keyword is also updated:

unix% dmlist ngc6300_stacks_src.pi header | grep FILE
0102 BACKFILE             ngc6300_stacks_bkg.pi          String       
0103 CORRFILE             none                           String       
0104 RESPFILE             ngc6300_stacks_src.rmf         String       
0105 ANCRFILE             ngc6300_stacks_src.arf         String

The header of the combined background file is also updated, when the responses are available:

unix% dmlist ngc6300_stacks_bkg.pi header | grep FILE
0104 BACKFILE             none                           String
0105 CORRFILE             none                           String
0106 RESPFILE             ngc6300_stacks_bkg.rmf         String
0107 ANCRFILE             ngc6300_stacks_bkg.arf         String

When the spectrum is read into Sherpa, the background file (when applicable) and source-related responses will automatically be read in as well.

To fit the background-subtracted source spectrum using a common RMF and ARF for source and background, simply read the source spectrum FITS file into Sherpa, subtract the background, and fit it. See the Introduction to Fitting PHA Spectra thread for details.

If the background rates contributing to a source are significantly different in the individual spectra to be combined, it is recommended that these spectra remain separate and be modeled simultaneously - otherwise, the modeling results of the combined source spectrum could be biased towards the observation(s) with the highest background rate(s).

To fit source and background spectra simultaneously with distinct RMFs and ARFs, follow the Independent Background Responses thread.

Caveats

Any grouping flags which may be present in input source or background PHA spectra will be ignored by the script. This is indicated in the script output at verboset > 0:
```
WARNING: The grouping flags in spectrum '10289.pi' will be ignored.
```
The data can be grouped after being read into Sherpa, as shown in the Changing the grouping scheme of a data set thread.
Combining background spectra with wildly varying spectral extraction region areas may yield misleading uncertainty estimates; i.e., some extractions will be over-represented while others will be under-represented.

History

13 Jan 2011	new for CIAO 4.3: the thread uses the combine_spectra script in place of the old acisspec script
25 Feb 2011	updated for 25 Feb scripts package release: combine_spectra correctly handles duplicate input filenames, e.g. source spectra all having the same name, located in different directories.
04 Apr 2011	updated for 04 Apr scripts package release: combine_spectra temporary files are written to the 'outroot' directory before being moved to /tmp; script prints version at verbose > 0.
20 Jul 2011	required software updates are listed in Synopsis
11 Jan 2012	reviewed for CIAO 4.4: removed reference to psextract, which is no longer in CIAO; added warning about summed times being different in PI and ARF files
16 Feb 2012	a combine_spectra update was released in the 16 Feb 2012 scripts package: works around a bug in addresp (no TLMIN4 keyword in the output RMF file) so that combined RMF files can be used in Sherpa and X-Spec.
03 Dec 2012	Review for CIAO 4.5; no changes
25 Nov 2013	Review for CIAO 4.6; no changes.
16 Dec 2014	Review for CIAO 4.7. Updated for combine_spectra verbose output.
13 Jan 2021	Review for CIAO 4.14. No changes.