---
title: results
sidebarTitle: results
---

# `catalax.mcmc.results`

## Classes

### `HMCResults` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L29" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>


Results container for HMC sampling with integrated visualization methods.

This class provides a comprehensive interface for analyzing and visualizing
the results of Hamiltonian Monte Carlo (HMC) sampling. It wraps the MCMC
object and provides convenient methods for diagnostics, plotting, and
exporting results.

The class integrates with ArviZ for advanced diagnostics and provides
methods for generating various plots including corner plots, trace plots,
posterior distributions, and credibility intervals.


**Methods:**

#### `get_fitted_model` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L65" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_fitted_model(self, hdi_prob: float = 0.95, set_bounds: bool = False) -> 'Model'
```

Get the fitted model with parameter estimates from posterior samples.

Creates a new model instance with parameters set to posterior estimates.
Parameter values are typically set to posterior means or medians, with
uncertainty bounds optionally derived from highest density intervals.

**Args:**
- `hdi_prob`: Probability mass for highest density interval calculation.
Used to determine uncertainty bounds for parameters.
- `set_bounds`: Whether to set parameter bounds based on HDI. If True,
parameter bounds will be updated to reflect posterior uncertainty.

**Returns:**
- New model instance with parameters updated from posterior samples.
The returned model can be used for predictions with fitted parameters.


#### `get_samples` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L92" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
get_samples(self) -> Dict[str, Array]
```

Get posterior samples for all parameters.

Returns the raw posterior samples as generated by the MCMC sampler.
These samples represent the posterior distribution over model parameters
and can be used for custom analysis or uncertainty quantification.

**Returns:**
- Dict[str, Array]: Dictionary mapping parameter names to arrays of
posterior samples. Each array has shape (num_samples, ...) where
the parameter dimensions depend on the parameter structure.


#### `print_summary` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L106" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
print_summary(self)
```

Print MCMC summary statistics to console.

Displays a tabular summary of the MCMC results including:
- Parameter posterior means and standard deviations
- Effective sample size (ESS) for each parameter
- R-hat convergence diagnostics
- Monte Carlo standard error estimates

This provides a quick overview of sampling quality and parameter estimates.


#### `render_model` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L119" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
render_model(self, path: str, render_distributions: bool = False)
```

Render the Bayesian model structure as a graphical representation.

Creates a visual representation of the model's probabilistic structure,
showing the relationships between parameters, priors, and likelihood.
Useful for understanding model structure and debugging.

**Args:**
- `path`: File path where the rendered model graph will be saved.
Should include appropriate file extension (e.g., '.pdf', '.png').
- `render_distributions`: Whether to include distribution shapes in the
rendered graph. If True, adds visual representation of prior
and likelihood distributions.

**Returns:**
- The result of numpyro.render_model, typically None but may vary
- based on the rendering backend used.


#### `plot_corner` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L148" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
plot_corner(self, quantiles: Tuple[float, float, float] = (0.16, 0.5, 0.84), figsize: Optional[Tuple[float, float]] = None, backend: Optional[str] = None, show: bool = False, path: Optional[str] = None)
```

Plot corner plot of parameter correlations and marginal distributions.

Creates a matrix plot showing pairwise parameter correlations in the
lower triangle, marginal posterior distributions on the diagonal, and
optionally scatter plots in the upper triangle. This is essential for
understanding parameter dependencies and posterior structure.

**Args:**
- `quantiles`: Three quantiles to display in marginal distributions,
typically representing lower bound, median, and upper bound.
Default (0.16, 0.5, 0.84) corresponds to 68% credible intervals.
- `figsize`: Figure size as (width, height) in inches. If None, uses default size.
- `backend`: Backend to use ('matplotlib' or 'bokeh'). If None, uses default.
- `show`: Whether to display the plot immediately using plt.show().
If False, the figure is returned without displaying.
- `path`: Optional file path to save the plot. If provided, the figure
will be saved to this location.

**Returns:**
- matplotlib.figure.Figure or bokeh plot: The corner plot figure, or None if show=True.
Can be used for further customization or saving.


#### `plot_posterior` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L188" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
plot_posterior(self, figsize: Optional[Tuple[float, float]] = None, backend: Optional[str] = None, show: bool = False, path: Optional[str] = None, **kwargs)
```

Plot posterior distributions for all parameters.

Creates individual plots showing the posterior distribution for each
model parameter. This provides a clear view of parameter uncertainty
and can help identify multimodal distributions or convergence issues.

**Args:**
- `figsize`: Figure size as (width, height) in inches. If None, uses default size.
- `backend`: Backend to use ('matplotlib' or 'bokeh'). If None, uses default.
- `show`: Whether to display the plot immediately using plt.show().
If False, the figure is returned without displaying.
- `path`: Optional file path to save the plot. If provided, the figure
will be saved to this location.
- `**kwargs`: Additional keyword arguments passed to arviz.plot_posterior.
Common options include 'hdi_prob' for credible interval probability,
'point_estimate' for central tendency measure, and 'ref_val' for
reference values.

