Prepare Data for GLOW Testing

Transforms a raw glow_variant_set (from extract_variant_set) into processed data ready for score statistics and GLOW variant-set tests. Handles allele flipping, B/PI computation, LD filtering, rare variant collapsing, and B/PI aggregation.

prepare_glow_input(
  variant_set,
  B = NULL,
  B_func = NULL,
  B_model = NULL,
  PI = NULL,
  PI_models = NULL,
  PI_features = NULL,
  reference_medians = NULL,
  ld_threshold = 0.9,
  ld_prefer_keep = "lower_maf",
  remove_lindep = TRUE,
  mac_threshold = 10L,
  collapse_method = "mean",
  max_group_size = Inf,
  verbose = 1
)

Arguments

variant_set

A glow_variant_set object from extract_variant_set.

B

Numeric vector (length = n_variants) of pre-computed B values, or NULL. Exactly one of B, B_func, B_model must be provided.

B_func

Function taking a numeric MAF vector and returning B values. For example: function(maf) sqrt(-0.14307 * log(maf * (1 - maf)) - 0.19522).

B_model

A glow_B_model object. Calls predict_B internally.

PI

Numeric vector (length = n_variants) of pre-computed PI values, or NULL. Exactly one of PI and PI_models must be provided.

PI_models

Either a list from load_PI_models or a character path to a model directory.

PI_features

Character vector of annotation column names to use for PI prediction. Required when using PI_models. If NULL, uses the default 16 curated PI training features from .default_PI_features().

reference_medians

Named numeric vector of chromosome-wide annotation medians for NA imputation (optional). From compute_annotation_medians. When provided, NA annotation values are imputed with these medians instead of per-gene column medians.

ld_threshold

Numeric (default 0.9). Correlation threshold for LD pruning.

ld_prefer_keep

Character (default "lower_maf"). Tie-breaking for LD pruning: "lower_maf", "higher_maf", or "first".

remove_lindep

Logical (default TRUE). Remove linearly dependent columns via QR decomposition.

mac_threshold

Integer (default 10). MAC threshold for rare variant collapsing. Set to 0 to disable collapsing.

collapse_method

Character (default "mean"). B/PI aggregation method for collapsed groups: "mean", "max", or "sum".

max_group_size

Numeric (default Inf). Maximum variants per collapsed group.

verbose

Integer (default 1). Verbosity level.

Value

A glow_input S3 object (see Details), or NULL if too few variants remain after filtering.

Details

The processing pipeline applies the following steps in order:

1. Validate inputs

2. Flip alleles to minor allele coding via flip_alleles

3. Compute B values (from vector, function, or model)

4. Compute PI values (from vector or ensemble models)

5. LD filtering via filter_variants_ld

6. Rare variant collapsing via collapse_rare_variants

7. Aggregate B/PI for collapsed groups via aggregate_B_PI

The returned glow_input object contains:

G

Numeric matrix (n x p_final) of processed genotypes

B

Numeric vector (length p_final) of B values

PI

Numeric vector (length p_final) of PI values

is_collapsed

Logical vector indicating collapsed groups

col_mapping

List mapping final columns to original column indices

ld_keep_idx

Integer vector (length n_after_ld); element j is the post-filter variant index (i.e., 1-based row index into the input variant set's variant_info) occupying post-LD column j. Chained with col_mapping, this traces every post-collapse test unit back to its post-filter raw variants.

region

Region information from the input variant set

n_original

Raw variant count in the region before any filtering (from variant_set$n_total_in_region)

n_after_filter

Variants remaining after Component 3's filter spec (QC, variant type, annotation mask, MAF/MAC), i.e., the variants entering prepare_glow_input

n_after_ld

Variants remaining after LD filtering

n_after_collapse

Variants remaining after rare-variant collapsing (= final number of columns in G)

cMAC

Cumulative MAC across all final columns

processing_log

Character vector of processing step descriptions

See also

extract_variant_set for creating the input variant set, flip_alleles, filter_variants_ld, collapse_rare_variants, aggregate_B_PI

Examples

if (FALSE) { # \dontrun{
# Extract variant set from GDS
vset <- extract_variant_set(gds, region, filter_spec)

# Method 1: Pre-computed B and PI vectors
result <- prepare_glow_input(vset, B = B_vec, PI = PI_vec)

# Method 2: B from function, PI from models
B_formula <- function(maf) sqrt(-0.14307 * log(maf * (1 - maf)) - 0.19522)
result <- prepare_glow_input(vset, B_func = B_formula,
                              PI_models = "path/to/models/")

# Method 3: B from trained model
result <- prepare_glow_input(vset, B_model = b_model, PI = PI_vec)
} # }