Last modified: December 2020

URL: https://cxc.cfa.harvard.edu/sherpa/ahelp/sample_flux.html
AHELP for CIAO 4.13 Sherpa v1

sample_flux

Context: utilities

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)

modelcomponent - optional
lo - number, optional
hi - optional
id - int or string, optional
num - int, optional
scales - array, optional
correlated - bool, optional
numcores - optional
bkg_id - int or string, optional
Xrays - bool, optional
confidence - number, optional

Description

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.


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()
>>> 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

Example 2

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)

Example 3

Explicitly send in a covariance matrix:

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

PARAMETERS

The parameters for this function are:

Parameter Definition
modelcomponent 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 The lower limit to use when summing up the signal. If not given then the lower value of the data grid is used.
hi The upper limit to use when summing up the signal. If not given then the upper value of the data grid is used.
id 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 The number of samples to create. The default is 1.
scales 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 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 The number of CPU cores to use. The default is to use all the cores on the machine.
bkg_id 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 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 The confidence level for the upper and lower quartiles, as a percentage. 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, 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.


Bugs

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

See Also

plotting
get_energy_flux_hist, get_photon_flux_hist, plot_energy_flux, plot_photon_flux
utilities
sample_energy_flux, sample_photon_flux