Chain Consumer API

ChainConsumer has a number of different methods that can be access. In the latest version of ChainConsumer, the increasing number of methods has had them put into smaller classes within ChainConsumer.

Basic Methods

The methods found in the ChainConsumer class itself all relate to add, manipulating, and configuring the chains fed in.

Plotter Class

The plotter class, accessible via chainConsumer.plotter contains the methods used for generating plots.

Analysis Class

The plotter class, accessible via chainConsumer.analysis contains the methods used for getting data or LaTeX analysis of the chains fed in.

Diagnostic Class

The plotter class, accessible via chainConsumer.diagnostic contains the methods used for checking chain convergence

Model Comparison Class

The plotter class, accessible via chainConsumer.comparison contains the methods used for comparing the chains from various models.

  • chainconsumer.comparisons.Comparison.comparison.aic() - Return the AICc values for all chains.

  • chainconsumer.comparisons.Comparison.comparison.bic() - Return the BIC values for all chains.

  • chainconsumer.comparisons.Comparison.comparison.dic() - Return the DIC values for all chains.

  • chainconsumer.comparisons.Comparison.comparison.comparison_table() - Return a LaTeX table comparing models as per the above methods.

The full documentation can be found below.

Full Documentation

class chainconsumer.ChainConsumer

A class for consuming chains produced by an MCMC walk. Or grid searches. To make plots, figures, tables, diagnostics, you name it.

add_chain(chain, parameters=None, name=None, weights=None, posterior=None, walkers=None, grid=False, num_eff_data_points=None, num_free_params=None, color=None, linewidth=None, linestyle=None, kde=None, shade=None, shade_alpha=None, power=None, marker_style=None, marker_size=None, marker_alpha=None, plot_contour=None, plot_point=None, show_as_1d_prior=None, statistics=None, cloud=None, shade_gradient=None, bar_shade=None, bins=None, smooth=None, color_params=None, plot_color_params=None, cmap=None, num_cloud=None, zorder=None, shift_params=None)

Add a chain to the consumer.

Parameters
  • chain (str|ndarray|dict|pandas.DataFrame) – The chain to load. Normally a numpy.ndarray. If a string is found, it interprets the string as a filename and attempts to load it in using pandas.read_csv. If a dict is passed in, it assumes the dict has keys of parameter names and values of an array of samples. Notice that using a dictionary puts the order of parameters in the output under the control of the python dict.keys() function. If you passed grid is set, you can pass in the parameter ranges in list form. If you pass a DataFrame, I will look for a “weight” and “posterior” column by default. If they are called something different, extract them and pass them directly into weights and posterior.

  • parameters (list[str], optional) – A list of parameter names, one for each column (dimension) in the chain. This parameter should remain None if a dictionary is given as chain, as the parameter names are taken from the dictionary keys.

  • name (str, optional) – The name of the chain. Used when plotting multiple chains at once.

  • weights (ndarray, optional) – If given, uses this array to weight the samples in chain

  • posterior (ndarray, optional) – If given, records the log posterior for each sample in the chain

  • walkers (int, optional) – How many walkers went into creating the chain. Each walker should contribute the same number of steps, and should appear in contiguous blocks in the final chain.

  • grid (boolean, optional) – Whether the input is a flattened chain from a grid search instead of a Monte-Carlo chains. Note that when this is set, walkers should not be set, and weights should be set to the posterior evaluation for the grid point. Be careful when using a coarse grid of setting a high smoothing value, as this may oversmooth the posterior surface and give unreasonably large parameter bounds.

  • num_eff_data_points (int|float, optional) – The number of effective (independent) data points used in the model fitting. Not required for plotting, but required if loading in multiple chains to perform model comparison.

  • num_free_params (int, optional) – The number of degrees of freedom in your model. Not required for plotting, but required if loading in multiple chains to perform model comparison.

  • color (str(hex), optional) – Provide a colour for the chain. Can be used instead of calling configure for convenience.

  • linewidth (float, optional) – Provide a line width to plot the contours. Can be used instead of calling configure for convenience.

  • linestyle (str, optional) – Provide a line style to plot the contour. Can be used instead of calling configure for convenience.

  • kde (bool|float, optional) – Set the kde value for this specific chain. Can be used instead of calling configure for convenience.

  • shade (booloptional) – If set, overrides the default behaviour and plots filled contours or not. If a list of bools is passed, you can turn shading on or off for specific chains.

  • shade_alpha (float, optional) – Filled contour alpha value. Can be used instead of calling configure for convenience.

  • power (float, optional) – The power to raise the posterior surface to. Useful for inflating or deflating uncertainty for debugging.

  • marker_style (str|, optional) – The marker style to use when plotting points. Defaults to '.'

  • marker_size (numeric|, optional) – Size of markers, if plotted. Defaults to 20.

  • marker_alpha (numeric, optional) – The alpha values when plotting markers.

  • plot_contour (bool, optional) – Whether to plot the whole contour (as opposed to a point). Defaults to true for less than 25 concurrent chains.

  • plot_point (bool, optional) – Whether to plot a maximum likelihood point. Defaults to true for more then 24 chains.

  • show_as_1d_prior (bool, optional) – Showing as a 1D prior will show the 1D histograms, but won’t plot the 2D contours.

  • statistics (string, optional) – Which sort of statistics to use. Defaults to "max" for maximum likelihood statistics. Other available options are "mean", "cumulative", "max_symmetric", "max_closest" and "max_central". In the very, very rare case you want to enable different statistics for different chains, you can pass in a list of strings.

  • cloud (bool, optional) – If set, overrides the default behaviour and plots the cloud or not shade_gradient :

  • bar_shade (bool, optional) – If set to true, shades in confidence regions in under histogram. By default this happens if you less than 3 chains, but is disabled if you are comparing more chains. You can pass a list if you wish to shade some chains but not others.

  • bins (int|float, optional) – The number of bins to use. By default uses \(\frac{\sqrt{n}}{10}\), where \(n\) are the number of data points. Giving an integer will set the number of bins to the given value. Giving a float will scale the number of bins, such that giving bins=1.5 will result in using \(\frac{1.5\sqrt{n}}{10}\) bins. Note this parameter is most useful if kde=False is also passed, so you can actually see the bins and not a KDE. smooth :

  • color_params (str, optional) – The name of the parameter to use for the colour scatter. Defaults to none, for no colour. If set to ‘weights’, ‘log_weights’, or ‘posterior’ (without the quotes), and that is not a parameter in the chain, it will respectively use the weights, log weights, or posterior, to colour the points.

  • plot_color_params (bool, optional) – Whether or not the colour parameter should also be plotted as a posterior surface.

  • cmaps (str, optional) – The matplotlib colourmap to use in the colour_param. If you have multiple `color_param`s, you can specific a different cmap for each variable. By default ChainConsumer will cycle between several cmaps.

  • num_cloud (int, optional) – The number of scatter points to show when enabling cloud or setting one of the parameters to colour scatter. Defaults to 15k per chain.

  • zorder (int, optional) – The zorder to pass to matplotlib when plotting to determine visual order in the plot.

  • shift_params (dict|list, optional) – Shifts the parameters specify to the numeric values. Useful to shift contours to the same location to perform blinded uncertainty comparisons.

