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, 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.

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 guven 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.
  • confidence (number, optional) – The confidence level for the upper and lower quartiles, as a percentage. 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, upper quartile, and lower quartile values of the flux distribution. The vals array has a shape of (num+1, N+2), 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, and then the statistic value for this set of parameters.
Return type:

(fullflux, cptflux, vals)

See also

calc_photon_flux()
Integrate the source model over a pass band.
calc_energy_flux()
Integrate the 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.

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()
>>> covar()
>>> (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 created by the covar call:

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

Explicitly send in a covariance matrix:

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