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.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 returnedvals
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 byget_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: whenTrue
, 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 isFalse
) thenscales
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 usecalc_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)
, whereN
is the number of free parameters and num is thenum
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)