ahbackscal -- Correct BACKSCAL keyword in a spectrum extracted with XSELECT.


ahbackscal infile regfile expfile


'ahbackscal' corrects the the BACKSCAL keyword in a spectrum file that has been extracted from XSELECT, using as input the extraction region file and an exposure map, which must be defined in the same coordinate system. The BACKSCAL keyword is used by XSPEC to properly scale the background spectrum before subtracting it from the source spectrum, since the extraction regions are usually different between source and background. XSELECT sets BACKSCAL according to the fraction of pixels contained in the extraction region compared to the number of pixels defined by the TLMIN and TLMAX of the event list coordinate columns. If this region contains bad pixels, bad columns, partially exposed pixels, regions outside of the field-of-view, the BACKSCAL keyword will be incorrect.

The task works in the following way:

1. Mask the exposure map with the region file so that parts outside the region are set to zero.
2. Sum up the pixel values in the good region.
3. Normalize this sum by the maximum value in the exposure map ('norm=MAX'), by the spectrum file exposure time keyword ('norm=EXPOSURE'), or by some specified numerical value ('norm=value'). This third option makes the tool mission-independent, because some "exposure maps" are already normalized to unity.
4. Divide this value by the number of pixels in the coordinate system, since this is how BACKSCAL is defined.

In general, 'norm=MAX' should be used to properly scale the number of good pixels in the exposure map. Due to spacecraft attitude motion and therefore pixels with partial exposure in 'expfile', the total number of good pixels will not necessarily be an integer, and 'ahbackscal' takes this correctly in to account. It is important to note that 'ahbackscal' only corrects the scaling used to subtract the background spectrum in XSPEC; spectral modeling already accounts for all pixels that are bad, partially exposed, or out of the field-of-view by using properly constructed response files (RMF and ARF). There is no output file, instead the BACKSCAL keyword is updated in the input spectrum file.

This tool is designed to be mission-independent, and will work for any PHA spectrum extracted from XSELECT as long as the SAO region file 'regfile' and exposure map image 'expfile' are specified in the same coordinates (e.g. DET or SKY).


infile [filename]
Name of input spectrum (PHA) file. The BACKSCAL keyword is updated in this file.

regfile [filename]
Name of input region file. The format is that of a standard SAO region file, and the coordinate system should be the same as that of 'expfile'.

expfile [filename]
Name of input exposure map file. The exposure map my be an image in the primary extension of this file, in the same coordinate system used by 'regfile'.

(norm = MAX) [string]
Normalization value for exposure map file. This value is used to scale the summed pixel values in 'expfile' within the region defined by 'regfile'. If set to MAX, the maximum pixel value is used. If set to EXPOSURE, the value of the EXPOSURE keyword in the first extension of 'expfile' is used. If set to a numerical value (can be floating point), that value is used.

(cleanup = yes) [boolean]
Delete temporary files ([yes]/no)

(clobber = no) [boolean]
Overwrites the existing output file if set to yes (yes/[no]).

(chatter = 1) [integer]
Chatter level for output. Set to 0 to suppress output, or to 1, 2, or 3 for increasing the chatter of the output.

(logfile = !DEFAULT) [string]
Log filename. If set to DEFAULT uses the name of the task and, if preceded by '!', overwrite the file if it exists. If set to NONE no log file is created.

(debug = no) [boolean]
Diagnostic output is printed out on the screen if set to yes (yes/[no]).

(history = yes) [boolean]
Records tool parameters in HISTORY if set to yes ([yes]/no).

(mode = ql) [string ql|hl|q]
Mode to query the parameter file. Acceptable values include: "ql (query and learn/remember), "hl" (hidden and learn/remember), "q" (query but don't remember), "h" (hidden).


  1. Correct BACKSCAL in Hitomi SXI source and background spectra, using the maximum value in the exposure map to normalize (the default behavior). Note that both use the same exposure map file.
    ahbackscal infile=ah100050010sxi_p0100004b0_cl_src.pi regfile=sxi_src_wcs.reg expfile=ah100050020sxi_p0100004b0_cl.expo
    ahbackscal infile=ah100050010sxi_p0100004b0_cl_bkg.pi regfile=sxi_bkg_wcs.reg expfile=ah100050020sxi_p0100004b0_cl.expo
  2. Correct BACKSCAL in a Hitomi SXI spectrum, using the EXPOSURE keyword in the exposure map first extension to normalize.
    ahbackscal infile=ah100050010sxi_p0100004b0_cl_src.pi regfile=sxi_src_wcs.reg expfile=ah100050020sxi_p0100004b0_cl.expo norm=EXPOSURE
  3. Correct BACKSCAL in a Suzaku XIS spectrum, specifying a value to use as the exposure map normalization. This should be the maximum expected value in the exposure map, usually the exposure time in seconds.
    ahbackscal infile=xis_src.pha regfile=xis_src_wcs.reg expfile=xis_src.expo




December 2016