Anesthetic

Overview

Anesthetic is a Python package for visualizing and analyzing posterior samples from Bayesian inference. It creates publication-quality corner plots, 1D/2D marginal distributions, and computes Bayesian statistics (evidence, KL divergence) from nested sampling or MCMC chains.

Key capabilities:

• Load chains from PolyChord, MultiNest, UltraNest, Cobaya, GetDist formats
• Create corner/triangle plots with KDE, histogram, or scatter representations
• Compare prior vs posterior distributions
• Compute log-evidence, KL divergence, model dimensionality
• Built on pandas DataFrames for easy parameter manipulation

Workflow position: This skill provides component (4) Visualization in the physics workflow.

Installation

First, ensure anesthetic is installed in your environment:

# Using uv (recommended)
uv pip install anesthetic

# Or using pip
pip install anesthetic

# Or using conda
conda install -c conda-forge anesthetic

Optional for faster KDE: uv pip install fastkde

Quick Start

from anesthetic import read_chains, make_2d_axes
import matplotlib.pyplot as plt

# Load posterior chains (auto-detects format)
samples = read_chains('path/to/chains_root')

# Create corner plot (two-step process)
fig, axes = make_2d_axes(['x0', 'x1', 'x2'])  # Create axes first
samples.plot_2d(axes)                          # Then plot onto them
fig.savefig('corner.png')
plt.close(fig)

Important: Always create axes first with make_2d_axes() or make_1d_axes(), then pass them to plot_2d() or plot_1d(). The plot methods return axes, not (fig, axes) tuples.

Core Workflow

1. Load chains - read_chains() auto-detects format, or use format-specific readers
2. Select parameters - Choose which parameters to plot
3. Create axes - make_1d_axes() or make_2d_axes()
4. Plot - samples.plot_1d() or samples.plot_2d()
5. Customize - Labels, colors, reference lines

Reference Documentation

Detailed documentation is split by topic:

• Loading data: See references/loading-chains.md for all supported formats and creating samples from arrays
• Plotting: See references/plotting-guide.md for 1D/2D plots, plot kinds, and multi-chain comparisons
• Customization: See references/customization.md for labels, colors, axes, legends, and reference values
• Statistics: See references/statistics.md for Bayesian evidence, KL divergence, and MCMC diagnostics
• Full API: See references/api-reference.md for complete function signatures and options

Common Patterns

Basic Corner Plot

from anesthetic import read_chains, make_2d_axes

samples = read_chains('chains/run')
fig, axes = make_2d_axes(['param1', 'param2', 'param3'])
samples.plot_2d(axes, kind='kde')
fig.savefig('corner.png')

Prior vs Posterior Comparison

samples = read_chains('chains/run')  # NestedSamples
prior = samples.prior()

fig, axes = make_2d_axes(['x0', 'x1', 'x2'])
prior.plot_2d(axes, kind='kde', label='Prior', alpha=0.5)
samples.plot_2d(axes, kind='kde', label='Posterior')
axes.iloc[-1, 0].legend(bbox_to_anchor=(len(axes)/2, len(axes)), loc='lower center')

Multiple Chain Comparison

samples1 = read_chains('chains/model1')
samples2 = read_chains('chains/model2')

fig, axes = make_2d_axes(['x0', 'x1'])
samples1.plot_2d(axes, kind='kde', label='Model 1')
samples2.plot_2d(axes, kind='kde', label='Model 2')
axes.iloc[-1, 0].legend()

Compute Bayesian Evidence

samples = read_chains('chains/run')  # Must be NestedSamples
print(f"log(Z) = {samples.logZ():.2f}")
print(f"D_KL = {samples.D_KL():.2f}")

# With uncertainties
stats = samples.stats(nsamples=1000)
print(f"log(Z) = {stats['logZ'].mean():.2f} +/- {stats['logZ'].std():.2f}")

Plot Bayesian Statistics

# stats is a Samples object, so use anesthetic's plot_2d
stats = samples.stats(nsamples=1000)
fig, axes = make_2d_axes(['logZ', 'D_KL', 'd_G'])
stats.plot_2d(axes)
fig.savefig('stats_corner.png')

Add Truth Values

fig, axes = make_2d_axes(['x0', 'x1', 'x2'])
samples.plot_2d(axes)
truth = {'x0': 0.3, 'x1': 0.8, 'x2': 0.7}
axes.axlines(truth, color='red', linestyle='--')
axes.scatter(truth, marker='*', s=100, c='red')

Runnable Example

A complete example script is available at scripts/example_plots.py. Run it with:

python scripts/example_plots.py path/to/chains_root

This creates corner_plot.png, 1d_marginals.png, and prior_posterior.png.