Select Features via RUV-4 Dual-Objective Scoring

Fits RUV-4 to jointly estimate outcome-associated signal and unwanted variation per feature, then ranks features by the ratio (or composite z-score) of discrimination strength to unwanted-variation sensitivity. Unlike cohort-label-based methods, RUV-4 estimates latent batch factors from negative control genes, making it suitable when cohort structure is ambiguous or confounders are continuous.

select_ruv_features(
  x_list,
  y_list,
  n_features = 50L,
  k = NULL,
  neg_control_method = c("empirical", "list"),
  neg_control_genes = NULL,
  neg_control_quantile = 0.75,
  iterate_controls = FALSE,
  max_iterations = 3L,
  scoring = c("ratio", "composite_z"),
  epsilon = 0.01,
  ebayes = TRUE,
  return_corrected = FALSE,
  assay = NULL
)

Arguments

x_list

A matrix-like object, SummarizedExperiment, or list of such objects. Rows represent samples and columns represent features.

y_list

A binary response aligned with x_list. Must be a factor with levels c("No", "Yes"). Provide a list when x_list is a list.

n_features

Maximum number of features to return (default 50).

k

Number of unwanted variation factors to estimate. When NULL (default), auto-selected via PCA on the negative control submatrix.

neg_control_method

Method for identifying negative control genes. "empirical" (default) selects non-significant genes from a pooled limma fit; "list" uses genes supplied via neg_control_genes.

neg_control_genes

Character vector of negative control gene names. Required when neg_control_method = "list".

neg_control_quantile

Quantile threshold for empirical control selection (default 0.75). Features with p-value above this quantile are selected as controls.

iterate_controls

If TRUE, iteratively refine the negative control set by re-running limma on RUV-corrected expression. Default FALSE.

max_iterations

Maximum number of control refinement iterations (default 3).

scoring

Scoring method. "ratio" (default) uses discrimination / (alpha_norm + epsilon); "composite_z" uses z(discrimination) + z(-alpha_norm).

epsilon

Small constant added to alpha_norm denominator in ratio scoring (default 0.01).

ebayes

If TRUE (default), apply empirical Bayes variance shrinkage via ruv::variance_adjust() for better-calibrated t-statistics.

return_corrected

If TRUE, include the RUV-4-corrected expression matrix in the output. Default FALSE.

assay

For SummarizedExperiment inputs, the assay name or index to extract prior to analysis.

Value

A list with components:

features

Character vector of selected feature names.

scores

Data frame with per-feature scoring metadata: feature, discrimination, alpha_norm, score, rank.

ruv_summary

List of RUV-4 diagnostics: k, n_controls, control_genes, W_outcome_cor, W_cohort_cor.

corrected

RUV-4-corrected expression matrix (only when return_corrected = TRUE).

settings

List of parameter values used.

Details

This method complements the existing cohort-label-based selectors (select_transferable_features(), select_discriminative_features()) by estimating latent unwanted factors from negative control genes rather than requiring explicit cohort labels. It is particularly useful when batch structure is ambiguous, confounders are continuous, or multiple sources of unwanted variation overlap.

The discrimination axis measures how strongly each feature associates with the outcome after accounting for unwanted variation (via the RUV-4 t-statistic). The alpha_norm axis measures each feature's total loading on the estimated unwanted factors (L2 norm across k factors). Features with high discrimination and low alpha_norm are prioritised.

See also

select_transferable_features(), select_discriminative_features(), select_de_features(), select_batch_associated_features() for the label-based counterpart that targets batch-associated genes directly.