Skip to contents

Fit a BACE (Bayesian Augmentation using Chained Equations) baseline

Source: R/fit_baseline_bace.R
fit_baseline_bace.Rd

Uses BACE to provide a phylogenetically-informed Bayesian baseline for all trait types. Returns imputed means and between-imputation SEs in latent scale, matching the interface of fit_baseline.

Usage

fit_baseline_bace(
  data,
  tree,
  splits = NULL,
  runs = 5L,
  nitt = 4000L,
  burnin = 1000L,
  thin = 10L,
  final_imp = FALSE,
  n_final = 15L,
  verbose = TRUE
)

Arguments

data

object of class "pigauto_data".

tree

object of class "phylo".

splits

list (output of make_missing_splits) or NULL.

runs

integer. Number of BACE chained imputation iterations (default 5L).

nitt

integer. MCMC iterations per model (default 4000L).

burnin

integer. Burn-in iterations (default 1000L).

thin

integer. Thinning rate (default 10L).

final_imp

logical. If TRUE, append BACE::bace_final_imp() after the chain and build mu / se from its final datasets instead of the chain datasets. Default FALSE (unchanged behaviour).

n_final

integer. Number of final imputation draws when final_imp = TRUE (default 15L, matching the BACE simulation study). Ignored when final_imp = FALSE. Small values undercover; BACE's own default is 50.

verbose

logical.

Value

A list with:

mu

Numeric matrix (n x p_latent), baseline means.

se

Numeric matrix (n x p_latent), between-imputation SEs.

Details

BACE runs chained MCMCglmm imputation: each trait is modelled as a response with all others as predictors, cycling through multiple MCMC runs. This provides a fully phylogenetic baseline for binary, categorical, and count traits — not just continuous ones.

The returned mu matrix is the mean across imputation runs; se is the between-imputation SD (capturing imputation uncertainty). Both are in latent scale (same as pigauto_data$X_scaled), so they can be passed directly to fit_pigauto as the baseline argument.

Which BACE datasets mu / se are built from

Two paths are available and they differ in what the returned se means.

final_imp = FALSE (default)

mu / se are computed from the runs datasets of the bace_imp() chain. Those are successive sweeps of one chained-equations chain, so they are autocorrelated by construction and still carry convergence transient. The resulting se is a cheap dispersion summary, not a calibrated imputation standard error, and it has no coverage guarantee.

final_imp = TRUE

BACE::bace_final_imp() is run on the fitted chain object and mu / se are computed from its n_final final datasets. Each of those runs starts independently from the converged chain, so they are proper multiple-imputation draws and se is a between-imputation SD in the Rubin (1987) sense. Expect this se to be larger than the default path's. Cost is n_final extra MCMC fits per trait on top of the chain.

The default is FALSE so that existing calls are unchanged. Note that this is a choice about which BACE datasets pigauto summarises; it is not a correction to the default path's arithmetic.

BACE::bace_final_imp() is only available in recent BACE versions. If it is missing, final_imp = TRUE errors with an upgrade hint rather than silently falling back.

The final phase is also less robust than the chain phase: each draw refits MCMCglmm from the converged data and can hit “Mixed model equations singular” on data the chain handled without complaint. When that happens final_imp = TRUE errors rather than quietly returning chain averages, because a caller who asked for proper MI draws should not silently receive improper ones. Raising nitt, using fewer traits, or falling back to final_imp = FALSE are the available responses.

Examples

if (FALSE) { # \dontrun{
bl_bace <- fit_baseline_bace(pd, tree, splits = spl)
fit <- fit_pigauto(pd, tree, splits = spl, baseline = bl_bace)
} # }