---
title: Bayesian Optimization outputs and interpretation
description: >-
  Parameter posteriors, HDI intervals, diagnostics, and model comparison
  metrics from a Bayesian fit.
tags:
  - bayesian
  - outputs
---

A completed job returns a per-parameter posterior summary, the full trace for further analysis, sampler diagnostics, and (for `pkpd` models) compartmental PK parameters. Use the diagnostics to confirm the fit converged before you trust the parameter estimates.

## Output artifacts

| Artifact | Format | Contents |
|----------|--------|----------|
| **posterior_summary_csv** | CSV | One row per parameter: `parameter, mean, sd, hdi_3%, hdi_97%, ess, r_hat`. |
| **trace_netcdf** | NetCDF | Full posterior samples for every chain, for offline analysis (e.g. with ArviZ). |
| **diagnostics_json** | JSON | `{divergences, r_hat_max, ess_min, loo, waic}`. |
| **plots_zip** | ZIP | Trace plots, posterior distribution plots, and posterior-predictive-check (PPC) plots, when `generate_plots` is enabled. |

The job's top-level metrics also report `n_samples`, `n_chains`, `all_rhat_ok`, `min_ess`, `divergences`, and `loo_score`.

## Reading the parameter summary

- **mean / sd**: the posterior mean and standard deviation for each parameter.
- **hdi_3% / hdi_97%**: the 94% highest-density interval — the range PyMC's default HDI reports as most credible, not a classical confidence interval.
- **ess**: effective sample size. Low ESS relative to `num_samples * num_chains` means the chains are autocorrelated and your effective posterior is thinner than it looks.
- **r_hat**: the Gelman-Rubin statistic comparing between-chain and within-chain variance. Values close to 1.0 (conventionally <1.01) indicate the chains agree; higher values mean the sampler hasn't converged and the summary shouldn't be trusted yet.

## Convergence diagnostics

- **divergences**: MCMC divergent transitions. Any nonzero count is worth investigating — reparameterize the model, raise `target_accept`, or increase `num_tune` before trusting the posterior.
- **r_hat_max**: the worst R-hat across all parameters; check this before reading individual parameter rows.
- **ess_min**: the smallest effective sample size across parameters; a low value flags the parameter with the least-reliable posterior.

## Model comparison

- **loo**: leave-one-out cross-validation estimate (when `compute_loo` is enabled). Use it to compare model fits on the same data — higher is better.
- **waic**: Watanabe-Akaike information criterion (when `compute_waic` is enabled), an alternative comparison metric on the same scale question as LOO.

## PK/PD-specific outputs

For `model_type: "pkpd"`, the parameter summary includes the compartmental parameters for the chosen `pk_model` (for example clearance `CL` and volume of distribution `V` for a one-compartment model). For a population model (`population_model: true`), the summary includes both the population-level (fixed-effect) parameters and the per-subject random-effect terms named in `random_effects`.

## Plots

When `generate_plots` is enabled, `plots_zip` contains:
- **Trace plots**: per-chain parameter traces, for a visual convergence check alongside R-hat.
- **Posterior plots**: the marginal posterior distribution for each parameter.
- **PPC plots**: posterior predictive checks — simulated data from the fitted model overlaid on the observed data, to sanity-check the model against reality.

## Read next