Advanced Interface for B Estimation with Full Control

Source: R/get_B_user_interfaces.R

An advanced wrapper for get_B that provides full control over all parameters including cross-validation, outlier handling, and diagnostic integration. This function is designed for users who need fine-grained control over the estimation process.

get_B_advanced(
  training_data,
  target_MAF,
  training_trait = NULL,
  target_trait = NULL,
  target_SE = NULL,
  target_case_prop = NULL,
  method = "both",
  selection_criterion = "R2",
  custom_models = NULL,
  outlier_method = "both",
  outlier_action = "flag",
  cook_threshold = 4,
  biological_rules = NULL,
  cross_validation = FALSE,
  show_diagnostics = FALSE,
  show_outlier_details = FALSE,
  return_full = TRUE,
  verbose = 2
)

Arguments

training_data

Either:

  • A data.frame with columns: MAF, BETA or (P/P_mlog10, N), and optionally rsID, CHR, POS. P_mlog10 represents -log10(p-value) and is preferred for extreme p-values.

  • An object of class glow_training_data from prepare_B_training_data

target_MAF

Numeric vector of target MAF values for which to predict effect sizes. Values should be in (0, 1)

training_trait

Character string specifying training trait type: "binary" or "continuous". If NULL and training_data is a glow_training_data object, automatically extracted

target_trait

Character string specifying target trait type: "binary" or "continuous". If NULL (default), uses training_trait

target_SE

Numeric value or vector of standard errors for target data. Required when target_trait == "continuous" and p-value method is used

target_case_prop

Numeric value or vector specifying the proportion of cases in target case-control study. Required when target_trait == "binary" and p-value method is used

method

Character string specifying which method(s) to use:

  • "auto" (default): Automatic selection based on available data

  • "beta": Direct beta method only

  • "pvalue": P-value/Z-score method only

  • "both": Run both methods for comparison

selection_criterion

Character string specifying model selection criterion: "R2" (default), "adj_R2", or "CV_R2" (cross-validation). When cross_validation = TRUE, this is automatically set to "CV_R2"

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", "statistical" (Cook's distance), "biological" (implausible combinations), or "both" (default)

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. Default uses common variants (MAF > 0.05) with large effects (|effect| > 10)

cross_validation

Logical. If TRUE, enables leave-one-out cross-validation (LOOCV) for model selection and automatically sets selection_criterion = "CV_R2". Note: Currently implements LOOCV only; k-fold CV support is planned for a future release

show_diagnostics

Logical. If TRUE, automatically displays diagnostic plots after estimation (default: FALSE)

show_outlier_details

Logical. If TRUE, prints detailed outlier information (default: FALSE)

return_full

Logical. If FALSE, returns only B estimates. If TRUE (default), returns comprehensive result object with diagnostics

verbose

Integer controlling verbosity: 0=silent, 1=warnings, 2=detailed progress (default), 3=debug output

Value

If return_full = FALSE: Numeric vector of predicted effect sizes (B) for each variant in target_MAF.

If return_full = TRUE (default): A list with class "glow_B_estimate" containing comprehensive results including B estimates, fitted models, outlier detection results, method comparison (if applicable), and diagnostics. See get_B for full details.

Details

Advanced Features:

This function provides:

  • Full control over estimation method selection

  • Customizable model selection criteria (R2, adj_R2, CV_R2)

  • Cross-validation for robust model selection

  • Flexible outlier detection and handling

  • Automatic diagnostic display

  • Method comparison when both methods applicable

  • Custom model specification

Cross-Validation:

When cross_validation = TRUE:

  • Performs leave-one-out cross-validation (LOOCV)

  • Automatically sets selection_criterion = "CV_R2"

  • Provides more robust model selection for small samples

  • Increases computation time by factor of n_train

  • Note: K-fold CV support is planned for a future release

Diagnostic Integration:

When show_diagnostics = TRUE:

  • Displays 2x2 dashboard of diagnostic plots

  • Shows model fit, residuals, and method comparison

  • Automatically called after estimation completes

When show_outlier_details = TRUE:

  • Prints detailed information about detected outliers

  • Shows Cook's distance values

  • Reports biological rule violations

When to Use:

Use this function when:

  • You need full control over estimation parameters

  • You want to compare different methods

  • You need cross-validation for small samples

  • You want comprehensive diagnostics

  • You're developing or validating methods

For simpler use cases, use get_B_auto.

Computational Complexity

O(k * 8 * n_train + n_test) where k = n_train for LOOCV (1 if no CV), n_train = number of training variants, n_test = number of target variants. LOOCV evaluates all 8 candidate models n_train times.

See also

get_B for the main B estimation function get_B_auto for simplified automatic interface get_B_diagnostics for detailed diagnostic analysis plot.glow_B_estimate for visualization

Examples

if (FALSE) { # \dontrun{
# Example 1: Advanced estimation with cross-validation
result <- get_B_advanced(
  training_data = prepared_data,
  target_MAF = seq(0.01, 0.4, by = 0.01),
  target_case_prop = 0.5,
  method = "both",
  cross_validation = TRUE,  # Uses LOOCV
  show_diagnostics = TRUE,
  verbose = 2
)

# Access results
B_primary <- result$B
comparison <- result$model$comparison
model_stats <- summary(result$model$models$beta_method)

# Example 2: Custom outlier handling
result <- get_B_advanced(
  training_data = my_data,
  training_trait = "binary",
  target_MAF = target_mafs,
  target_case_prop = 0.5,
  outlier_method = "both",
  outlier_action = "remove",  # Actually remove outliers
  cook_threshold = 3,  # More stringent threshold
  show_outlier_details = TRUE
)

# Example 3: Custom model selection
custom_formulas <- list(
  formula(Y ~ poly(X, 3)),
  formula(Y ~ poly(X, 4))
)

result <- get_B_advanced(
  training_data = my_data,
  training_trait = "continuous",
  target_MAF = target_mafs,
  target_SE = 0.1,
  custom_models = custom_formulas,
  selection_criterion = "adj_R2",  # Prefer simpler models
  return_full = TRUE
)

# Example 4: Compare all selection criteria
criteria <- c("R2", "adj_R2", "CV_R2")
results <- lapply(criteria, function(crit) {
  get_B_advanced(
    training_data = my_data,
    training_trait = "binary",
    target_MAF = target_mafs,
    target_case_prop = 0.5,
    selection_criterion = crit,
    return_full = TRUE,
    verbose = 0
  )
})
names(results) <- criteria
} # }