get_bkg_scale

sherpa.astro.ui.get_bkg_scale(id=None, bkg_id=1, units='counts', group=True, filter=False)

Return the background scaling factor for a background data set.

Return the factor applied to the background component to scale it to match it to the source, either when subtracting the background (units=’counts’), or fitting it simultaneously (units=’rate’).

Changed in version 4.12.2: The bkg_id, counts, group, and filter parameters have been added and the routine no-longer calculates the average scaling for all the background components but just for the given component.

Parameters:
  • id (int or str, optional) – The identifier for the data set to use. If not given then the default identifier is used, as returned by get_default_id.

  • bkg_id (int or str, optional) – Set to identify which background component to use. The default value is 1.

  • units ({'counts', 'rate'}, optional) – The correction is applied to a model defined as counts, the default, or a rate. The latter should be used when calculating the correction factor for adding the background data to the source aperture.

  • group (bool, optional) – Should the values be grouped to match the data?

  • filter (bool, optional) – Should the values be filtered to match the data?

Returns:

ratio – The scaling factor. The result can vary per channel, in which case an array is returned.

Return type:

number or array

See also

get_areascal

Return the fractional area factor of a PHA data set.

get_backscal

Return the area scaling factor for a PHA data set.

set_backscal

Change the area scaling of a PHA data set.

set_full_model

Define the convolved model expression for a data set.

set_bkg_full_model

Define the convolved background model expression for a PHA data set.

Notes

The scale factor when units=’counts’ is:

exp_src * bscale_src * areascal_src /
(exp_bgnd * bscale_bgnd * areascal_ngnd) /
nbkg

where exp_x, bscale_x. and areascal_x are the exposure, BACKSCAL, and AREASCAL values for the source (x=src) and background (x=bgnd) regions, respectively, and nbkg is the number of background datasets associated with the source aperture. When units=’rate’, the exposure and areascal corrections are not included.

Examples

Return the background-scaling factor for the default dataset (this assumes there’s only one background component).

>>> get_bkg_scale()
0.034514770047217924

Return the factor for dataset “pi”:

>>> get_bkg_scale('pi')
0.034514770047217924

Calculate the factors for the first two background components of the default dataset, valid for combining the source and background models to fit the source aperture:

>>> scale1 = get_bkg_scale(units='rate')
>>> scale2 = get_bkg_scale(units='rate', bkg_id=2)