Returns

Itself, to allow chaining calls.

Return type

ChainConsumer

add_covariance(mean, covariance, parameters=None, name=None, **kwargs)

Generate samples as per mean and covariance supplied. Useful for Fisher matrix forecasts.

Parameters
  • mean (list|np.ndarray) – The an array of mean values.

  • covariance (list|np.ndarray) – The 2D array describing the covariance. Dimensions should agree with the mean input.

  • parameters (list[str], optional) – A list of parameter names, one for each column (dimension) in the mean array.

  • name (str, optional) – The name of the chain. Used when plotting multiple chains at once.

  • kwargs – Extra arguments about formatting - identical to what you would find in add_chain. linewidth, color, etc.

Returns

Itself, to allow chaining calls.

Return type

ChainConsumer

add_marker(location, parameters=None, name=None, color=None, marker_size=None, marker_style=None, marker_alpha=None)

Add a marker to the plot at the given location.

Parameters
  • location (list|np.ndarray) – The coordinates to place the marker

  • parameters (list[str], optional) – A list of parameter names, one for each column (dimension) in the mean array.

  • name (str, optional) – The name of the chain. Used when plotting multiple chains at once.

  • color (str(hex), optional) – Provide a colour for the chain. Can be used instead of calling configure for convenience.

  • marker_style (str|, optional) – The marker style to use when plotting points. Defaults to '.'

  • marker_size (numeric|, optional) – Size of markers, if plotted. Defaults to 20.

  • marker_alpha (numeric, optional) – The alpha values when plotting markers.

Returns

Itself, to allow chaining calls.

Return type

ChainConsumer

configure(statistics='max', max_ticks=5, plot_hists=True, flip=True, serif=True, sigma2d=False, sigmas=None, summary=None, bins=None, cmap=None, colors=None, linestyles=None, linewidths=None, kde=False, smooth=None, cloud=None, shade=None, shade_alpha=None, shade_gradient=None, bar_shade=None, num_cloud=None, color_params=None, plot_color_params=False, cmaps=None, plot_contour=None, plot_point=None, show_as_1d_prior=None, global_point=True, marker_style=None, marker_size=None, marker_alpha=None, usetex=True, diagonal_tick_labels=True, label_font_size=12, tick_font_size=10, spacing=None, contour_labels=None, contour_label_font_size=10, legend_kwargs=None, legend_location=None, legend_artists=None, legend_color_text=True, watermark_text_kwargs=None, summary_area=0.6827, zorder=None, stack=False)

