sample_flux

sherpa.astro.ui.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)

Return the flux distribution of a model.

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.

Changed in version 4.16.0: The random number generation is now controlled by the set_rng routine.

Changed in version 4.13.1: 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.

Parameters:
  • 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 or string, 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 or string, 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.

Returns:

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.

Return type:

(fullflux, cptflux, vals)

See also

calc_photon_flux

Integrate the unconvolved source model over a pass band.

calc_energy_flux

Integrate the unconvolved source model over a pass band.

covar

Estimate the confidence intervals using the confidence method.

plot_energy_flux

Display the energy flux distribution.

plot_photon_flux

Display the photon flux distribution.

sample_energy_flux

Return the energy flux distribution of a model.

sample_photon_flux

Return the photon flux distribution of a model.

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.

Examples

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

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)

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)

Explicitly send in a covariance matrix:

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

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 runnng sample_flux:

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