Checks whether the supplied runjags-package model
satisfied convergence criteria.
Derived-draw views are refused with
BayesTools_draws_view_inference_unavailable (also
BayesTools_draws_view_unavailable); assess fit$original_fit.
JAGS_check_convergence(
fit,
prior_list = NULL,
max_Rhat = 1.05,
min_ESS = 500,
max_error = 0.01,
max_SD_error = 0.05,
add_parameters = NULL,
fail_fast = FALSE,
check_indicators = FALSE,
monitor = NULL,
allow_not_assessable = FALSE
)a 'BayesTools_fit' object created by JAGS_fit() with this
version of BayesTools. Fits without its parameter map and fit contract
(such as fits created by BayesTools 0.3.0) must be refitted: they stop with
an error of class BayesTools_refit_required (see
JAGS_validate_fit_contract()).
optional named list of prior distributions (names
correspond to the parameter names). When supplied, it must be the prior list
stored with fit (attr(fit, "prior_list")); another list is an
error. The classification of the fitted parameters always comes from the
convergence roles of the fit's coordinates (see Details), not from this
argument.
maximum R-hat error for the autofit function.
Defaults to 1.05. R-hat is the larger of the point estimate and
the upper confidence limit of the potential scale reduction factor
(coda::gelman.diag()), whereas the summary tables show the point
estimate; the Rhat column of the diagnostics attribute
holds the same value. With one chain, this criterion is skipped with
a warning; the remaining enabled criteria are still assessed.
minimum effective sample size. Defaults to 500.
maximum MCMC error. Defaults to 0.01.
maximum MCMC error as the proportion of standard
deviation of the parameters. Defaults to 0.05.
vector of parameter names that are excluded
from the default selection. Parameters named in monitor are
checked even when they are listed here. Automatic fitting in
JAGS_fit() and JAGS_extend() excludes nothing through this
argument; it uses the default selection described in Details.
whether the function should stop after the first failed convergence check.
whether model indicator variables should be included
in convergence checks. Binary indicators are checked as Bernoulli
occupancies and categorical indicators are checked separately for every
observed state. When monitor is supplied, eligible indicators are
added to that selection. Defaults to FALSE.
optional character vector selecting parameters for convergence
checks. A base name selects all of its indexed elements. A name that is not
available stops with an error of class BayesTools_parameter_not_found.
During automatic fitting, base names are checked against the monitored nodes
before sampling, whereas an indexed request such as "mu[2]" is
resolved against the fitted columns after the first run and fails then when
the element does not exist. Requests are
resolved against the monitored parameters that the summary tables show,
including derived and auxiliary ones that the default selection leaves out.
Private implementation nodes that the summary tables hide cannot be
requested.
NULL selects the default parameters; character() requests no
parameters.
whether requested sampled parameters with
undefined diagnostics may be ignored. Defaults to FALSE. A sampled
column that never changes when its chains are pooled, including a constant
model indicator, is not evidence of convergence and remains not assessable,
as does a diagnostic whose computation failed. A diagnostic computed on
draws that vary is a value, not an undefined result, and is assessed even
when it is infinite or zero: chains that are each constant but at different
values give an R-hat of Inf and an ESS of 0, which fail
max_Rhat and min_ESS whatever this argument is. Their MCMC
error (the standard error SD / sqrt(ESS) of an ESS of 0) is Inf, so
max_error and max_SD_error fail as well.
JAGS_check_convergence returns a boolean indicating whether
all requested, assessable parameters satisfy the enabled criteria. An
explicitly empty monitor returns logical(0) rather than
claiming convergence. When no parameters remain available (empty sample
columns and no structural parameters) or the selection is empty, the
function returns TRUE: there is nothing assessable, which is
treated as vacuously satisfied. The diagnostics attribute contains
one row per available parameter and classifies it as
"assessable", "structural_constant", "not_assessable",
"not_requested", or "not_checked" when fail_fast = TRUE
stops before reaching that parameter. Its Rhat column is the larger
of the point estimate and the upper confidence limit of the potential scale
reduction factor (see max_Rhat). The errors attribute carries
the failed checks: one message per failed criterion, with the most extreme
value, as in BayesTools 0.3.0 (for example "R-hat 1.234 is
larger than the set target (1.05)."), followed by the sentence
"Failing parameters: 'mu', 'tau'." that names the failing parameters
(the first five and the number of the others), and one message for every
parameter whose enabled diagnostics are not assessable.
JAGS_fit() assigns every fitted coordinate one convergence
role, stored in the convergence_role column of
parameter_coordinates() and derived from the declared model, never from
the draws:
"sampled"stochastic parameters, including the user's
add_parameters that depend on a stochastic node; checked by
default.
"indicator"declared model indicators of mixture,
spike-and-slab, and variance-allocation priors; checked with
check_indicators = TRUE.
"structural"declared constants: point priors, one-state
indicators, reference and fixed publication-weight bins, a p-hacking kind
shared by every mixture branch, the point total of an ordered prior and
the coefficients it fixes, unit correlation diagonals and Cholesky
constants, monitored fully observed data, and monitored deterministic
nodes (<- or =) whose ancestors in the model syntax are all
data or constants. They are reported as "structural_constant".
"derived"deterministic functions of sampled nodes that
BayesTools generates for formulas (such as random-effect correlation
matrices, their Cholesky factors, and derived latent effects or SDs) and
point priors whose location is an expression; checked only when named in
monitor.
"auxiliary"inclusion probabilities and the backend anchor
of models without monitored parameters, checked only when named in
monitor, and private implementation nodes that the summary tables
hide (such as Dirichlet gamma draws), which are never checked.
Mirrored two-sided publication-weight bins are hidden in the same way.
The default selection (monitor = NULL) consists of the sampled and
structural parameters, and of the indicators when check_indicators
is set. Automatic fitting in JAGS_fit() and JAGS_extend()
uses the same selection.
if (FALSE) { # \dontrun{
# simulate data
set.seed(1)
data <- list(
x = rnorm(10),
N = 10
)
data$x
# define priors
priors_list <- list(mu = prior("normal", list(0, 1)))
# define likelihood for the data
model_syntax <-
"model{
for(i in 1:N){
x[i] ~ dnorm(mu, 1)
}
}"
# fit the models
fit <- JAGS_fit(model_syntax, data, priors_list)
JAGS_check_convergence(fit)
} # }