Configure the general plotting parameters common across the bar and contour plots.

If you do not call this explicitly, the plot() method will invoke this method automatically.

Please ensure that you call this method after adding all the relevant data to the chain consumer, as the consume changes configuration values depending on the supplied data.

Parameters
  • statistics (string|list[str], optional) – Which sort of statistics to use. Defaults to "max" for maximum likelihood statistics. Other available options are "mean", "cumulative", "max_symmetric", "max_closest" and "max_central". In the very, very rare case you want to enable different statistics for different chains, you can pass in a list of strings.

  • max_ticks (int, optional) – The maximum number of ticks to use on the plots

  • plot_hists (bool, optional) – Whether to plot marginalised distributions or not

  • flip (bool, optional) – Set to false if, when plotting only two parameters, you do not want it to rotate the histogram so that it is horizontal.

  • sigma2d (bool, optional) – Defaults to False. When False, uses \(\sigma\) levels for 1D Gaussians - ie confidence levels of 68% and 95%. When True, uses the confidence levels for 2D Gaussians, where 1 and 2 \(\sigma\) represents 39% and 86% confidence levels respectively.

  • sigmas (np.array, optional) – The \(\sigma\) contour levels to plot. Defaults to [0, 1, 2, 3] for a single chain and [0, 1, 2] for multiple chains.

  • serif (bool, optional) – Whether to display ticks and labels with serif font.

  • summary (bool, optional) – If overridden, sets whether parameter summaries should be set as axis titles. Will not work if you have multiple chains

  • bins (int|float,list[int|float], optional) – The number of bins to use. By default uses \(\frac{\sqrt{n}}{10}\), where \(n\) are the number of data points. Giving an integer will set the number of bins to the given value. Giving a float will scale the number of bins, such that giving bins=1.5 will result in using \(\frac{1.5\sqrt{n}}{10}\) bins. Note this parameter is most useful if kde=False is also passed, so you can actually see the bins and not a KDE.

  • cmap (str, optional) – Set to the matplotlib colour map you want to use to overwrite the default colours. Note that this parameter overwrites colours. The cmaps parameters is different, and used when you ask for an extra dimension to be used to colour scatter points. See the online examples to see the difference.

  • colors (str(hex)|list[str(hex)], optional) – Provide a list of colours to use for each chain. If you provide more chains than colours, you will get the rainbow colour spectrum. If you only pass one colour, all chains are set to this colour. This probably won’t look good.

  • linestyles (str|list[str], optional) – Provide a list of line styles to plot the contours and marginalised distributions with. By default, this will become a list of solid lines. If a string is passed instead of a list, this style is used for all chains.

  • linewidths (float|list[float], optional) – Provide a list of line widths to plot the contours and marginalised distributions with. By default, this is a width of 1. If a float is passed instead of a list, this width is used for all chains.

  • kde (bool|float|list[bool|float], optional) – Whether to use a Gaussian KDE to smooth marginalised posteriors. If false, uses bins and linear interpolation, so ensure you have plenty of samples if your distribution is highly non-gaussian. Due to the slowness of performing a KDE on all data, it is often useful to disable this before producing final plots. If float, scales the width of the KDE bandpass manually.

  • smooth (int|list[int], optional) – Defaults to 3. How much to smooth the marginalised distributions using a gaussian filter. If kde is set to true, this parameter is ignored. Setting it to either 0, False disables smoothing. For grid data, smoothing is set to 0 by default, not 3.

  • cloud (bool|list[bool], optional) – If set, overrides the default behaviour and plots the cloud or not

  • shade (bool|list[bool] optional) – If set, overrides the default behaviour and plots filled contours or not. If a list of bools is passed, you can turn shading on or off for specific chains.

  • shade_alpha (float|list[float], optional) – Filled contour alpha value override. Default is 1.0. If a list is passed, you can set the shade opacity for specific chains.

  • shade_gradient (float|list[float], optional) – How much to vary colours in different contour levels.

  • bar_shade (bool|list[bool], optional) – If set to true, shades in confidence regions in under histogram. By default this happens if you less than 3 chains, but is disabled if you are comparing more chains. You can pass a list if you wish to shade some chains but not others.

  • num_cloud (int|list[int], optional) – The number of scatter points to show when enabling cloud or setting one of the parameters to colour scatter. Defaults to 15k per chain.

  • color_params (str|list[str], optional) – The name of the parameter to use for the colour scatter. Defaults to none, for no colour. If set to ‘weights’, ‘log_weights’, or ‘posterior’ (without the quotes), and that is not a parameter in the chain, it will respectively use the weights, log weights, or posterior, to colour the points.

  • plot_color_params (bool|list[bool], optional) – Whether or not the colour parameter should also be plotted as a posterior surface.

  • cmaps (str|list[str], optional) – The matplotlib colourmap to use in the colour_param. If you have multiple `color_param`s, you can specific a different cmap for each variable. By default ChainConsumer will cycle between several cmaps.

  • plot_contour (bool|list[bool], optional) – Whether to plot the whole contour (as opposed to a point). Defaults to true for less than 25 concurrent chains.

  • plot_point (bool|list[bool], optional) – Whether to plot a maximum likelihood point. Defaults to true for more then 24 chains.

  • show_as_1d_prior (bool|list[bool], optional) – Showing as a 1D prior will show the 1D histograms, but won’t plot the 2D contours.

  • global_point (bool, optional) –

    Whether the point which gets plotted is the global posterior maximum, or the marginalised 2D posterior maximum. Note that when you use marginalised 2D maximums for the points, you do not

    get the 1D histograms. Defaults to True, for a global maximum value.

  • marker_style (str|list[str], optional) – The marker style to use when plotting points. Defaults to '.'

  • marker_size (numeric|list[numeric], optional) – Size of markers, if plotted. Defaults to 20.

  • marker_alpha (numeric|list[numeric], optional) – The alpha values when plotting markers.

  • usetex (bool, optional) – Whether or not to parse text as LaTeX in plots.

  • diagonal_tick_labels (bool, optional) – Whether to display tick labels on a 45 degree angle.

  • label_font_size (int|float, optional) – The font size for plot axis labels and axis titles if summaries are configured to display.

  • tick_font_size (int|float, optional) – The font size for the tick labels in the plots.

  • spacing (float, optional) – The amount of spacing to add between plots. Defaults to None, which equates to 1.0 for less than 6 dimensions and 0.0 for higher dimensions.

  • contour_labels (string, optional) – If unset do not plot contour labels. If set to “confidence”, label the using confidence intervals. If set to “sigma”, labels using sigma.

  • contour_label_font_size (int|float, optional) – The font size for contour labels, if they are enabled.

  • legend_kwargs (dict, optional) – Extra arguments to pass to the legend api.

  • legend_location (tuple(int,int), optional) – Specifies the subplot in which to locate the legend. By default, this will be (0, -1), corresponding to the top right subplot if there are more than two parameters, and the bottom left plot for only two parameters with flip on. For having the legend in the primary subplot in the bottom left, set to (-1,0).

  • legend_artists (bool, optional) – Whether to include hide artists in the legend. If all linestyles and line widths are identical, this will default to false (as only the colours change). Otherwise it will be true.

  • legend_color_text (bool, optional) – Whether to colour the legend text.

  • watermark_text_kwargs (dict, optional) – Options to pass to the fontdict property when generating text for the watermark.

  • summary_area (float, optional) – The confidence interval used when generating parameter summaries. Defaults to 1 sigma, aka 0.6827

  • zorder (int, optional) – The zorder to pass to matplotlib to determine visual ordering when plotting.

