get_bkg_scale

Context: data

Synopsis

Return the background scaling factor for a background data set.

Syntax

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

Description

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').

Examples

Example 1

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

>>> get_bkg_scale()
0.034514770047217924

Example 2

Return the factor for dataset "pi":

>>> get_bkg_scale('pi')
0.034514770047217924

Example 3

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)

PARAMETERS

The parameters for this function are:

Parameter	Type information	Definition
id	int, 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_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?

Return value

The return value from this function is:

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

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.

Changes in CIAO

Changed in CIAO 4.13

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.

Bugs

See the bugs pages on the Sherpa website for an up-to-date listing of known bugs.