Bayesian Optimization FAQ

Q: Which model type should I use?

regression for a standard predictor-to-outcome fit, hierarchical when your data is grouped (batch, site, subject) and you want to pool information across groups, dose_response for a dose-response curve, time_series for time-indexed data, mixture for a mixture over the outcome distribution, and pkpd for compartmental pharmacokinetic modeling. Use custom only if none of the built-in model types fit and you can supply your own PyMC model code.

Q: What does inference_method change?

mcmc (the default) draws samples with PyMC's NUTS sampler and gives you the most reliable posterior, at the cost of being the slowest option. variational fits an approximate posterior faster but can understate uncertainty. pathfinder is a faster approximate method that initializes well but, like variational, trades some accuracy for speed. Start with mcmc; switch only if runtime is a real constraint.

Q: How do I fit a population PK model?

Set model_type: "pkpd", choose pk_model and administration, and provide time_column, concentration_column, and dose_column. Add subject_column and set population_model: true to fit per-subject random effects (default on CL and V) on top of the population-level parameters — override random_effects to add or change which parameters get subject-level variation.

Q: Can I supply my own model?

Yes — set model_type: "custom" and provide model_code with your own PyMC model. This bypasses the built-in model-type logic entirely, so you're responsible for the model's correctness.

Q: How do I know if the fit converged?

Check r_hat_max (want it close to 1.0, conventionally <1.01), ess_min (want it reasonably large relative to your total sample count), and divergences (want 0). If any of these look off, don't trust the parameter summary yet — increase tuning/sampling or reparameterize first.

Common questions about model types, sampler settings, PK/PD modeling, and convergence diagnostics.

These answers cover which model type to pick, how the sampler settings affect a fit, how PK/PD modeling works, and how to tell whether a fit converged.

Frequently asked questions

Which model type should I use?

regression for a standard predictor-to-outcome fit, hierarchical when your data is grouped (batch, site, subject) and you want to pool information across groups, dose_response for a dose-response curve, time_series for time-indexed data, mixture for a mixture over the outcome distribution, and pkpd for compartmental pharmacokinetic modeling. Use custom only if none of the built-in model types fit and you can supply your own PyMC model code.

What does `inference_method` change?

mcmc (the default) draws samples with PyMC's NUTS sampler and gives you the most reliable posterior, at the cost of being the slowest option. variational fits an approximate posterior faster but can understate uncertainty. pathfinder is a faster approximate method that initializes well but, like variational, trades some accuracy for speed. Start with mcmc; switch only if runtime is a real constraint.

How many chains and samples do I need?

The defaults — 4 chains, 2,000 samples, 1,000 tuning steps — are a reasonable starting point for most models. More chains make the R-hat convergence check more reliable (you're comparing more independent runs); more samples raise the effective sample size for each parameter. Increase both for a model with many parameters or a complex posterior geometry.

What if I see divergences?

A nonzero divergence count means MCMC found regions of the posterior geometry it couldn't sample reliably — the resulting posterior may be biased. Raise target_accept (toward 0.95–0.99) and increase num_tune. Divergences that persist after that usually point to a model reparameterization issue rather than something to tune away.

How do I fit a population PK model?

Set model_type: "pkpd", choose pk_model and administration, and provide time_column, concentration_column, and dose_column. Add subject_column and set population_model: true to fit per-subject random effects (default on CL and V) on top of the population-level parameters — override random_effects to add or change which parameters get subject-level variation.

What's the difference between LOO and WAIC?

Both are information criteria for comparing model fits on the same data, computed when compute_loo/compute_waic are enabled (both default on). They usually agree; if they diverge substantially, treat that as a signal to inspect the model rather than picking whichever number looks better.

Can I supply my own model?

Yes — set model_type: "custom" and provide model_code with your own PyMC model. This bypasses the built-in model-type logic entirely, so you're responsible for the model's correctness.

How do I know if the fit converged?

Check r_hat_max (want it close to 1.0, conventionally <1.01), ess_min (want it reasonably large relative to your total sample count), and divergences (want 0). If any of these look off, don't trust the parameter summary yet — increase tuning/sampling or reparameterize first.