Last modified: December 2023

AHELP for CIAO 4.16 Sherpa


Context: plotting


Display the energy flux distribution.


plot_energy_flux(lo=None, hi=None, id=None, num=7500, bins=75,
correlated=False, numcores=None, bkg_id=None, scales=None, model=None,
otherids=(), recalc=True, clip='hard', overplot=False,
clearwindow=True, **kwargs)

lo - number, optional
hi - optional
id - int or string, optional
num - int, optional
bins - int, optional
correlated - bool, optional
numcores - optional
bkg_id - int or string, optional
scales - array, optional
model - model, optional
otherids - sequence of integer and string ids, optional
recalc - bool, optional
clip - {'hard', 'soft', 'none'}, optional
overplot - bool, optional
clearwindow - bool, optional


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). Plot up the distribution of this flux. The units for the flux are as returned by `calc_energy_flux` . The `sample_energy_flux` and `get_energy_flux_hist` functions return the data used to create this plot.


Example 1

Plot the energy flux distribution for the range 0.5 to 7 for the default data set:

>>> plot_energy_flux(0.5, 7, num=1000)

Example 2

Overplot the 0.5 to 2 energy flux distribution from the "core" data set on top of the values from the "jet" data set:

>>> plot_energy_flux(0.5, 2, id="jet", num=1000)
>>> plot_energy_flux(0.5, 2, id="core", num=1000, overplot=True)

Example 3

Overplot the flux distribution for just the pl component (which must be part of the source expression) on top of the full model. If the full model was * then this will compare the unabsorbed to absorbed flux distributions:

>>> plot_energy_flux(0.5, 2, num=1000, bins=20)
>>> plot_energy_flux(0.5, 2, model=pl, num=1000, bins=20)

Example 4

If you have multiple datasets loaded, each with a model, then all datasets will be used to calculate the errors when the id parameter is not set. A single dataset can be used by specifying a dataset (in this example the overplot is just with dataset 1):

>>> mdl = * xsapec.src
>>> set_source(1, mdl)
>>> set_source(2, mdl)
>>> plot_energy_flux(0.5, 2, model=src num=1000, bins=20)
>>> plot_energy_flux(0.5, 2, model=src num=1000, bins=20,
...                  id=1, overplot=True)

Example 5

If you have multiple datasets then you can use the otherids argument to specify exactly what set of data is used:

>>> plot_energy_flux(0.5, 2, model=src num=1000, bins=20,
...                  id=1, otherids=(2, 3, 4))


The parameters for this function are:

Parameter Definition
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. If `None` , the default value, then all datasets with associated models are used to calculate the errors and the model evaluation is done using the default dataset.
num The number of samples to create. The default is 7500.
bins The number of bins to use for the histogram.
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.
scales The scales used to define the normal distributions for the parameters. The size and shape of the array depends on the number of free parameters in the fit (n) and the value of the `correlated` parameter. When the parameter is `True` , scales must be given the covariance matrix for the free parameters (a n by n matrix that matches the parameter ordering used by Sherpa). For un-correlated parameters the covariance matrix can be used, or a one-dimensional array of n elements can be used, giving the width (specified as the sigma value of a normal distribution) for each parameter (e.g. the square root of the diagonal elements of the covariance matrix). If the scales parameter is not given then the covariance matrix is evaluated for the current model and best-fit parameters.
model The model to integrate. If left as `None` then the source model for the dataset will be used. This can be used to calculate the unabsorbed flux, as shown in the examples. The model must be part of the source expression.
otherids The list of other datasets that should be included when calculating the errors to draw values from.
recalc If True , the default, then re-calculate the values rather than use the values from the last time the function was run.
clip What clipping strategy should be applied to the sampled parameters. The default ('hard') is to fix values at their hard limits if they exceed them. A value of 'soft' uses the soft limits instead, and 'none' applies no clipping.
overplot If True then add the data to an existing plot, otherwise create a new plot. The default is False .
clearwindow Should the existing plot area be cleared before creating this new plot (e.g. for multi-panel plots)?

Changes in CIAO

Changed in CIAO 4.13

The scales parameter is no longer ignored when set and the model and otherids parameters have been added. The clip argument has been added.


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

See Also

get_data_prof, get_data_prof_prefs, get_delchi_prof, get_delchi_prof_prefs, get_fit_prof, get_model_prof, get_model_prof_prefs, get_resid_prof, get_resid_prof_prefs, get_source_prof, get_source_prof_prefs, plot_chart_spectrum, plot_marx_spectrum, prof_data, prof_delchi, prof_fit, prof_fit_delchi, prof_fit_resid, prof_model, prof_resid, prof_source
get_arf_plot, get_bkg_chisqr_plot, get_bkg_delchi_plot, get_bkg_fit_plot, get_bkg_model_plot, get_bkg_plot, get_bkg_ratio_plot, get_bkg_resid_plot, get_bkg_source_plot
normal_sample, t_sample, uniform_sample
get_cdf_plot, get_energy_flux_hist, get_pdf_plot, get_photon_flux_hist, get_pvalue_plot, get_pvalue_results, get_split_plot, plot, plot_arf, plot_bkg, plot_bkg_chisqr, plot_bkg_delchi, plot_bkg_fit, plot_bkg_fit_delchi, plot_bkg_fit_resid, plot_bkg_model, plot_bkg_ratio, plot_bkg_resid, plot_bkg_source, plot_cdf, plot_chisqr, plot_data, plot_delchi, plot_fit, plot_fit_delchi, plot_fit_resid, plot_model, plot_model_component, plot_order, plot_pdf, plot_photon_flux, plot_pvalue, plot_ratio, plot_resid, plot_scatter, plot_source, plot_source_component, plot_trace, set_xlinear, set_xlog, set_ylinear, set_ylog
get_chisqr_plot, get_delchi_plot
sample_energy_flux, sample_flux, sample_photon_flux