Chandra X-Ray Observatory
	(CXC)
Skip to the navigation links
Last modified: March 2017

URL: http://cxc.harvard.edu/ciao/ahelp/combine_spectra.html
AHELP for CIAO 4.9

combine_spectra

Context: tools

Synopsis

Combine PHA files and their associated response files.

Syntax

combine_spectra  src_spectra outroot [src_arfs] [src_rmfs]
[bkg_spectra] [bkg_arfs] [bkg_rmfs] [method] [bscale_method]
[exp_origin] [clobber] [verbose]

Description

The combine_spectra script sums multiple PHA spectra. It will also combine the associated background PHA spectra and source and background ARF and RMF response files.

Typically only the src_spectra parameter and outroot parameters need to be specified, since the response (ARF and RMF) and background files will be found from the ANCRFILE, RESPFILE, and BACKFILE keywords in the spectra. If required, the user can override these settings using the src_arfs, src_rmfs, bkg_spectra, bkg_arfs, and bkg_rmfs parameters.

The output source spectrum will contain the sum of the source spectrum counts and (by default) the sum of the exposure time. The background counts are scaled by the exposure times and areas as discussed below.

Example 1

unix% combine_spectra obs1843.pi,obs1842.pi combined

Combine the two source spectra. The output source file is called combined_src.pi and contains the summed source counts and the summed EXPOSURE. If the files contain ANCRFILE, RESPFILE, and/or BACKFILE keywords, the responses and background files will also be created.

Example 2

unix% combine_spectra /data/pha1.pi,/data/pha2.pi summed \
bkg_spectra=pha1_bkg.pi,pha2_bkg.pi bkg_arfs=@pha_arf.lis

The input source spectra 'pha1.pi' and 'pha2.pi' are combined to produce the summed counts spectrum 'summed_src.pi'. The script locates the associated source ARF and RMF files for these spectra and combines them, producing output files 'summed_src.arf' and 'summed_src.rmf'. Instead of having the script search for the associated background spectra and background ARFs to combine, they are explicitly entered into the 'bkg_spectra' and 'bkg_arfs' parameters, the latter using a stack file.

Example 3

unix% combine_spectra @pha3.lis combined verbose=2

An ASCII file containing a list of Level-3 PHA spectral filenames is input to combine_spectra for combining. The script locates the associated source responses, background spectra, and background responses, and combines these files as well. The verbosity level is changed from the default value of 1 to 2, in order to print to the screen each step of the code as it is carried out.

Parameters

name type ftype def min max reqd stacks
src_spectra file input       yes yes
outroot file output       yes  
src_arfs file input       no yes
src_rmfs file input       no yes
bkg_spectra file input       no yes
bkg_arfs file input       no yes
bkg_rmfs file input       no yes
method string   sum     no  
bscale_method string   asca     no  
exp_origin string   pha     no  
clobber boolean   no     no  
verbose integer   1 0 5 no  

Detailed Parameter Descriptions

Parameter=src_spectra (file required filetype=input stacks=yes)

Source PHA files to combine; enter list or '@stack'

A stack of PHA TYPE:I spectra to combine.

Parameter=outroot (file required filetype=output)

Root name for output files

The script will create the following output files based on the available inputs:

  • ${outroot}_src.pi : Source spectrum
  • ${outroot}_src.arf : Source ARF file
  • ${outroot}_src.rmf: Source RMF file
  • ${outroot}_bkg.pi : Background spectrum
  • ${outroot}_bkg.arf : Background ARF file
  • ${outroot}_bkg.rmf : Background RMF file

Parameter=src_arfs (file not required filetype=input stacks=yes)

Source ARF files to combine; enter list or '@stack'

If this parameter is blank then the script will locate the ARF file using the ANCRFILE keyword in each of the input files. If given, then the order of the ARF files must match the order of the src_spectra parameter.

The parameter can be set to "NONE" and the keyword value will not be used.

Parameter=src_rmfs (file not required filetype=input stacks=yes)

Source RMF files to combine; enter list or '@stack'

If this parameter is blank then the script will locate the RMF file using the RESPFILE keyword in each of the input files. If given, then the order of the RMF files must match the order of the src_spectra parameter.

The parameter can be set to "NONE" and the keyword value will not be used.

