sample_flux

Synopsis

Return the flux distribution of a model.

Syntax

sample_flux(modelcomponent=None, lo=None, hi=None, id=None, num=1,
scales=None, correlated=False, numcores=None, bkg_id=None, Xrays=True,
confidence=68)

Description

For each iteration, draw the parameter values of the model from a normal distribution, filter out samples that lie outside the soft limits of the parameters, evaluate the model, and sum the model over the given range (the flux). Return the parameter values used, together with the median, upper, and lower quantiles of the flux distribution.

Examples

Example 1

Estimate the flux distribution for the "src" component using the default data set. The parameters are assumed to be uncorrelated.

>>> set_source(xsphabs.gal * xsapec.src)
>>> fit()
>>> fflux, cflux, vals = sample_flux(src, 0.5, 2, num=1000)
original model flux = 2.88993e-14, + 1.92575e-15, - 1.81963e-15
model component flux = 7.96865e-14, + 4.65144e-15, - 4.41222e-15
>>> f0, fhi, flo = cflux
>>> print("Flux: {:.2e} {:+.2e} {:+.2e}".format(f0, fhi-f0, flo-f0))
Flux: 7.97e-14 +4.65e-15 -4.41e-15

Example 2

This time the parameters are assumed to be correlated, using the covariance matrix for the fit:

>>> ans = sample_flux(src, 0.5, 2, num=1000, correlated=True)

Example 3

Explicitly send in the parameter widths (sigma values), using the estimates generated by `covar` :

>>> covar()
>>> errs = get_covar_results().parmaxes
>>> ans = sample_flux(correlated=False, scales=errs, num=500)

Example 4

Explicitly send in a covariance matrix:

>>> cmatrix = get_covar_results().extra_output
>>> ans = sample_flux(correlated=True, scales=cmatrix, num=500)

Example 5

Run sample_flux after changing the logging level, so that the screen output from sample_flux is not displayed. We use the SherpaVerbosity function from `sherpa.utils.logging` to only change the logging level while running sample_flux:

>>> from sherpa.utils.logging import SherpaVerbosity
>>> with SherpaVerbosity('WARN'):
...     ans = sample_flux(num=1000, lo=0.5, hi=7)

PARAMETERS

The parameters for this function are:

Parameter	Type information	Definition
modelcomponent	optional	The model to use. It can be a single component or a combination. If not given, then the full source expression for the data set is used.
lo	number, optional	The lower limit to use when summing up the signal. If not given then the lower value of the data grid is used.
hi	optional	The upper limit to use when summing up the signal. If not given then the upper value of the data grid is used.
id	int, str, or None, optional	The identifier of the data set to use. The default value ( none ) means that the default identifier, as returned by `get_default_id` , is used.
num	int, optional	The number of samples to create. The default is 1.
scales	array, optional	The scales used to define the normal distributions for the parameters. The form depends on the `correlated` parameter: when True , the array should be a symmetric positive semi-definite (N, N) array, otherwise a 1D array of length N, where N is the number of free parameters.
correlated	bool, optional	If True (the default is False ) then `scales` is the full covariance matrix, otherwise it is just a 1D array containing the variances of the parameters (the diagonal elements of the covariance matrix).
numcores	optional	The number of CPU cores to use. The default is to use all the cores on the machine.
bkg_id	int, str, or None, optional	The identifier of the background component to use. This should only be set when the line to be measured is in the background model.
Xrays	bool, optional	When True (the default), assume that the model has units of photon/cm^2/s, and use `calc_energy_flux` to convert to erg/cm^2/s. This should not be changed from the default value.
confidence	number, optional	The confidence level for the upper and lower values, as a percentage (0 to 100). The default is 68, so as to return the one-sigma range.

Return value

The return value from this function is:

The fullflux and cptflux arrays contain the results for the full source model and the flux of the `modelcomponent` argument (they can be the same). They have three elements and give the median value, the value containing 100 - confidence/2 of the data, and the fraction containing confidence/2 of the flux distribution. For the default confidence argument of 68 this means the last two give the one-sigma upper and lower bounds. The vals array has a shape of (num+1, n+3) , where n is the number of free parameters and num is the `num` parameter. The rows of this array contain the flux value for the iteration (for the full source model), the parameter values, a flag indicating whether any parameter in that row was clipped (and so was excluded from the flux calculation), and the statistic value for this set of parameters.

Notes

Setting the Xrays parameter to False is currently unsupported.

The summary output displayed by this routine - giving the median and confidence ranges - is controlled by the standard Sherpa logging instance, and can be hidden by changing the logging to a level greater than "INFO" (e.g. with `sherpa.utils.logging.SherpaVerbosity` ).

This routine can not be used if you have used set_full_model: the calc_energy_flux routine should be used instead.

Changes in CIAO

Changed in CIAO 4.16

The random number generation is now controlled by the `set_rng` routine.

Changed in CIAO 4.14

The `id` parameter is now used if set (previously the default dataset was always used). The screen output is now controlled by the Sherpa logging setup. The flux calculation no longer excludes samples at the parameter soft limits, as this could cause an over-estimation of the flux when a parameter is only an upper limit. The statistic value is now returned for each row, even those that were excluded from the flux calculation. The last-but-one column of the returned `vals` array now records the rows that were excluded from the flux calculation.

Bugs

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