LUCIDus (version 3.2.1)

predict_lucid: Predict Cluster Assignment and Outcome From a Fitted LUCID Model

Description

Predict cluster assignment and outcome using new data on G, Z, and optional Y. If g_computation = TRUE, prediction uses only the G-to-X path from the fitted model and returns counterfactual-style predictions under modified G. This function can also be used to extract latent cluster assignments when using the training data as input.

Usage

predict_lucid(
  model,
  lucid_model = NULL,
  G,
  Z = NULL,
  Y = NULL,
  CoG = NULL,
  CoY = NULL,
  response = TRUE,
  g_computation = FALSE,
  verbose = FALSE
)

Value

A list containing:

inclusion.p

Posterior inclusion probabilities for latent clusters (a matrix for "early"; a list by layer for "parallel" and "serial"). Columns are ordered by cluster, matching the row order of the model's res_Mu and res_Beta.

pred.x

Predicted latent-cluster labels (a numeric vector for "early"; a list by layer for "parallel" and "serial"), obtained as the maximum a posteriori column of inclusion.p. Labels run 1, ..., K, agreeing with Eq 21 and with the cluster names used by summary() and the mu and beta row names. Versions before 3.1.0 returned 0, ..., K - 1 here; code that compensated by adding one must drop that adjustment.

pred.y

Predicted outcome values. For binary outcomes, this is class labels when response = TRUE and probabilities when response = FALSE.

pred.z

Predicted omics means under g-computation mode (g_computation = TRUE); NULL otherwise.

Supplying Y makes the cluster prediction supervised: the outcome enters the posterior alongside G and Z, as it does during fitting. Omitting it predicts clusters from G and Z alone, which is what is wanted when the outcome is unavailable or must not inform the assignment.

Arguments

model

A model fitted and returned by estimate_lucid

lucid_model

Optional; "early", "parallel", or "serial". Auto-detected from class(model) when omitted (the normal case), so this rarely needs to be set explicitly -- it exists for backward compatibility with scripts written before auto-detection. A serial model must have at least two stages to be predicted; a single-stage serial model is a fully equivalent early or parallel model and should be fitted as one.

G

Exposures, a numeric vector, matrix, or data frame. Categorical variable should be transformed into dummy variables. If a matrix or data frame, rows represent observations and columns correspond to variables.

Z

Omics data, and required for every model type unless g_computation = TRUE. If "early", an N by M matrix. If "parallel", a list, each element i is a matrix with N rows and P_i features. If "serial", a list, each element i is a matrix with N rows and p_i features (or a list with two or more matrices with N rows and a certain number of features).

The requirement is not arbitrary: the E-step forms the posterior from the omics likelihood, so with no Z there is nothing to condition on. g_computation = TRUE is a different estimator, not a way around this -- it drops the omics and outcome terms and uses the exposure path alone -- which is why it is the one mode that accepts Z = NULL.

Y

Outcome, a numeric vector. Categorical variable is not allowed. Binary outcome should be coded as 0 and 1.

CoG

Optional, covariates to be adjusted for estimating the latent cluster. A numeric vector, matrix or data frame. Categorical variable should be transformed into dummy variables.

CoY

Optional, covariates to be adjusted for estimating the association between latent cluster and the outcome. A numeric vector, matrix or data frame. Categorical variable should be transformed into dummy variables.

response

If TRUE, when predicting binary outcomes, class labels (0/1) are returned using a 0.5 threshold. If FALSE, predicted probabilities are returned.

g_computation

If TRUE, prediction uses only information on G, making it the counterfactual mode: hold the fitted model fixed, vary G, and read off what the model implies. It is the only mode in which Z may be omitted, and it is also the only one that returns pred.z. Supplied Z and Y are ignored (with a printed notice) for "early", "parallel", and "serial", so results are unchanged by passing them.

verbose

A flag indicates whether detailed information is printed in console. Default is FALSE. Applies consistently to all three model types (early, parallel, serial).

Examples

# prepare data (a small subset keeps the example quick)
G <- sim_data$G[1:150, ]
Z <- sim_data$Z[1:150, ]
Y_normal <- sim_data$Y_normal[1:150, , drop = FALSE]

# fit lucid model
fit1 <- estimate_lucid(G = G, Z = Z, Y = Y_normal, lucid_model = "early", K = 2,
                       family = "normal", max_itr = 20, max_tot.itr = 50)

# prediction on training set (lucid_model is auto-detected from fit1's class)
pred1 <- predict_lucid(model = fit1, G = G, Z = Z, Y = Y_normal)
pred2 <- predict_lucid(model = fit1, G = G, Z = Z)

# g-computation style prediction using only G
pred_g <- predict_lucid(model = fit1, G = G, Z = NULL, g_computation = TRUE)