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:
- ${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 script 4.15.1 (January 2023) release
Setting the src_arfs parameter triggered two bugs that have now been fixed:
- The exposure times would be taken from the ARF instead of the PHA file (even with exp_origin=pha). This will not affect most Chandra imaging (non-grating) data since the values are usually the same.
- If the bkg_spectra parameter was left blank (default), the script would not be able to locate the background spectra via the BACKFILE keywords. Similarly, if the src_rmfs parameter was blank, the script would not be able to locate the RMF files using the RESPFILE keywords.
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
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