Train a B Estimation Model from Training Data

Trains a regression model to predict allelic effect sizes (B) from minor allele frequency (MAF), without requiring target data. This function supports two estimation methods: (1) direct beta method using effect sizes, and (2) p-value/Z-score method using a trait-independent h-squared transformation. The trained model can be applied to new MAF values via predict_B.

This function performs the training step only. It does not produce B predictions – use predict_B for that. This separation enables "train once, predict many times" workflows.

train_B_model(
  training_trait,
  training_MAF,
  training_BETA = NULL,
  training_P = NULL,
  training_P_mlog10 = NULL,
  training_N = NULL,
  method = "auto",
  selection_criterion = "R2",
  custom_models = NULL,
  outlier_method = "none",
  outlier_action = "flag",
  cook_threshold = 4,
  biological_rules = NULL,
  show_model_selection = TRUE,
  verbose = 1
)

Arguments

training_trait: Character string or NULL, trait type of training data. Can be "binary", "continuous", "mixed" (when training data contains both trait types), or NULL (unspecified). When "mixed" or NULL, only the p-value/Z-score method is available since the direct beta method requires a single trait type
training_MAF: Numeric vector of minor allele frequencies from training data, used to fit the B prediction model. Values should be in (0, 0.5]. Values > 0.5 are automatically folded to 1 - MAF with a warning
training_BETA: Numeric vector of effect sizes (regression coefficients) from training data. Required for direct beta method. Should have the same length as training_MAF
training_P: Numeric vector of p-values from training data. Used for p-value/Z-score method. Values should be in (0, 1). Either training_P OR training_P_mlog10 should be provided (not both)
training_P_mlog10: Numeric vector of -log10 transformed p-values from training data. Use this instead of training_P when dealing with extremely small p-values to avoid numerical underflow
training_N: Numeric vector of sample sizes from training data. Required for p-value/Z-score method
method: Character string specifying which method to use: "auto" (default), "beta", "pvalue", or "both". "auto" uses both methods when the beta method is possible and p-value data is available, otherwise uses the available method. "both" runs both methods for comparison
selection_criterion: Character string specifying model selection criterion: "R2" (default), "adj_R2", or "CV_R2". See select_best_model for guidance on choosing a criterion
custom_models: Optional list of custom model formulas to include in candidate model set. Each element should be a formula object
outlier_method: Character string specifying outlier detection method: "none" (default), "statistical" (Cook's distance), "biological" (implausible MAF-effect combinations), or "both"
outlier_action: Character string specifying action for detected outliers: "flag" (default, report but don't remove) or "remove" (exclude from analysis)
cook_threshold: Numeric threshold multiplier for Cook's distance outlier detection (default: 4). Outliers are defined as points with Cook's D > cook_threshold/n
biological_rules: Optional list of custom rules for biological outlier detection
show_model_selection: Logical. If TRUE (default), prints model selection comparison table. Set to FALSE to suppress in loops
verbose: Integer controlling verbosity: 0=silent, 1=warnings (default), 2=info messages, 3=debug output

Value

An object of class glow_B_model containing:

method_used: Character: "beta_method", "pvalue_method", or "both"
models: List with beta_method and/or pvalue_method containing the best fitted lm objects
all_models_info: List with beta_method and/or pvalue_method containing complete model comparison info
outliers: List with outlier detection results
training_summary: List with n_original, n_used, n_outliers_detected, trait_type
training_data: List with MAF, BETA, P, P_mlog10, N, trait (retained for diagnostics)
comparison: List with training-time model comparison when method="both": selection_criterion, criterion values, and method_selected
selection_criterion: The model selection criterion used

Details

Two Estimation Methods:

Method 1: Beta Method (beta_method)

Uses training_BETA values directly
Fits regression model: $BETA^2 \sim f(MAF)$
Best when training and target have the same trait type

Method 2: P-value Method (pvalue_method)

Converts p-values to trait-independent h-squared
Fits regression model: $h^2 \sim f(MAF)$
Can transfer information between different trait types

Method Selection Logic:

method="auto": Uses "both" if beta method possible + p-value data available; otherwise uses the available method
method="beta": Only beta method (requires training_BETA)
method="pvalue": Only p-value method (requires training_P/training_N)
method="both": Runs both, compares at training time using selection_criterion

Training-Time Comparison (method="both"):

When both methods are run, the function compares model quality using the selection_criterion (R2/adj_R2/CV_R2) applied to each method's best model. The method with the better criterion value is recorded as comparison$method_selected. Note that the two methods model different response variables (BETA^2 vs h^2), so this comparison reflects which transformation better captures the MAF-effect relationship.

Full prediction-based comparison (correlation, RMSE between B vectors) requires target data and is performed by get_B after calling predict_B.

Computational Complexity

O(8 * n_train) where n_train = length(training_MAF) (fitting 8 models). With CV_R2 criterion: O(8 * n_train^2) due to leave-one-out CV.

Examples

if (FALSE) { # \dontrun{
# Example 1: Train with beta method
set.seed(123)
training_MAF <- runif(50, 0.001, 0.3)
training_BETA <- sqrt(0.5 * training_MAF * (1 - training_MAF)) * 0.1

b_model <- train_B_model(
  training_trait = "binary",
  training_MAF = training_MAF,
  training_BETA = training_BETA,
  method = "beta"
)
print(b_model)

# Predict B for new MAF values
B_values <- predict_B(b_model, target_MAF = c(0.01, 0.05, 0.1))

# Example 2: Train with p-value method
training_P <- runif(50, 1e-8, 0.01)
training_N <- rep(5000, 50)

b_model_pval <- train_B_model(
  training_trait = "binary",
  training_MAF = training_MAF,
  training_P = training_P,
  training_N = training_N,
  method = "pvalue"
)

# Example 3: Train with both methods
b_model_both <- train_B_model(
  training_trait = "binary",
  training_MAF = training_MAF,
  training_BETA = training_BETA,
  training_P = training_P,
  training_N = training_N,
  method = "both",
  verbose = 2
)

# Example 4: Save and reload
save_B_model(b_model, "my_model.rds")
loaded <- load_B_model("my_model.rds")
} # }