**Returns:**
- matplotlib.figure.Figure or bokeh plot: The posterior plot figure, or None if show=True.
Contains subplots for each parameter's posterior distribution.


#### `plot_credibility_interval` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L228" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
plot_credibility_interval(self, initial_condition: Dict[str, float], time: Array, dt0: float = 0.1, figsize: Optional[Tuple[float, float]] = None, backend: Optional[str] = None, show: bool = False, path: Optional[str] = None)
```

Plot credibility intervals for model simulations.

Generates model predictions using posterior parameter samples and plots
credibility intervals around the mean trajectory. This shows prediction
uncertainty arising from parameter uncertainty and is crucial for
understanding model reliability.

**Args:**
- `initial_condition`: Dictionary mapping state names to initial
concentrations for the simulation. Must include all state
defined in the model.
- `time`: Array of time points at which to evaluate the model.
Should span the desired simulation duration.
- `dt0`: Time step size for numerical integration. Smaller values
increase accuracy but require more computation.
- `figsize`: Figure size as (width, height) in inches. If None, uses default size.
- `backend`: Backend to use ('matplotlib' or 'bokeh'). If None, uses default.
Note\: Credibility interval plots currently only support matplotlib backend.
- `show`: Whether to display the plot immediately using plt.show().
If False, the figure is returned without displaying.
- `path`: Optional file path to save the plot. If provided, the figure
will be saved to this location.

**Returns:**
- matplotlib.figure.Figure: The credibility interval plot figure,
or None if show=True. Shows model trajectories with uncertainty bands.


#### `plot_trace` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L277" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
plot_trace(self, figsize: Optional[Tuple[float, float]] = None, backend: Optional[str] = None, show: bool = False, path: Optional[str] = None, **kwargs)
```

Plot MCMC trace plots for convergence diagnostics.

Shows the evolution of parameter values across MCMC iterations for
each chain. Essential for diagnosing convergence issues, identifying
burn-in periods, and detecting problematic sampling behavior such
as poor mixing or trend.

**Args:**
- `figsize`: Figure size as (width, height) in inches. If None, uses default size.
- `backend`: Backend to use ('matplotlib' or 'bokeh'). If None, uses default.
- `show`: Whether to display the plot immediately using plt.show().
If False, the figure is returned without displaying.
- `path`: Optional file path to save the plot. If provided, the figure
will be saved to this location.
- `**kwargs`: Additional keyword arguments passed to arviz.plot_trace.
Common options include 'var_names' to select specific parameters,
'compact' for layout style, and 'combined' for overlaying chains.

**Returns:**
- matplotlib.figure.Figure or bokeh plot: The trace plot figure, or None if show=True.
Contains time series plots for each parameter across all chains.


#### `plot_forest` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L315" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
plot_forest(self, figsize: Optional[Tuple[float, float]] = None, backend: Optional[str] = None, show: bool = False, path: Optional[str] = None, **kwargs)
```

Plot forest plot of parameter distributions.

Creates a horizontal plot showing credible intervals for all parameters
in a compact format. Useful for comparing parameter estimates and
uncertainties across many parameters simultaneously.

**Args:**
- `figsize`: Figure size as (width, height) in inches. If None, uses default size.
- `backend`: Backend to use ('matplotlib' or 'bokeh'). If None, uses default.
- `show`: Whether to display the plot immediately using plt.show().
If False, the figure is returned without displaying.
- `path`: Optional file path to save the plot. If provided, the figure
will be saved to this location.
- `**kwargs`: Additional keyword arguments passed to arviz.plot_forest.
Common options include 'hdi_prob' for credible interval probability,
'combined' for pooling chains, and 'ess' for showing effective
sample size.

**Returns:**
- matplotlib.figure.Figure or bokeh plot: The forest plot figure, or None if show=True.
Shows horizontal credible intervals for each parameter.


#### `summary` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L357" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
summary(self, hdi_prob: float = 0.95) -> Union[pd.DataFrame, xarray.Dataset]
```

Generate comprehensive summary statistics for posterior samples.

Computes and returns detailed summary statistics including central
tendencies, credible intervals, effective sample sizes, and convergence
diagnostics. This provides a comprehensive numerical summary of the
MCMC results.

**Args:**
- `hdi_prob`: Probability mass for highest density interval calculation.
Determines the width of credible intervals in the summary.
Default 0.95 corresponds to 95% credible intervals.

**Returns:**
- Union\[pd.DataFrame, xarray.Dataset]: Summary statistics table
containing means, standard deviations, credible intervals,
effective sample sizes, and R-hat diagnostics for each parameter.
Format depends on the underlying implementation.