Note: RSP-style responses which have been premultiplied by an ARF are not supported.

Parameter=bkg_spectra (file not required filetype=input stacks=yes)

Background PHA files to combine; enter list or '@stack'

If this parameter is blank then the script will locate the background file using the BACKFILE keyword in each of the input files. If given, then the order of the background files must match the order of the src_spectra parameter.

The parameter can be set to "NONE" and the keyword value will not be used.

Parameter=bkg_arfs (file not required filetype=input stacks=yes)

Background ARF files to combine; enter list or '@stack'

See the src_arfs parameter for more details.

Parameter=bkg_rmfs (file not required filetype=input stacks=yes)

Background RMF files to combine; enter list or '@stack'

See the src_rmfs parameter for more details.

Parameter=method (string not required default=sum)

Sum or average PHA exposures?

The method parameter may be set to either 'sum' (default) or 'avg' to specify how the individual PHA exposure times should be combined for the output combined spectrum. When 'method=sum', combined spectra are output with the total PHA exposure time recorded in the header. When 'method=avg' , the mean exposure time is recorded. The output combined responses are appropriately adjusted for the current 'method' setting.

Parameter=bscale_method (string not required default=asca)

How are BACKSCAL and background counts computed?

There are 3 different algorithms to combine the background counts compute the background scaling (BACKSCAL) values.

'asca'

When simply subtracting the background, the 'asca' method can be used. The combined background counts are an exposure and area weighted combination:

f = {(bkg_exp1 + ... + bkg_expN)/[src_exp1(src_backscal1/bkg_backscal1) + ... + src_expN(src_backscalN/bkg_backscalN)]}*
f_I = f*{(src_expI/bkg_expI)*(src_backscalI/bkg_backscalI)}  
BKG_COUNTS = f_1*bkg_counts1 + f_2*bkg_counts2 + ... f_N*bkg_countsN
BKG_BACKSCAL = (src_exp1 + ... + src_expN)/[src_exp1(src_backscal1/bkg_backscal1) + ...  + src_expN(src_backscalN/bkg_backscalN)]  
SOURCE_COUNTS = src_counts1 + src_counts2 + ... + src_countsN
SOURCE_EXPOSURE = src_exp1 + src_exp2 + ... + src_expN
SOURCE_BACKSCAL = 1.0
'time'

The 'time' methods computes the total counts (unweighted) and the provides and exposure time weighted BACKSCAL value.

BKG_COUNTS = bkg_counts1 + bkg_counts2 + ... bkg_countsN
SS = [(src_exp1*src_backscal1) + ... + (src_expN*src_backscalN)] / (src_exp1 + ... + src_expN)
BB = [(bkg_exp1*bkg_backscal1) + ... + (bkg_expN*bkg_backscalN)] / (bkg_exp1 + ... + bkg_expN)
BKG_BACKSCAL = BB / SS
SOURCE_COUNTS = src_counts1 + src_counts2 + ... + src_countsN
SOURCE_EXPOSURE = src_exp1 + src_exp2 + ... + src_expN
SOURCE_BACKSCAL = 1.0
'counts'

The 'counts' method gives background counts and backscale values that are correctly weighted when the background is going to be modeled rather than subtracted. That is the background has been combined such that the errors on the background are correct.

r_i = (src_exp_i*src_backscal_i)/(bkg_exp_i*bkg_backscal_i)
m1 = (bkg_counts1*r_1) + ... + (bkg_countsN*r_N)
m2 = (bkg_counts1*r_1^2) + ... + (bkg_countsN*r_N^2)

BKG_COUNTS = (m1*m1) / m2
BKG_BACKSCAL = SOURCE_BACKSCAL * ((src_exp1+...+src_expN)/(bkg_exp1+...+bkg_expN))*(m1/m2)

SOURCE_COUNTS = src_counts1 + src_counts2 + ... + src_countsN
SOURCE_EXPOSURE = src_exp1 + src_exp2 + ... + src_expN
SOURCE_BACKSCAL = (src_exp1*src_backscal1) + ... + (src_expN*src_backscalN) / (src_exp1 + ... + src_expN)

Parameter=exp_origin (string not required default=pha)

Write combined PHA or ARF exposure time to header(s) (pha, arf)

