Construct Dual-Stream Ratio Features

Creates pairwise ratio features by combining numerator genes (signal genes, typically differentially expressed) with denominator genes (batch-proxy genes from select_batch_associated_features()).

construct_dual_stream_ratios(x, numerators, denominators, log_transform = TRUE)

Arguments

x

Expression matrix (samples x genes). Should contain log-transformed expression values when log_transform = TRUE.

numerators

Character vector of numerator gene names (signal genes).

denominators

Character vector of denominator gene names (batch-proxy genes, typically from select_batch_associated_features()).

log_transform

Logical. If TRUE (default), compute log-ratios by subtraction (appropriate for log-transformed expression). If FALSE, compute raw ratios by division.

Value

A matrix of ratio features with dimensions (n_samples x (n_numerators * n_denominators)). Column names are formatted as "Numerator/Denominator".

Details

For log-transformed expression data, log-ratios are computed as: log(Numerator) - log(Denominator) = log(Numerator/Denominator)

This normalization strategy exploits the fact that batch effects often manifest as multiplicative scaling factors. By constructing ratios with batch-associated denominators, the batch-specific scaling cancels out, improving cross-cohort transferability.

The function creates all pairwise combinations of numerator and denominator genes. For n numerators and d denominators, this produces n*d ratio features.

Missing genes (not found in the input matrix) are silently filtered out. The function will error if no valid numerators or denominators remain after filtering.

See also

select_batch_associated_features() for selecting batch-proxy genes, select_de_features() for selecting signal genes, pairwise_col_diff() for an alternative all-pairs ratio construction.

Examples

if (FALSE) { # \dontrun{
# First select denominators
denom_result <- select_batch_associated_features(x, cohort, y)

# Get signal genes (e.g., from DE analysis)
numerators <- select_de_features(
  x_list = list(x1, x2),
  y_list = list(y1, y2),
  n_features = 30
)

# Construct ratio features
x_ratios <- construct_dual_stream_ratios(
  x = x,
  numerators = numerators,
  denominators = denom_result$features
)

# Use ratios for optimization
result <- optimize_panel(x_ratios, y, ...)
} # }