#### `plot_mcse` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L380" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
plot_mcse(self, figsize: Optional[Tuple[float, float]] = None, backend: Optional[str] = None, show: bool = False, path: Optional[str] = None, **kwargs)
```

Plot Monte Carlo standard error diagnostics.

Visualizes the Monte Carlo standard error (MCSE) for parameter estimates,
which quantifies the uncertainty in posterior estimates due to finite
sample size. Lower MCSE indicates more reliable estimates.

**Args:**
- `figsize`: Figure size as (width, height) in inches. If None, uses default size.
- `backend`: Backend to use ('matplotlib' or 'bokeh'). If None, uses default.
- `show`: Whether to display the plot immediately using plt.show().
If False, the figure is returned without displaying.
- `path`: Optional file path to save the plot. If provided, the figure
will be saved to this location.
- `**kwargs`: Additional keyword arguments (currently unused but
maintained for API consistency).

**Returns:**
- matplotlib.figure.Figure or bokeh plot: The MCSE plot figure, or None if show=True.
Shows Monte Carlo standard error for each parameter.


#### `plot_ess` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L416" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
plot_ess(self, figsize: Optional[Tuple[float, float]] = None, backend: Optional[str] = None, show: bool = False, path: Optional[str] = None, **kwargs)
```

Plot effective sample size diagnostics.

Visualizes the effective sample size (ESS) for each parameter, which
measures how many independent samples the MCMC chains provide. Higher
ESS indicates better sampling efficiency and more reliable estimates.

**Args:**
- `figsize`: Figure size as (width, height) in inches. If None, uses default size.
- `backend`: Backend to use ('matplotlib' or 'bokeh'). If None, uses default.
- `show`: Whether to display the plot immediately using plt.show().
If False, the figure is returned without displaying.
- `path`: Optional file path to save the plot. If provided, the figure
will be saved to this location.
- `**kwargs`: Additional keyword arguments (currently unused but
maintained for API consistency).

**Returns:**
- matplotlib.figure.Figure or bokeh plot: The ESS plot figure, or None if show=True.
Shows effective sample size for each parameter.


#### `to_arviz` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L453" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_arviz(self)
```

Convert MCMC results to ArviZ InferenceData format.

Transforms the numpyro MCMC results into ArviZ's standardized format,
enabling access to advanced diagnostic tools, visualization methods,
and interoperability with other Bayesian analysis packages.

**Returns:**
- arviz.InferenceData: MCMC results in ArviZ format containing
posterior samples, sample statistics, and metadata. This format
provides access to comprehensive Bayesian analysis tools and
standardized visualization methods.


#### `to_netcdf` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L468" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
to_netcdf(self, path: str)
```

Save MCMC results to NetCDF format for persistent storage.

Exports the complete MCMC results to a self-describing NetCDF file
that preserves all sample data, metadata, and structure. This format
is ideal for archiving results, sharing analyses, or loading results
in different computing sessions.

**Args:**
- `path`: File path where the NetCDF file will be saved. Should include
the '.nc' extension. The file will contain all posterior samples,
diagnostics, and metadata in a standardized format.

**Returns:**
- Results are saved to the specified path. The file can later
be loaded using arviz.from_netcdf() or similar tools.


#### `create_plots_widget` <sup><a href="https://github.com/JR-1991/Catalax/blob/master/catalax/mcmc/results.py#L552" target="_blank"><Icon icon="github" style="width: 14px; height: 14px;" /></a></sup>

```python
create_plots_widget(self, initial_condition: Optional[Dict[str, float]] = None, time: Optional[Array] = None, dt0: float = 0.1, figsize: Optional[Tuple[float, float]] = (10, 6), backend: Optional[str] = None, tabs_to_include: Optional[List[str]] = None) -> Optional[widgets.Widget]
```

Create an interactive tabbed widget with all diagnostic plots.

This method creates a comprehensive tabbed interface for exploring
MCMC results with different diagnostic plots. Each tab contains
a different type of visualization.

**Args:**
- `initial_condition`: Initial conditions for credibility interval plot.
If None, credibility interval tab will be excluded.
- `time`: Time points for credibility interval plot.
If None, credibility interval tab will be excluded.
- `dt0`: Time step for credibility interval simulation.
- `figsize`: Default figure size for all plots.
- `backend`: Backend to use ('matplotlib' or 'bokeh'). If None, uses default.
- `tabs_to_include`: List of tab names to include. If None, includes all available.
Available options\: ['posterior', 'trace', 'corner', 'forest',
'credibility', 'ess', 'mcse']

**Returns:**
- ipywidgets.Tab: Tabbed widget with diagnostic plots, or None if widgets
are not available or not in Jupyter environment.

