% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/diagnostics.R
\name{bdeb_diagnose}
\alias{bdeb_diagnose}
\title{MCMC Convergence Diagnostics}
\usage{
bdeb_diagnose(fit, pars = NULL)
}
\arguments{
\item{fit}{A \code{\link[=bdeb_fit]{bdeb_fit()}} object.}

\item{pars}{Character vector of parameter names to report.  Default:
all model parameters (excluding generated quantities such as
\code{log_lik}, \code{L_rep}, and \code{lp__}).}
}
\value{
An object of class \code{bdeb_diagnostics} with components
\code{n_divergent}, \code{n_max_treedepth}, \code{ebfmi}, \code{summary} (a
\code{\link[posterior:draws_summary]{posterior::summarise_draws()}} tibble), \code{pars}, and \code{model_type}.
}
\description{
Reports a comprehensive set of NUTS/HMC diagnostics following the
recommendations of Vehtari et al. (2021):
\describe{
\item{Divergent transitions}{Indicate that the numerical leapfrog
integrator encountered regions of high curvature.  Even a single
divergence can bias the posterior.  Remedy: increase \code{adapt_delta}.}
\item{Treedepth saturation}{The NUTS trajectory hit the maximum
allowed tree depth, meaning it could not find a U-turn.  Remedy:
increase \code{max_treedepth}.}
\item{E-BFMI}{Energy Bayesian Fraction of Missing Information.
Values below 0.3 indicate that the momentum resampling is
inefficient (Betancourt, 2016).}
\item{\eqn{\hat{R}}}{Split-\eqn{\hat{R}} convergence diagnostic.
Values > 1.01 indicate incomplete mixing across chains.}
\item{Bulk and tail ESS}{Effective sample size for the bulk and
tails of the posterior.  Values below 400 suggest that posterior
summaries may be unreliable.}
}
}
\details{
Returns a \code{bdeb_diagnostics} S3 object.  The object has dedicated
\link[=print.bdeb_diagnostics]{print()},
\link[=summary.bdeb_diagnostics]{summary()} and
\link[=plot.bdeb_diagnostics]{plot()} methods.  When called interactively
the print method is invoked automatically; assign the result
(\code{d <- bdeb_diagnose(fit)}) to suppress output.
}
\examples{
# Requires the CmdStan toolchain (Suggests: cmdstanr); gated on its
# availability and wrapped in \donttest{} so example("bdeb_diagnose")
# runs it when a toolchain is present, mirroring bdeb_fit().
\donttest{
if (requireNamespace("cmdstanr", quietly = TRUE) &&
    nzchar(tryCatch(cmdstanr::cmdstan_path(),
                    error = function(e) ""))) {
  data(eisenia_growth)
  dat <- bdeb_data(growth = eisenia_growth[eisenia_growth$id == 1, ])
  fit <- bdeb_fit(bdeb_model(dat, type = "individual"),
                  chains = 2, iter_warmup = 200, iter_sampling = 200,
                  refresh = 0)
  d <- bdeb_diagnose(fit)
  print(d)
  summary(d)
  plot(d, type = "rhat")
}
}
}
\references{
Vehtari, A., Gelman, A., Simpson, D., Carpenter, B. and
Bürkner, P.-C. (2021). Rank-normalization, folding, and localization:
an improved \eqn{\hat{R}} for assessing convergence of MCMC.
\emph{Bayesian Analysis}, 16(2), 667--718. \doi{10.1214/20-BA1221}

Betancourt, M. (2016). Diagnosing biased inference with divergences.
Stan case study. \url{https://mc-stan.org/users/documentation/case-studies/divergences_and_bias.html}
}
\seealso{
\code{\link[=print.bdeb_diagnostics]{print.bdeb_diagnostics()}}, \code{\link[=summary.bdeb_diagnostics]{summary.bdeb_diagnostics()}},
\code{\link[=plot.bdeb_diagnostics]{plot.bdeb_diagnostics()}}
}
