Last modified: December 2023

URL: https://cxc.cfa.harvard.edu/sherpa/ahelp/get_bkg_scale.html
AHELP for CIAO 4.16 Sherpa

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)

id - int or str, optional
bkg_id - int or str, optional
units - {'counts', 'rate'}, optional
group - bool, optional
filter - bool, optional

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 Definition
id 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 Set to identify which background component to use. The default value is 1.
units 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 Should the values be grouped to match the data?
filter 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.

See Also

confidence
get_conf, get_conf_results, get_covar, get_covar_opt, get_covar_results, get_covariance_results, get_int_proj, get_int_unc, get_proj, get_proj_opt, get_proj_results, get_projection_results, get_reg_proj, get_reg_unc
contrib
get_chart_spectrum, get_marx_spectrum
data
get_areascal, get_arf, get_arf_plot, get_axes, get_backscal, get_bkg, get_bkg_arf, get_bkg_chisqr_plot, get_bkg_delchi_plot, get_bkg_fit_plot, get_bkg_model, get_bkg_model_plot, get_bkg_plot, get_bkg_ratio_plot, get_bkg_resid_plot, get_bkg_rmf, get_bkg_source, get_bkg_source_plot, get_coord, get_counts, get_data, get_data_contour, get_data_contour_prefs, get_data_image, get_data_plot, get_data_plot_prefs, get_dep, get_dims, get_error, get_exposure, get_grouping, get_indep, get_quality, get_rmf, get_specresp, get_staterror, get_syserror
filtering
get_filter
fitting
calc_stat_info, get_stat_info
info
get_default_id, list_stats
methods
get_draws, get_iter_method_name, get_iter_method_opt, get_method, get_method_name, get_method_opt
modeling
get_model, get_model_component, get_model_component_image, get_model_component_plot, get_model_plot, get_num_par, get_num_par_frozen, get_num_par_thawed, get_order_plot, get_par, get_pileup_model, get_response, get_source, get_source_component_image, get_source_component_plot, get_source_contour, get_source_image, get_source_plot, image_source
plotting
get_split_plot
psfs
get_psf, get_psf_contour, get_psf_image, get_psf_plot
statistics
get_chisqr_plot, get_delchi_plot, get_prior, get_sampler, get_stat, get_stat_name
utilities
get_analysis, get_rate
visualization
image_getregion