Compute the marginal likelihood of a brma model using bridge sampling and store the result in the object.
Usage
# S3 method for class 'brma'
add_marglik(
object,
parallel = NULL,
cores = NULL,
repetitions = 1L,
method = c("normal", "warp3"),
maxiter = 10000L,
silent = TRUE,
...
)Arguments
- object
a brma model object.
- parallel
whether bridge-density evaluations run in parallel. The default,
NULL, inherits the setting used to fitobject.- cores
number of bridge-sampling worker processes. The default,
NULL, inherits the fitted core count and is capped byRoBMA.get_option("max_cores"). It is used only whenparallel = TRUE.- repetitions
number of independent bridge-sampling repetitions.
- method
bridge transformation; either
"normal"or"warp3".- maxiter
maximum number of bridge iterations per repetition.
- silent
whether bridge-sampling progress is suppressed. The typed iteration-limit diagnostic remains visible even when
silent = TRUE.- ...
reserved for future use. Unused arguments produce a warning.
Details
The marginal likelihood is computed using the bridgesampling package
via the BayesTools::JAGS_bridgesampling wrapper. The result is stored
in the object and can be extracted using bridge_sampler.brma.
Proposal draws use the seed stored with the fit. When that seed is non-NULL,
the caller's random-number state is restored after the call; a NULL fit seed
uses and advances the caller's random-number stream.
A finite bridge estimate remains available when observed iteration counts
exceed maxiter. The stored result's success records finite
availability, not certified convergence. Its optional
iteration_limit_exceeded is TRUE for observed excess,
FALSE for complete counts without excess, and NA or absent
when telemetry is unavailable. Counts may include upstream retries.
Observed excess raises BayesTools_marglik_iteration_limit, inheriting
from BayesTools_marglik_diagnostic, under either silent setting.
Inspect print(object[["marglik"]]) and its repetition diagnostics.
bridge_sampler(object) returns the original upstream bridge object;
it does not promise the stored wrapper's optional telemetry field.
Product-space model-averaging objects (BMA.norm, BMA.glmm,
BMA.mv, RoBMA, and RoBMA.mv) do not expose a
bridge-sampling marginal likelihood;
use predictive comparison methods such as loo.brma instead.
For a single model whose bridge parameters are all fixed by point priors,
the log marginal likelihood is evaluated exactly at those fixed values;
no bridge-sampling repetitions are required.
For brma.mv() known-V objects, bridge sampling evaluates the
joint likelihood corresponding to the fitted known-V backend, not the
conditional estimate-wise target used by LOO/WAIC diagnostics. Sampled
Gaussian location random-effect blocks are integrated exactly during bridge
evaluation as their draw-specific \(ZGZ'\) covariance. Their SD,
allocation, and correlation parameters remain bridge coordinates; only the
standardized latent effects are removed. This is a reparameterization of the
same marginal-likelihood target, not a likelihood approximation. Fitted
estimate-level marginalized blocks remain in the diagonal row variance.
For Gaussian models fitted with the specialized cluster interface,
the standardized cluster effects are likewise integrated exactly. The bridge
retains total heterogeneity and its allocation while evaluating the implied
diagonal-plus-cluster-rank-one covariance, including row-specific scale
regression and likelihood weights.
Selection models retain every context that the fitted model conditions on,
including its normalized prior, and integrate only the Gaussian sources
declared by that model. The likelihood uses the same full publication events
and integration plan as fitting. A context integrated before selection
normalization cannot be replaced by a retained-context parameterization.
With known_sampling_variance = "condition", the bridge retains the
independent Gaussian augmentation coordinates and their normalized priors.
The complete sampling error and random effects are reconstructed for each
proposed bridge state before evaluating its selection normalizer.
A non-finite bridge repetition raises a
RoBMA_marglik_repetition_failure error, inheriting from
RoBMA_marglik_error. Its parent retains the complete upstream
condition, including the failed repetitions table. Increase
maxiter when a failed repetition reached its iteration limit;
otherwise inspect the posterior samples and priors for non-finite densities.
Fitting more posterior draws (for example with a larger sample or
update()) may help in either case. These actions do not guarantee
that the diagnostics will pass.
A checked posterior sample that cannot form a full-rank bridge proposal
raises RoBMA_marglik_rank_deficiency, inheriting from
RoBMA_marglik_error. Its unchanged upstream parent and exposed
reason, rank, n_coordinates, n_draws, and
dependent_coordinates describe the observed sample. For
reason = "insufficient_draws", fit more posterior draws with a larger
sample or update(); dependence may persist. For
reason = "dependent_coordinates", inspect the parameterization and
sampling; more draws alone need not resolve dependence. The message names the
first reported pivot coordinates; they identify one dependent set, not
uniquely faulty nodes.
The stored result records an identity of the data, weights, priors, and
model it was computed for. bridge_sampler(), logml(),
bf(), and post_prob() refuse a stored result that no longer
matches the object, or that an earlier RoBMA version stored, with an error of
class RoBMA_marglik_stale (inheriting from RoBMA_marglik_error);
recompute it with add_marglik(). update(slab = ) keeps it, and
extending the fit with update() recomputes or drops it.
Examples
if (FALSE) { # \dontrun{
if (requireNamespace("metadat", quietly = TRUE)) {
data(dat.lehmann2018, package = "metadat")
fit <- brma(yi = yi, vi = vi, data = dat.lehmann2018, measure = "SMD")
fit <- add_marglik(fit)
bridge <- bridge_sampler(fit)
print(bridge)
logml(fit)
}
} # }