Returns

Itself, to allow chaining calls.

Return type

ChainConsumer

configure_truth(**kwargs)

Configure the arguments passed to the axvline and axhline methods when plotting truth values.

If you do not call this explicitly, the plot() method will invoke this method automatically.

Recommended to set the parameters linestyle, color and/or alpha if you want some basic control.

Default is to use an opaque black dashed line.

Parameters

kwargs (dict) – The keyword arguments to unwrap when calling axvline and axhline.

Returns

Itself, to allow chaining calls.

Return type

ChainConsumer

divide_chain(chain=0)

Returns a ChainConsumer instance containing all the walks of a given chain as individual chains themselves.

This method might be useful if, for example, your chain was made using MCMC with 4 walkers. To check the sampling of all 4 walkers agree, you could call this to get a ChainConsumer instance with one chain for ech of the four walks. If you then plot, hopefully all four contours you would see agree.

Parameters

chain (int|str, optional) – The index or name of the chain you want divided

Returns

A new ChainConsumer instance with the same settings as the parent instance, containing num_walker chains.

Return type

ChainConsumer

remove_chain(chain=- 1)

Removes a chain from ChainConsumer.

Calling this will require any configurations set to be redone!

Parameters

chain (int|str, list[str|int]) – The chain(s) to remove. You can pass in either the chain index, or the chain name, to remove it. By default removes the last chain added.