Should the combined EXPOSURE time be taken from the PHA or ARF files?

Parameter=clobber (boolean not required default=no)

OK to overwrite existing output file?

Parameter=verbose (integer not required default=1 min=0 max=5)

Debug Level(0-5)

Caveats

  • Any grouping flags which may be present in input source or background PHA spectra will be ignored by the script.
  • 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.
  • 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).
  • RSP-style responses which have been premultiplied by an ARF are not supported.
  • Statistical errors on the combined counts in the combined source and background spectra are only recomputed using the Gehrel's approximation if the input file has a STAT_ERR column.
  • Non-chandra files may not work correctly.

Changes in the scripts 4.9.2 (April 2017) release

If the input spectra contain a STAT_ERR column, the script will now recompute the error using the Gehrel's approximation.

Change in the 4.7.3 (June 2015) release

The path name is now removed from the file names stored in the ANCRFILE, RESPFILE, and BACKFILE keywords.

Changes in the 4.6.7 (November 2014) release

Users can now specify src_arf, src_rmf, bkg_spectra, bkg_arf, and bkg_rmf as "NONE" to for the tool to entirely skip combining those products, even if they are able to be located by the ANCRFILE, RESPFILE, or BACKFILE keywords in the input source spectrum files. (Value is case sensitive)

Fixes a bug in the bscale_method='counts' method when the combined background counts in any channel is 0.

Changes in the CIAO 4.6.6 (September 2014) release

The script will ensure that the ONTIME, LIVETIME, and EXPOSURE keywords (and the per-chip variants) in the output ARF files are consistent with the input ARF times. The PHA values in the PHA files (used by sherpa and xspec) are not affected.

Changes in the CIAO 4.6.5 (June 2014) release

The combine_spectra script has been completely re-written. It no longer makes use of a large number of temporary files and as a result is much faster.

Two new parameters have been added. exp_origin controls whether the EXPOSURE keyword is computed from the spectrum, pha, files or whether it is computed from the ARF files. bscale_method allows the user to select different algorithms to compute the combined background counts and associated scaling factor (BACKSCAL); the default, 'asca', is the same as previous versions of this script.

Changes in the February 2012 Release

The script was updated to work around a CIAO 4.4 bug in the tool addresp, used for combining ARF and RMF responses: the output combined RMF file is missing the TLMIN header keyword for the F_CHAN column; combine_spectra now adds the TLMIN4 keyword to the combined RMF file.

The script now cleans up several temporary files which were being written to the outroot directory, instead of to /tmp/.

Changes in the December 2011 Release

New 'method' parameter for selecting between a summed and mean exposure value to be recorded in the header of output combined spectra and ARFs.

Bug fix: the ANCRFILE header keyword in an output combined background spectrum was incorrectly being set to "NONE" when the input backround response files exactly matched the input source responses.

Internal updates to the addresp step of the script to support the new addresp 'phafiles' and 'method' parameters.

Changes in the April 2011 Release

The script prints the version number when verbosity is greater than 0.

Temporary output files are written to the 'outroot' directory instead of the current working directory, before being moved to the /tmp directory.

Changes in the December 2010 Release

combine_spectra in CIAO 4.3 invokes the new tool addresp for combining ARF and RMF responses. Prior to this release, the script combined ARFs via the dmarfadd tool - with results equivalent to the output of addresp - and did not combine RMFs.

About Contributed Software

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

There are no known bugs for this tool.

See Also

calibration
ardlib
psf
psf
tools
acis_bkgrnd_lookup, acis_fef_lookup, acis_set_ardlib, addresp, aprates, asphist, combine_grating_spectra, dither_region, dmarfadd, dmextract, eff2evt, fullgarf, hrc_bkgrnd_lookup, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psextract, psf_project_ray, readout_bkg, rmfimg, sky2tdet, specextract

Last modified: March 2017
Smithsonian Institute Smithsonian Institute

The Chandra X-Ray Center (CXC) is operated for NASA by the Smithsonian Astrophysical Observatory. 60 Garden Street, Cambridge, MA 02138 USA.   Email:   cxchelp@head.cfa.harvard.edu Smithsonian Institution, Copyright © 1998-2017. All rights reserved.