NAME

USAGE

DESCRIPTION

The ahbackscal task corrects the BACKSCAL keyword in a spectrum file that has, for example, been extracted from xselect. The inputs to the task are the extraction region file and an exposure map, which must both 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. The xselect task sets BACKSCAL according to the fraction of pixels contained in the extraction region out of the total number of pixels on the detector, as defined by the TLMIN and TLMAX of the event list coordinate columns. If this region contains bad pixels, bad columns, partially exposed pixels, or regions outside of the field-of-view, the BACKSCAL keyword will be incorrect and will need to be corrected by the ahbackscal task.

The task works in the following way:

1. Mask the exposure map with the region file, setting pixels outside the region 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 (e.g., 'norm=100'). This third option makes the task mission-independent because some exposure maps are already normalized to unity.
4. Divide this value by the total number of pixels in the detector area, since this is how BACKSCAL is defined.

In general, using 'norm=MAX' is the best option 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 the ahbackscal task takes this correctly into account. It is important to note that the ahbackscal task 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. Note: since the result does not depend on the initial value of BACKSCAL, running the task more than once using the same input files will appear to not change the BACKSCAL keyword value because it will already be correct.

This task is designed to be mission-independent and will work for any PHA or PI 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).

PARAMETERS

infile [filename]

Name of input spectrum (PHA or PI) 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 may be an image in the primary extension of this file and must be in the same coordinate system used by 'regfile'.

(norm = MAX) [string MAX|EXPOSURE|value]

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 'norm' is 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 (which can be floating point), that value is used.

(cleanup = yes) [boolean yes|no]

Delete temporary files.

(clobber = no) [boolean yes|no]

Overwrites the existing output file if set to yes.

(chatter = 2) [integer 0|1|2|3]

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 DEFAULT|NONE|file name]

Log file name. If set to DEFAULT, uses the name of the task and, if preceded by "!", overwrites the file if it exists. If set to NONE, no log file is created.

(debug = no) [boolean yes|no]

Diagnostic output is printed to the screen if set to yes.

(history = yes) [boolean yes|no]

Records tool parameters in HISTORY.

EXAMPLES

1. Correct BACKSCAL in Hitomi/SXI source and background spectra, using the maximum value in the exposure map to normalize. Note: both use the same exposure map file.

      ahbackscal infile=ah100050010sxi_src.pi regfile=ah100050010sxi_src_sky.reg expfile=ah100050020sxi_cl.expo
   
      ahbackscal infile=ah100050010sxi_bkg.pi regfile=ah100050010sxi_bkg_sky.reg expfile=ah100050020sxi_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_src.pi regfile=ah100050010sxi_src_sky.reg expfile=ah100050020sxi_cl.expo \
         norm=EXPOSURE
   

3. Correct BACKSCAL in a XRISM/Xtend 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=xa100050020xtd_p0100004b0_src.pha regfile=xa100050020_spec.reg expfile=xa100050020xtd_p0100004b0_cl.expo norm=100
   

4. Correct BACKSCAL in a XRISM/Resolve source spectrum, using the maximum value in the exposure map to normalize.

      ahbackscal infile=xa100050020rsl_p0px1010_src.pha regfile=xa100050020_spec.reg expfile=xa100050020rsl_p0px1010_cl.expo norm=100
   

5. 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 norm=15549.23
   

SEE ALSO

LAST MODIFIED