Returns

Itself, to allow chaining calls.

Return type

ChainConsumer


class chainconsumer.analysis.Analysis(parent)
get_correlation_table(chain=0, parameters=None, caption='Parameter Correlations', label='tab:parameter_correlations')

Gets a LaTeX table of parameter correlations.

Parameters
  • chain (int|str, optional) – The chain index or name. Defaults to first chain.

  • parameters (list[str], optional) – The list of parameters to compute correlations. Defaults to all parameters for the given chain.

  • caption (str, optional) – The LaTeX table caption.

  • label (str, optional) – The LaTeX table label.

Returns

The LaTeX table ready to go!

Return type

str

get_correlations(chain=0, parameters=None)

Takes a chain and returns the correlation between chain parameters.

Parameters
  • chain (int|str, optional) – The chain index or name. Defaults to first chain.

  • parameters (list[str], optional) – The list of parameters to compute correlations. Defaults to all parameters for the given chain.

Returns

The first index giving a list of parameter names, the second index being the 2D correlation matrix.

Return type

tuple

get_covariance(chain=0, parameters=None)

Takes a chain and returns the covariance between chain parameters.

Parameters
  • chain (int|str, optional) – The chain index or name. Defaults to first chain.

  • parameters (list[str], optional) – The list of parameters to compute correlations. Defaults to all parameters for the given chain.

Returns

The first index giving a list of parameter names, the second index being the 2D covariance matrix.

Return type

tuple

get_covariance_table(chain=0, parameters=None, caption='Parameter Covariance', label='tab:parameter_covariance')

Gets a LaTeX table of parameter covariance.

Parameters
  • chain (int|str, optional) – The chain index or name. Defaults to first chain.

  • parameters (list[str], optional) – The list of parameters to compute correlations. Defaults to all parameters for the given chain.

  • caption (str, optional) – The LaTeX table caption.

  • label (str, optional) – The LaTeX table label.

Returns

The LaTeX table ready to go!

Return type

str

get_latex_table(parameters=None, transpose=False, caption=None, label='tab:model_params', hlines=True, blank_fill='--', filename=None)

Generates a LaTeX table from parameter summaries.

Parameters
  • parameters (list[str], int optional) – A list of what parameters to include in the table. By default, includes all parameters

  • transpose (bool, optional) – Defaults to False, which gives each column as a parameter, each chain (framework) as a row. You can swap it so that you have a parameter each row and a framework each column by setting this to True

  • caption (str, optional) – If you want to generate a caption for the table through Python, use this. Defaults to an empty string

  • label (str, optional) – If you want to generate a label for the table through Python, use this. Defaults to an empty string

  • hlines (bool, optional) – Inserts \hline before and after the header, and at the end of table.

  • blank_fill (str, optional) – If a framework does not have a particular parameter, will fill that cell of the table with this string.

  • filename (str, optional) – The file to save the output string to

Returns

the LaTeX table.

Return type

str

get_max_posteriors(parameters=None, squeeze=True, chains=None)

Gets the maximum posterior point in parameter space from the passed parameters.

Requires the chains to have set posterior values.

Parameters
  • parameters (str|list[str]) – The parameters to find

  • squeeze (bool, optional) – Squeeze the summaries. If you only have one chain, squeeze will not return a length one list, just the single summary. If this is false, you will get a length one list.

  • chains (list[int|str], optional) – A list of the chains to get a summary of.

Returns

One entry per chain, two-tuple represents the max-likelihood coordinate

Return type

list of two-tuples

get_parameter_text(lower, maximum, upper, wrap=False)

Generates LaTeX appropriate text from marginalised parameter bounds.

Parameters
  • lower (float) – The lower bound on the parameter

  • maximum (float) – The value of the parameter with maximum probability

  • upper (float) – The upper bound on the parameter

  • wrap (bool) – Wrap output text in dollar signs for LaTeX

Returns

The formatted text given the parameter bounds

Return type

str

get_summary(squeeze=True, parameters=None, chains=None)

Gets a summary of the marginalised parameter distributions.

Parameters
  • squeeze (bool, optional) – Squeeze the summaries. If you only have one chain, squeeze will not return a length one list, just the single summary. If this is false, you will get a length one list.

  • parameters (list[str], optional) – A list of parameters which to generate summaries for.

  • chains (list[int|str], optional) – A list of the chains to get a summary of.

Returns

One entry per chain, parameter bounds stored in dictionary with parameter as key

Return type

list of dictionaries


class chainconsumer.comparisons.Comparison(parent)
aic()

Returns the corrected Akaike Information Criterion (AICc) for all chains loaded into ChainConsumer.

If a chain does not have a posterior, number of data points, and number of free parameters loaded, this method will return None for that chain. Formally, the AIC is defined as

