gcfit.analysis.MCMCRun

class gcfit.analysis.MCMCRun(filename, observations=None, group='mcmc', name=None)

Analysis and visualization of an MCMC cluster fitting run.

Provides a number of flexible plotting, output and summary methods useful for the analysis of both the procedure and results of an MCMC run, based on the output file generated by the fitting (emcee.HDFBackend).

Parameters:

filenamepathlib.Path or str

Path to the run output HDF5 file.

observationsgcfit.Observations or None, optional

The Observations instance corresponding to this cluster. If None (default), an educated guess will be made on the source location (i.e. the restrict_to argument) and the observations will be created based on the cluster name stored in the output.

groupstr, optional

Name of the root group in the HDF5 file. Defaults to “mcmc”, the most likely name used by gcfit.MCMC_fit.

namestr, optional

Custom name for this run.

Methods

__init__(filename[, observations, group, name])
add_residuals(ax, y1, y2, e1, e2[, clrs, ...])	Append an extra axis to ax for plotting residuals.
get_CImodel([N, Nprocesses, load])	Return a CIModelVisualizer instance corresponding to this run.
get_model([method])	Return a single ModelVisualizer instance corresponding to this run.
plot_acceptance([fig, ax])	Plot the sampler acceptance rate over time.
plot_chains([fig, params])	Plot trace plot of the chains of walkers for all parameters.
plot_indiv([fig])	Plot the evolution of each individual likelihood component over time.
plot_marginals([fig])	Plot a "corner plot" showcasing the relationships between parameters.
plot_params([fig, params, posterior_color, ...])	Plot a diagnostic figure of the distributions of parameter samples.
plot_posterior(param[, fig, ax, chain, ...])	Plot a smoothed posterior distribution of a single parameter.
plot_probability([fig, ax])	Plot the posterior probability over time.
print_summary([out, content])	Write a short summary of the run results and metadata.
reset_mask()	Reset the mask.
slice_on_param(param, lower_lim, upper_lim)	Set mask based on the value of a certain parameter.

Attributes

chains
cmap
cut_incomplete
iterations	Slice or mask defining the iterations to use in all analysis.
mask	Mask out certain samples, removing them from all analysis.
results
state	Return a flag representing where in the fitting this run reached.
walkers	Slice or mask defining the walkers to use in all analysis.

add_residuals(ax, y1, y2, e1, e2, clrs=None, res_ax=None, loc='bottom', size='15%', pad=0.1)

Append an extra axis to ax for plotting residuals.

Automatically appends a new axis to the the bottom of the given ax, and plots the residuals between the two given quantities (and their errors) on it, as a percentage.

Parameters:

axmatplotlib.axes.Axes

An axes instance on which to plot this observational data.

y1, y2np.ndarray

Arrays of data values to plot the residual between. Residuals are of (y2 - y1) / y1.

e1, e2np.ndarray

Arrays of errors on each datapoint.

clrscolor, optional

Colour used for all datapoints, passed to errorbar and scatter.

res_axmatplotlib.axes.Axes, optional

Optionally provide an already created axis to plot residuals on. This is useful for overplotting multiple residuals (i.e. for multiple datasets).

loc{“left”, “right”, “bottom”, “top”}, optional

Where the new axes is positioned relative to the main axes.

sizestr or float, optional

The size of the appended residuals axes, with respect to the primary axes. See mpl_toolkits.axes_grid1.axes_divider.AxesDivider.append_axes for more information. Defaults to “15%”.

padfloat, optional

Padding between the axes. Defaults to 0.1.

Returns:

matplotlib.axes.Axes

The created axes instance containing the residuals plot.

get_CImodel(N=100, Nprocesses=1, load=False)

Return a CIModelVisualizer instance corresponding to this run.

The visualizer is initialized through the CIModelVisualizer.from_chain classmethod, with the chain from this run and using N samples, if load is False, otherwise will attempt to use the CIModelVisualizer.load classmethod, assuming a CI model has already been created and saved to this same file, under the model group.

Parameters:

Nint, optional

The number of samples to use in computing the confidence intervals.

Nprocessesint, optional

The number of processes to use in a multiprocessing.Pool passed to the CI model initializer. Defaults to only 1 cpu.

loadbool, optional

If True, will attempt to load a CI model, rather than creating a new one.

Returns:

CIModelVisualizer

The created model visualization (with confidence intervals) object.

get_model(method='median')

Return a single ModelVisualizer instance corresponding to this run.

The visualizer is initialized through the ModelVisualizer.from_chain classmethod, with the chain from this run and the method given here.

Parameters:

method{‘median’, ‘mean’, ‘final’}, optional

The method used to compute a single theta set from the chain. Defaults to ‘median’.

Returns:

ModelVisualizer

The created model visualization object.

property iterations

Slice or mask defining the iterations to use in all analysis.

property mask

Mask out certain samples, removing them from all analysis.

plot_acceptance(fig=None, ax=None)

Plot the sampler acceptance rate over time.

