Last modified: January 2023

URL: https://cxc.cfa.harvard.edu/ciao/ahelp/combine_spectra.html
AHELP for CIAO 4.16

combine_spectra

Context: Tools::Composite

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.


Examples

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:

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

Changes in the script 4.15.1 (January 2023) release

Setting the src_arfs parameter triggered two bugs that have now been fixed:

Changes in the script 4.12.2 (April 2020) release

The combine_spectra script has been updated to delete the NUMGRP and NUMELT keywords in the output RMF files. These keywords are optional and may be incorrectly set by the addresp tool.

Changes in the scripts 4.12.1 (December 2019) release

Updated to remove the grating order, tg_m, from the subspace during the merge. This was leading to multiple subspace components instead of simply collapsing into one.

Changes in the scripts 4.10.3 (October 2018) release

Recognizes when outroot is a directory and adjusts file names so they no longer begin with an underscore or period.

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.11.5 (September 2019) release

Fixed a bug when bkg_spectrum=NONE. It should have skipped combining background spectrum files even when the BACKFILE keywords were populated in the source spectra.

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 this page for installation instructions.


Bugs

Incorrect NUMGRP and NUMELT keywords

The addresp tool is not updating the NUMGRP nor the NUMELT keywords in the output file to match the actual values in the MATRIX's N_GRP and N_CHAN columns. It is simply copying those keywords from the 1st file to the output file. These incorrect values have shown to cause problems with XSPEC v 12.11.0.

See Also

calibration
ardlib
psf
psf
tools::aspect
asphist, dither_region
tools::background
acis_bkgrnd_lookup, hrc_bkgrnd_lookup, readout_bkg
tools::composite
combine_grating_spectra, specextract
tools::coordinates
sky2tdet
tools::core
dmextract
tools::response
acis_fef_lookup, acis_set_ardlib, addresp, dmarfadd, eff2evt, find_mono_energy, fullgarf, make_instmap_weights, mean_energy_map, mkacisrmf, mkarf, mkexpmap, mkgarf, mkgrmf, mkinstmap, mkpsfmap, mkrmf, mkwarf, psf_project_ray, rmfimg
tools::statistics
aprates