\[AIC \equiv -2\ln(P) + 2k,\]

where \(P\) represents the posterior, and \(k\) the number of model parameters. The AICc is then defined as

\[AIC_c \equiv AIC + \frac{2k(k+1)}{N-k-1},\]

where \(N\) represents the number of independent data points used in the model fitting. The AICc is a correction for the AIC to take into account finite chain sizes.

Returns

A list of all the AICc values - one per chain, in the order in which the chains were added.

Return type

list[float]

bic()

Returns the corrected Bayesian Information Criterion (BIC) for all chains loaded into ChainConsumer.

If a chain does not have a posterior, number of data points, and number of free parameters loaded, this method will return None for that chain. Formally, the BIC is defined as

\[BIC \equiv -2\ln(P) + k \ln(N),\]

where \(P\) represents the posterior, \(k\) the number of model parameters and \(N\) the number of independent data points used in the model fitting.

Returns

A list of all the BIC values - one per chain, in the order in which the chains were added.

Return type

list[float]

comparison_table(caption=None, label='tab:model_comp', hlines=True, aic=True, bic=True, dic=True, sort='bic', descending=True)

Return a LaTeX ready table of model comparisons.

Parameters
  • caption (str, optional) – The table caption to insert.

  • label (str, optional) – The table label to insert.

  • hlines (bool, optional) – Whether to insert hlines in the table or not.

  • aic (bool, optional) – Whether to include a column for AICc or not.

  • bic (bool, optional) – Whether to include a column for BIC or not.

  • dic (bool, optional) – Whether to include a column for DIC or not.

  • sort (str, optional) – How to sort the models. Should be one of “bic”, “aic” or “dic”.

  • descending (bool, optional) – The sort order.

Returns

A LaTeX table to be copied into your document.

Return type

str

dic()

Returns the corrected Deviance Information Criterion (DIC) for all chains loaded into ChainConsumer.

If a chain does not have a posterior, this method will return None for that chain. Note that the DIC metric is only valid on posterior surfaces which closely resemble multivariate normals! Formally, we follow Liddle (2007) and first define Bayesian complexity as

\[p_D = \bar{D}(\theta) - D(\bar{\theta}),\]

where \(D(\theta) = -2\ln(P(\theta)) + C\) is the deviance, where \(P\) is the posterior and \(C\) a constant. From here the DIC is defined as

\[DIC \equiv D(\bar{\theta}) + 2p_D = \bar{D}(\theta) + p_D.\]
Returns

A list of all the DIC values - one per chain, in the order in which the chains were added.

Return type

list[float]

References

[1] Andrew R. Liddle, “Information criteria for astrophysical model selection”, MNRAS (2007)


class chainconsumer.diagnostic.Diagnostic(parent)
gelman_rubin(chain=None, threshold=0.05)

Runs the Gelman Rubin diagnostic on the supplied chains.

Parameters
  • chain (int|str, optional) – Which chain to run the diagnostic on. By default, this is None, which will run the diagnostic on all chains. You can also supply and integer (the chain index) or a string, for the chain name (if you set one).

  • threshold (float, optional) – The maximum deviation permitted from 1 for the final value \(\hat{R}\)

Returns

whether or not the chains pass the test

Return type

float

Notes

I follow PyMC in calculating the Gelman-Rubin statistic, where, having \(m\) chains of length \(n\), we compute

\[ \begin{align}\begin{aligned}B = \frac{n}{m-1} \sum_{j=1}^{m} \left(\bar{\theta}_{.j} - \bar{\theta}_{..}\right)^2\\W = \frac{1}{m} \sum_{j=1}^{m} \left[ \frac{1}{n-1} \sum_{i=1}^{n} \left( \theta_{ij} - \bar{\theta_{.j}}\right)^2 \right]\end{aligned}\end{align} \]

where \(\theta\) represents each model parameter. We then compute \(\hat{V} = \frac{n_1}{n}W + \frac{1}{n}B\), and have our convergence ratio \(\hat{R} = \sqrt{\frac{\hat{V}}{W}}\). We check that for all parameters, this ratio deviates from unity by less than the supplied threshold.

geweke(chain=None, first=0.1, last=0.5, threshold=0.05)

Runs the Geweke diagnostic on the supplied chains.

Parameters
  • chain (int|str, optional) – Which chain to run the diagnostic on. By default, this is None, which will run the diagnostic on all chains. You can also supply and integer (the chain index) or a string, for the chain name (if you set one).

  • first (float, optional) – The amount of the start of the chain to use

  • last (float, optional) – The end amount of the chain to use

  • threshold (float, optional) – The p-value to use when testing for normality.

Returns