Plots the “acceptance rate” of the MCMC sampler as a function of iterations. All walkers are shown, in different colours.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _RunAnalysis._setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this rate. Should be a part of the given fig.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_chains(fig=None, params=None)

Plot trace plot of the chains of walkers for all parameters.

Plots an Nparam-panel figure following the evolution of the different walkers throughout all iterations. All walkers are shown, per parameter, in different colours.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place all axes on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _RunAnalysis._setup_multi_artist for more details.

paramsNone or list of str, optional

The parameters to show on this figure. If None (default) all parameters (including fixed params) will be shown.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_indiv(fig=None)

Plot the evolution of each individual likelihood component over time.

Plots a multipanel figure tracing the value of the log-likelihood of each likelihood component (i.e. based on self.obs.valid_likelihoods, not each dataset type) individually. All walkers are shown, per component, in different colours.

Individual likelihoods must have been stored as “blobs” during the fit.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place all axes on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _RunAnalysis._setup_multi_artist for more details.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_marginals(fig=None, **corner_kw)

Plot a “corner plot” showcasing the relationships between parameters.

Plots a Nparam-Nparam lower-triangular “corner” marginal plot showing the projections of all sampled parameter values, using the corner.py package.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place all axes on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _RunAnalysis._setup_multi_artist for more details.

**corner_kwdict

All other arguments are passed to corner.corner.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_params(fig=None, params=None, *, posterior_color='tab:blue', posterior_border=True, ylims=None, truths=None, **kw)

Plot a diagnostic figure of the distributions of parameter samples.

Plots an Nparam-panel figure showcasing the parameter values of all samples, over the iteration domain, as well as a KDE-based smoothed posterior distribution for each parameter.

This class is mostly provided to match the nested sampling version, where it is much more instructive. This may be very expensive for large MCMC runs, and plot_chains may be more instructive.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place all axes on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _RunAnalysis._setup_multi_artist for more details.

paramsNone or list of str, optional

The parameters to show on this figure. If None (default) all parameters (including fixed params) will be shown.

posterior_colorcolor, optional

The colour of the smoothed posterior distributions.

posterior_borderbool, optional

If False, will remove the axis frame around the smooth posterior distribution to the right of each panel.

ylimslist[Nparam] of 2-tuples, optional

Used to set the upper and lower y axis-limits on each parameter.

truthsnp.ndarray[Nparam] or np.ndarray[Nparam, 3], optional

Optionally indicate the “true” values as horizontal lines on the posterior frames. If [Nparam, 3], the values in each row will be taken as the median, lower limit and upper limit.

**kwdict

All other arguments are passed to ax.scatter.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_posterior(param, fig=None, ax=None, chain=None, flipped=True, truth=None, truth_ci=None, *args, **kwargs)

Plot a smoothed posterior distribution of a single parameter.

Plots a gaussian-KDE smoothed posterior probability distribution of a given parameter. Designed mainly to be used within the plot_params method, but can be used on its own.

Parameters:

paramstr

Name of the parameter to plot.

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _RunAnalysis._setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this posterior. Should be a part of the given fig.

chainnp.ndarray, optional

Optionally supply a (flattened) array of samples to create the posterior from. By default, will load the full chain using self._get_chains.

flippedbool, optional

If True (default) the posterior will be flipped on it’s side, attached to the left-axis.

truthfloat, optional

Optionally indicate the “true” value as horizontal lines on the posterior.

truth_ci2-tuple of float, optional

Optionally shade between the lower and upper limits of the “truth” values, using plt.axhspan.

*args, **kwargs

All other arguments are passed to the ax.fill_between function.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

plot_probability(fig=None, ax=None)

Plot the posterior probability over time.

Plots the total (sum of all components) logged posterior probability of the MCMC sampler as a function of iterations. All walkers are shown, in different colours.

Parameters:

figNone or matplotlib.figure.Figure, optional

Figure to place the ax on. If None (default), a new figure will be created, otherwise the given figure should be empty, or already have the correct number of axes. See _RunAnalysis._setup_artist for more details.

axNone or matplotlib.axes.Axes, optional

An axes instance on which to plot this probability. Should be a part of the given fig.

Returns:

matplotlib.figure.Figure

The corresponding figure, containing all axes and plot artists.

print_summary(out=None, content='all')

Write a short summary of the run results and metadata.

Write out (to a file or stdout) a short summary of the final median and 1σ parameter values, as well as some metadata surrounding the fitting run setup, such as fixed parameters.

Parameters:

outNone or file-like object, str, or pathlib.Path, optional

The file to write out the summary to. If None (default) will be printed to stdout.

content{‘all’, ‘results’, ‘metadata’}

Which parts of the summary to write. If “results”, will print only the parameter values. If “metadata”, will print only the run metadata. If “all” (default), prints both.

reset_mask()

Reset the mask.

slice_on_param(param, lower_lim, upper_lim)

Set mask based on the value of a certain parameter. Already present masks will be combined. If that’s not desired, masks should be reset (self.reset_mask()) first.

property state

Return a flag representing where in the fitting this run reached.

property walkers

Slice or mask defining the walkers to use in all analysis.