Block coordinate ascent for iterative model refinement. — block_coordinate

Generic framework for post-convergence refinement of fitted models. Repeatedly applies a block update (step_fn) to a fitted model, monitoring ELBO for convergence and stability. Both CS refinement (run_refine) and residual variance estimation (mvsusieR) are instances of block coordinate ascent over different parameter blocks.

Usage

block_coordinate_ascent(
  model,
  data,
  step_fn,
  max_iter = 100,
  tol = 0.001,
  verbose = FALSE
)

Arguments

model

Fitted model (e.g., from susie_workhorse or mvsusie_workhorse).

data

Data object passed to step_fn.

step_fn

A function with signature function(model, data, iter) that performs one block coordinate update. Must return a named list with elements:

model: (required) The updated model.
data: (optional) Updated data object, e.g. after changing residual variance. If NULL, the data is unchanged.
converged: (optional) Logical; if TRUE, stop iterating.
log_msg: (optional) Character string appended to verbose output.

max_iter

Maximum number of block ascent iterations (default 100).

tol

Convergence tolerance for relative ELBO change (default 1e-3).

verbose

If TRUE, print progress each iteration (default FALSE).

Value

The refined model, with model$converged set to TRUE or FALSE.

Details

Convergence is reached when either:

step_fn returns converged = TRUE (the block update signals no further improvement), or
the relative ELBO change falls below tol (ELBO stabilized across block updates).

A warning is issued if the ELBO decreases between iterations.