plot_pvalue

sherpa.astro.ui.plot_pvalue(null_model, alt_model, conv_model=None, id: IdType = 1, otherids: IdTypes = (), num: int = 500, bins: int = 25, numcores: int | None = None, replot: bool = False, overplot: bool = False, clearwindow: bool = True, **kwargs) → None

Compute and plot a histogram of likelihood ratios by simulating data.

Compare the likelihood of the null model to an alternative model by running a number of simulations to calibrate the likelihood ratio test statistics. The distribution of the simulated likelihood ratios is plotted and compared to the likelihoods of the two models fit to the observed data. The fit statistic must be set to a likelihood-based method, such as “cash” or “cstat”. Screen output is created as well as the plot; these values can be retrieved with get_pvalue_results.

The algorithm is based on the description in Sec.5.2 in “Statistics, Handle with Care: Detecting Multiple Model Components with the Likelihood Ratio Test” by Protassov et al., 2002, The Astrophysical Journal, 571, 545; <doi:10.1086/339856>

Changed in version 4.17.0: The “wstat” statistic can now be used with this routine.

Parameters:
null_model

The model expression for the null hypothesis.

alt_model

The model expression for the alternative hypothesis.

conv_modeloptional

An expression used to modify the model so that it can be compared to the data (e.g. a PSF or PHA response).

idint or str, optional

The data set that provides the data. The default is 1.

otheridssequence of int or str, optional

Other data sets to use in the calculation.

numint, optional

The number of simulations to run. The default is 500.

binsint, optional

The number of bins to use to create the histogram. The default is 25.

numcoresoptional

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

replotbool, optional

Set to True to use the values calculated by the last call to plot_pvalue. The default is False.

overplotbool, optional

If True then add the data to an existing plot, otherwise create a new plot. The default is False.

clearwindowbool, optional

Should the existing plot area be cleared before creating this new plot (e.g. for multi-panel plots)?

Raises:
TypeError

An invalid statistic.

See also

get_pvalue_plot

Return the data used by plot_pvalue.

get_pvalue_results

Return the data calculated by the last plot_pvalue call.

Notes

Each simulation involves creating a data set using the observed data simulated with Poisson noise.

For the likelihood ratio test to be valid, the following conditions must hold:

  1. The null model is nested within the alternative model.

  2. The extra parameters of the alternative model have Gaussian (normal) distributions that are not truncated by the boundaries of the parameter spaces.

Examples

Use the likelihood ratio to see if the data in data set 1 has a statistically-significant gaussian component:

>>> create_model_component('powlaw1d', 'pl')
>>> create_model_component('gauss1d', 'gline')
>>> plot_pvalue(pl, pl + gline)

Use 1000 simulations and use the data from data sets ‘core’, ‘jet1’, and ‘jet2’:

>>> mdl1 = pl
>>> mdl2 = pl + gline
>>> plot_pvalue(mdl1, mdl2, id='core', otherids=('jet1', 'jet2'),
...             num=1000)

Apply a convolution to the models before fitting:

>>> rsp = get_psf()
>>> plot_pvalue(mdl1, mdl2, conv_model=rsp)