Plotter

`plot_predictive_coverage(solver, distribution='posterior', x_lim=None, y_lim=None, figsize=(12, 6), plot_background=False, plot_models=True, plot_components=True, legend=True, n_samples=100, min_counts=None, grouping=None, residual_kind='pearson')`

Plot posterior predictive spectra with residuals.

The lower panel displays residuals between the observed data \(D\) and the sampled model predictions \(M_i\). Three formulae are available, selected via the residual_kind parameter:

Pearson ("pearson", default) — per-sample Poisson normalisation, well defined for both prior and posterior predictive checks:

\[ r_i = \frac{D - M_i}{\sqrt{M_i}} \]

Sigma ("sigma") — normalised by the 68 % ensemble spread; can be misleading when the prior is broad:

\[ r = \frac{M - D}{P_{84} - P_{16}} \]

Raw ("raw") — un-normalised residuals in data units (counts / keV / s):

\[ r_i = \frac{D - M_i}{\Delta E} \]

Parameters:

Name	Type	Description	Default
`solver`		Solver instance exposing `distributions` and `simulate`.	required
`distribution`	`str`	Name of the distribution to sample from, looked up in `solver.distributions`. Common values are `"prior"` and `"posterior"`. Defaults to `"posterior"`.	`'posterior'`
`x_lim`	`tuple[float, float]`	Energy bounds in keV for the upper panel x-axis.	`None`
`y_lim`	`tuple[float, float]`	Flux limits for the upper panel y-axis.	`None`
`figsize`	`tuple[float, float]`	Matplotlib figure size in inches. Defaults to `(12, 6)`.	`(12, 6)`
`plot_background`	`bool`	Reserved for background overlays. This currently has no effect unless the simulated payload contains a `background` entry.	`False`
`plot_models`	`bool`	If `True`, draw one predictive band per source model (in addition to the total model).	`True`
`plot_components`	`bool`	If `True`, draw additive-component predictive bands for each source model.	`True`
`legend`	`bool`	Whether to display the legend on the spectrum panel. Defaults to `True`.	`True`
`n_samples`	`int`	Number of parameter draws used to build the predictive bands. Defaults to `100`.	`100`
`min_counts`	`int`	If set, adjacent bins are merged until every grouped bin contains at least min_counts observed counts. The same grouping is applied to all plotted quantities (observed spectrum, models, components, and residuals). `None` disables adaptive rebinning. Defaults to `None`. Mutually exclusive with grouping.	`None`
`grouping`	`int`	If set, every grouping adjacent bins are merged into one (the last group may contain fewer bins). Mutually exclusive with min_counts. Defaults to `None`.	`None`
`residual_kind`	`str`	Formula used for the residual panel. One of `"pearson"`, `"sigma"`, or `"raw"` (see above). Defaults to `"pearson"`.	`'pearson'`

Returns:

Type	Description
	matplotlib.figure.Figure: Figure containing spectrum and residual panels.