get_photon_flux_hist

sherpa.astro.ui.get_photon_flux_hist(lo=None, hi=None, id: IdType | None = None, num=7500, bins=75, correlated: bool = False, numcores: int | None = None, bkg_id: IdType | None = None, scales=None, model=None, otherids: IdTypes = (), recalc: bool = True, clip='hard', copy: bool = True)

Return the data displayed by plot_photon_flux.

The get_photon_flux_hist() function calculates a histogram of simulated photon flux values representing the photon flux probability distribution for a model component, accounting for the errors on the model parameters.

Changed in version 4.19.0: The plot object is now copied by default. To get the previous behaviour set the copy attribute to False.

Changed in version 4.12.2: The scales parameter is no longer ignored when set and the model and otherids parameters have been added.

Parameters:

lonumber, optional

The lower limit to use when summing up the signal. If not given then the lower value of the data grid is used.

hioptional

The upper limit to use when summing up the signal. If not given then the upper value of the data grid is used.

idint, str, or None, optional

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.

numint, optional

The number of samples to create. The default is 7500.

binsint, optional

The number of bins to use for the histogram.

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

numcoresoptional

The number of CPU cores to use. The default is to use all the cores on the machine.

bkg_idint, str, or None, 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.

scalesarray, optional

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.

modelModel, optional

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.

otheridssequence of integer and str ids, optional

The list of other datasets that should be included when calculating the errors to draw values from.

recalcbool, optional

If True, the default, then re-calculate the values rather than use the values from the last time the function was run.

clip{‘hard’, ‘soft’, ‘none’}, optional

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.

copybool, optional

Is the plot object copied before being returned? If so then the plot attributes will not be changed by multiple calls to this routine.

Returns:

hista sherpa.astro.plot.PhotonFluxHistogram instance

An object representing the data used to create the plot by plot_photon_flux.

See also

get_energy_flux_hist, plot_energy_flux, plot_photon_flux

sample_energy_flux, sample_flux, sample_photon_flux

Examples

Get the photon flux distribution for the range 0.5 to 7 for the default data set:

>>> phist = get_photon_flux_hist(0.5, 7, num=1000)
>>> print(phist)

Compare the 0.5 to 2 photon flux distribution from the “core” data set to the values from the “jet” data set:

>>> phist1 = get_photon_flux_hist(0.5, 2, id='jet', num=1000)
>>> phist2 = get_photon_flux_hist(0.5, 2, id='core', num=1000)

Compare the flux distribution for the full source expression (aflux) to that for just the pl component (uflux); this can be useful to calculate the unabsorbed flux distribution if the full source model contains an absorption component:

>>> aflux = get_photon_flux_hist(0.5, 2, num=1000, bins=20)
>>> uflux = get_photon_flux_hist(0.5, 2, model=pl, num=1000, bins=20)

When there are multiple datasets loaded, get_photon_flux_hist uses all datasets to evaluate the errors when the id parameter is left at its default value of None. The otherids parameter is used, along with id, to specify exactly what datasets are used:

>>> x = get_photon_flux_hist(2, 10, num=1000, bins=20, model=src)
>>> y = get_photon_flux_hist(2, 10, num=1000, bins=20, model=src,
...                          id=1, otherids=(2, 3, 4))