get_bkg_scale

sherpa.astro.ui.get_bkg_scale(id: IdType | None = None, bkg_id: IdType = 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:

idint, str, or None, 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_idint 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.

groupbool, optional

Should the values be grouped to match the data?

filterbool, optional

Should the values be filtered to match the data?

Returns:

rationumber or array

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

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)