whether or not the chains pass the test

Return type

float


class chainconsumer.plotter.Plotter(parent)
plot(figsize='GROW', parameters=None, chains=None, extents=None, filename=None, display=False, truth=None, legend=None, blind=None, watermark=None, log_scales=None)

Plot the chain!

Parameters
  • figsize (str|tuple(float)|float, optional) – The figure size to generate. Accepts a regular two tuple of size in inches, or one of several key words. The default value of COLUMN creates a figure of appropriate size of insertion into an A4 LaTeX document in two-column mode. PAGE creates a full page width figure. GROW creates an image that scales with parameters (1.5 inches per parameter). String arguments are not case sensitive. If you pass a float, it will scale the default GROW by that amount, so 2.0 would result in a plot 3 inches per parameter.

  • parameters (list[str]|int, optional) – If set, only creates a plot for those specific parameters (if list). If an integer is given, only plots the fist so many parameters.

  • chains (int|str, list[str|int], optional) – Used to specify which chain to show if more than one chain is loaded in. Can be an integer, specifying the chain index, or a str, specifying the chain name.

  • extents (list[tuple[float]] or dict[str], optional) – Extents are given as two-tuples. You can pass in a list the same size as parameters (or default parameters if you don’t specify parameters), or as a dictionary.

  • filename (str, optional) – If set, saves the figure to this location

  • display (bool, optional) – If True, shows the figure using plt.show().

  • truth (list[float] or dict[str], optional) – A list of truth values corresponding to parameters, or a dictionary of truth values indexed by key

  • legend (bool, optional) – If true, creates a legend in your plot using the chain names.

  • blind (bool|string|list[string], optional) – Whether to blind axes values. Can be set to True to blind all parameters, or can pass in a string (or list of strings) which specify the parameters to blind.

  • watermark (str, optional) – A watermark to add to the figure

  • log_scales (bool, list[bool] or dict[bool], optional) – Whether or not to use a log scale on any given axis. Can be a list of True/False, a list of param names to set to true, a dictionary of param names with true/false or just a bool (just True would set everything to log scales).

Returns

the matplotlib figure

Return type

figure

plot_contour(ax, parameter_x, parameter_y, chains=None)

A lightweight method to plot contours in an external axis given two specified parameters

Parameters
  • ax (matplotlib axis) – The axis to plot on

  • parameter_x (str) – The name of the parameter to plot for the x axis. Must be the string label of the parameter.

  • parameter_y (str) – The name of the parameter to plot for the y axis. Must be the string label of the parameter.

  • chains (int|str, list[str|int], optional) – Used to specify which chain to show if more than one chain is loaded in. Can be an integer, specifying the chain index, or a str, specifying the chain name, or a list of either.

plot_distributions(parameters=None, truth=None, extents=None, display=False, filename=None, chains=None, col_wrap=4, figsize=None, blind=None, log_scales=None)

Plots the 1D parameter distributions for verification purposes.

This plot is more for a sanity or consistency check than for use with final results. Plotting this before plotting with plot() allows you to quickly see if the chains give well behaved distributions, or if certain parameters are suspect or require a greater burn in period.

Parameters
  • parameters (list[str]|int, optional) – Specify a subset of parameters to plot. If not set, all parameters are plotted. If an integer is given, only the first so many parameters are plotted.

  • truth (list[float]|dict[str], optional) – A list of truth values corresponding to parameters, or a dictionary of truth values keyed by the parameter.

  • extents (list[tuple]|dict[str], optional) – A list of two-tuples for plot extents per parameter, or a dictionary of extents keyed by the parameter.

  • display (bool, optional) – If set, shows the plot using plt.show()

  • filename (str, optional) – If set, saves the figure to the filename

  • chains (int|str, list[str|int], optional) – Used to specify which chain to show if more than one chain is loaded in. Can be an integer, specifying the chain index, or a str, specifying the chain name.

  • col_wrap (int, optional) – How many columns to plot before wrapping.

  • figsize (tuple(float)|float, optional) – Either a tuple specifying the figure size or a float scaling factor.

  • blind (bool|string|list[string], optional) – Whether to blind axes values. Can be set to True to blind all parameters, or can pass in a string (or list of strings) which specify the parameters to blind.

  • log_scales (bool, list[bool] or dict[bool], optional) – Whether or not to use a log scale on any given axis. Can be a list of True/False, a list of param names to set to true, a dictionary of param names with true/false or just a bool (just True would set everything to log scales).

Returns

the matplotlib figure created

Return type

figure

plot_summary(parameters=None, truth=None, extents=None, display=False, filename=None, chains=None, figsize=1.0, errorbar=False, include_truth_chain=True, blind=None, watermark=None, extra_parameter_spacing=0.5, vertical_spacing_ratio=1.0, show_names=True, log_scales=None)

