% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/utilities.R
\name{RoBMA_control}
\alias{RoBMA_control}
\alias{set_autofit_control}
\alias{set_convergence_checks}
\title{Control MCMC fitting process}
\usage{
set_autofit_control(
  max_Rhat = 1.05,
  min_ESS = 500,
  max_error = NULL,
  max_SD_error = NULL,
  max_time = list(time = 60, unit = "mins"),
  sample_extend = 1000,
  restarts = 10,
  max_extend = 10
)

set_convergence_checks(
  max_Rhat = 1.05,
  min_ESS = 500,
  max_error = NULL,
  max_SD_error = NULL
)
}
\arguments{
\item{max_Rhat}{maximum value of the R-hat diagnostic.
Defaults to \code{1.05}.}

\item{min_ESS}{minimum estimated sample size.
Defaults to \code{500}.}

\item{max_error}{maximum value of the MCMC error.
Defaults to \code{NULL}. Be aware that PEESE publication bias
adjustment can have estimates on different scale than the rest of
the output, resulting in relatively large max MCMC error.}

\item{max_SD_error}{maximum value of the proportion of MCMC error
of the estimated SD of the parameter.
Defaults to \code{NULL}.}

\item{max_time}{list with the time and unit specifying the maximum
autofitting process per model. Passed to \link[base]{difftime} function
(possible units are \code{"secs"}, \code{"mins"}, \code{"hours"},
\code{"days"}, and \code{"weeks"}).
Defaults to \code{list(time = 60, unit = "mins")}.}

\item{sample_extend}{number of samples to extend the fitting process if
the criteria are not satisfied.
Defaults to \code{1000}.}

\item{restarts}{number of times new initial values should be generated in case a
model fails to initialize. Defaults to \code{10}.}

\item{max_extend}{number of times after which the automatic fitting function is stopped.
Defaults to \code{10}.}
}
\value{
\code{set_autofit_control} returns a list of autofit control settings
including \code{max_Rhat}, \code{min_ESS}, \code{max_error},
\code{max_SD_error}, \code{max_time}, \code{sample_extend},
\code{restarts}, \code{max_extend}, and delegated
\code{check_indicators}.
\code{set_convergence_checks} returns a list with convergence thresholds
\code{max_Rhat}, \code{min_ESS}, \code{max_error}, \code{max_SD_error},
and delegated \code{check_indicators}.
}
\description{
\code{set_autofit_control} and \code{set_convergence_checks} control settings for the
autofit process of the MCMC JAGS sampler and specify termination criteria and convergence checks.
}
\details{
\code{set_autofit_control} controls the automatic model fitting process, determining when to
stop iterating based on convergence criteria. \code{set_convergence_checks} sets thresholds
for determining whether a model has converged adequately.

The autofit control manages computational resources by setting maximum time limits and
determining how many additional samples to draw if convergence criteria are not met.
The convergence checks determine the quality standards that fitted models must meet.
Autofit thresholds \code{max_Rhat}, \code{min_ESS}, \code{max_error},
\code{max_SD_error}, \code{max_time}, \code{restarts}, and
\code{max_extend} can be set to \code{NULL}; \code{sample_extend} must be a
positive integer.
Thresholds can be disabled with \code{NULL}; otherwise \code{max_Rhat} must be
at least 1, \code{min_ESS} and \code{max_error} must be nonnegative, and
\code{max_SD_error} must be between 0 and 1.
}
\examples{
# Set custom autofit control with shorter time limit
autofit_ctrl <- set_autofit_control(
  max_time = list(time = 30, unit = "mins"),
  sample_extend = 2000
)

# Set custom convergence checks with stricter criteria
conv_checks <- set_convergence_checks(
  max_Rhat = 1.01,
  min_ESS = 1000
)

\dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
  data(dat.lehmann2018, package = "metadat")

  fit <- RoBMA(
    yi                 = yi,
    vi                 = vi,
    data               = dat.lehmann2018,
    measure            = "SMD",
    autofit_control    = autofit_ctrl,
    convergence_checks = conv_checks
  )
}
}

}
\seealso{
\code{\link[=RoBMA]{RoBMA()}}
}
