tune_lucid: Wrapper for LUCID Model and Penalty Tuning

In LUCIDus: LUCID with Multiple Omics Data

Wrapper for LUCID Model and Penalty Tuning

Description

Fit a grid of LUCID models over candidate numbers of latent clusters K and (optionally) L1 penalties Rho_G, Rho_Z_Mu, and Rho_Z_Cov. The input format for K differs by lucid_model. For "early", use an integer vector (for example, 2:4). For "parallel", use a list of vectors/integers, one per layer (for example, list(2:3, 2:3, 2)). For "serial", use a nested list as required by the serial model.

Usage

tune_lucid(
  G,
  Z,
  Y,
  CoG = NULL,
  CoY = NULL,
  family = c("normal", "binary"),
  K,
  lucid_model = c("early", "parallel", "serial"),
  Rho_G = 0,
  Rho_Z_Mu = 0,
  Rho_Z_Cov = 0,
  verbose_tune = FALSE,
  ...
)

Arguments

G	Exposures, a numeric vector, matrix, or data frame. Categorical variables should be transformed into dummy variables.
Z	Omics data. If "early", an N by M matrix. If "parallel", a list of matrices (same N). If "serial", a list matching the serial model structure.
Y	Outcome, a numeric vector. Binary outcomes should be coded as 0/1.
CoG	Optional covariates for the G-to-X model.
CoY	Optional covariates for the X-to-Y model.
family	Outcome family: "normal" or "binary".
K	Candidate latent-cluster values in model-specific format.
lucid_model	LUCID model type: "early", "parallel", or "serial".
Rho_G	Scalar or vector penalty for exposure coefficients in the G-to-X model. CoG covariates are included unpenalized. Vector tuning is supported for "early" and "parallel". For "serial", only scalar inputs are supported.
Rho_Z_Mu	Scalar or vector penalty for cluster-specific Z means. Vector tuning is supported for "early" and "parallel". For "serial", only scalar inputs are supported.
Rho_Z_Cov	Scalar or vector penalty for cluster-specific Z covariance matrices. Vector tuning is supported for "early" and "parallel". For "serial", only scalar inputs are supported.
verbose_tune	Logical; print tuning progress if TRUE.
...	Additional arguments passed to estimate_lucid.

Value

A list holding the tuning table, every fitted candidate, and the selected model. The element names differ by lucid_model:

• "early": tune_list, res_model, best_model

• "parallel" and "serial": tune_K, model_list, model_opt

The tuning table has one row per grid point, in the order the candidates were fitted, and the fitted-model list is aligned with it by position. Its columns are the grid coordinates – K (one column per layer or stage for "parallel" and "serial") together with Rho_G, Rho_Z_Mu and Rho_Z_Cov – followed by BIC.

Selection is on BIC, minimised over the rows. For "early" and "parallel" this is the penalized BIC of Eq 18: the full parameter count is reduced by one for each variable deselected by the penalty, so a sparser fit is not charged for coefficients it has driven to zero. Penalties are not tuned for "serial" – only scalar penalties are accepted there – so a serial grid varies K alone. A candidate whose EM algorithm failed records NA and is skipped; if every candidate fails, an error is raised rather than a model returned. Ties are broken by taking the first minimising row.

Note that the returned optimum is the penalized fit itself. It is lucid, not this function, that refits the selected variables without a penalty – so estimates taken straight from best_model or model_opt here are shrunk towards zero.

Examples

## Not run: 
G <- sim_data$G
Z <- sim_data$Z
Y <- sim_data$Y_normal
tune_early <- tune_lucid(G = G, Z = Z, Y = Y, lucid_model = "early", K = 2:3)
tune_rho <- tune_lucid(
  G = G, Z = Z, Y = Y, lucid_model = "early", K = 2,
  Rho_G = c(0, 0.1), Rho_Z_Mu = c(0, 5), Rho_Z_Cov = c(0, 0.1)
)

## End(Not run)

LUCIDus documentation built on Sept. 3, 2026, 1:06 a.m.