Plots parameter summaries

This plot is more for a sanity or consistency check than for use with final results. Plotting this before plotting with plot() allows you to quickly see if the chains give well behaved distributions, or if certain parameters are suspect or require a greater burn in period.

Parameters
  • parameters (list[str]|int, optional) – Specify a subset of parameters to plot. If not set, all parameters are plotted. If an integer is given, only the first so many parameters are plotted.

  • truth (list[float]|list|list[float]|dict[str]|str, optional) – A list of truth values corresponding to parameters, or a dictionary of truth values keyed by the parameter. Each “truth value” can be either a float (will draw a vertical line), two floats (a shaded interval) or three floats (min, mean, max), which renders as a shaded interval with a line for the mean. Or, supply a string which matches a chain name, and the results for that chain will be used as the ‘truth’

  • extents (list[tuple]|dict[str], optional) – A list of two-tuples for plot extents per parameter, or a dictionary of extents keyed by the parameter.

  • display (bool, optional) – If set, shows the plot using plt.show()

  • filename (str, optional) – If set, saves the figure to the filename

  • chains (int|str, list[str|int], optional) – Used to specify which chain to show if more than one chain is loaded in. Can be an integer, specifying the chain index, or a str, specifying the chain name.

  • figsize (float, optional) – Scale horizontal and vertical figure size.

  • errorbar (bool, optional) – Whether to onle plot an error bar, instead of the marginalised distribution.

  • include_truth_chain (bool, optional) – If you specify another chain as the truth chain, determine if it should still be plotted.

  • blind (bool|string|list[string], optional) – Whether to blind axes values. Can be set to True to blind all parameters, or can pass in a string (or list of strings) which specify the parameters to blind.

  • watermark (str, optional) – A watermark to add to the figure

  • extra_parameter_spacing (float, optional) – Increase horizontal space for parameter values

  • vertical_spacing_ratio (float, optional) – Increase vertical space for each model

  • show_names (bool, optional) – Whether to show chain names or not. Defaults to True.

  • log_scales (bool, list[bool] or dict[bool], optional) – Whether or not to use a log scale on any given axis. Can be a list of True/False, a list of param names to set to true, a dictionary of param names with true/false or just a bool (just True would set everything to log scales).

Returns

the matplotlib figure created

Return type

figure

plot_walks(parameters=None, truth=None, extents=None, display=False, filename=None, chains=None, convolve=None, figsize=None, plot_weights=True, plot_posterior=True, log_weight=None, log_scales=None)

Plots the chain walk; the parameter values as a function of step index.

This plot is more for a sanity or consistency check than for use with final results. Plotting this before plotting with plot() allows you to quickly see if the chains are well behaved, or if certain parameters are suspect or require a greater burn in period.

The desired outcome is to see an unchanging distribution along the x-axis of the plot. If there are obvious tails or features in the parameters, you probably want to investigate.

Parameters
  • parameters (list[str]|int, optional) – Specify a subset of parameters to plot. If not set, all parameters are plotted. If an integer is given, only the first so many parameters are plotted.

  • truth (list[float]|dict[str], optional) – A list of truth values corresponding to parameters, or a dictionary of truth values keyed by the parameter.

  • extents (list[tuple]|dict[str], optional) – A list of two-tuples for plot extents per parameter, or a dictionary of extents keyed by the parameter.

  • display (bool, optional) – If set, shows the plot using plt.show()

  • filename (str, optional) – If set, saves the figure to the filename

  • chains (int|str, list[str|int], optional) – Used to specify which chain to show if more than one chain is loaded in. Can be an integer, specifying the chain index, or a str, specifying the chain name.

  • convolve (int, optional) – If set, overplots a smoothed version of the steps using convolve as the width of the smoothing filter.

  • figsize (tuple, optional) – If set, sets the created figure size.

  • plot_weights (bool, optional) – If true, plots the weight if they are available

  • plot_posterior (bool, optional) – If true, plots the log posterior if they are available

  • log_weight (bool, optional) – Whether to display weights in log space or not. If None, the value is inferred by the mean weights of the plotted chains.

  • log_scales (bool, list[bool] or dict[bool], optional) – Whether or not to use a log scale on any given axis. Can be a list of True/False, a list of param names to set to true, a dictionary of param names with true/false or just a bool (just True would set everything to log scales).

Returns

the matplotlib figure created

Return type

figure

restore_rc_params()

Restores the matplotlib rc parameters modified by usetex and serif.

Unfortunately this cannot be automated because you cannot invoke it whilst you have an active figure object or matplotlib will destroy you. So do all your plotting, close the plots, and then you can call this.