Run GLOW Variant-Set Tests

Executes GLOW association tests on a set of variants using pre-computed marginal score statistics and per-variant B (effect size) and PI (variant-importance score) parameters. Returns a structured S3 result object that can be printed, converted to a data.frame, or further processed.

glow_test(
  marg_score_stats,
  B,
  PI,
  region_info = NULL,
  variant_summary = NULL,
  tests = "omni",
  test_specs = NULL,
  include_snv_cct = TRUE,
  return_weights = FALSE,
  verbose = 1,
  ...
)

Arguments

marg_score_stats

List from compute_score_stats or getZ_marg_score, containing Zscores, M_Z, M_s, and s0.

B

Numeric vector (length p). Per-variant effect size parameter.

PI

Numeric vector (length p). Per-variant variant-importance score in \([0, 1]\).

region_info

List with optional elements chr, start, end, label. Region metadata attached to output.

variant_summary

List with variant count information (optional). Common fields: n_original, n_after_filter, n_after_ld, n_after_collapse, cMAC.

tests

Character. Which tests to run: "omni" (default) runs the full omnibus pipeline, or a character vector subset of c("burden", "skat", "fisher") for individual tests.

test_specs

List of test specification lists (default: NULL uses default_test_specs). Only applies when tests = "omni".

include_snv_cct

Logical. If TRUE (default), include SNV-level CCT and final omnibus CCT in the output. Only applies when tests = "omni".

return_weights

Logical (default FALSE). If TRUE and tests = "omni", attach the per-test-unit weight matrix used by the GLOW test to the result as weights (rows: weight schemes; columns: variants). In the single-variant edge case, attaches a n_schemes x 1 matrix of 1s with the schema's scheme rownames so downstream consumers can rely on a uniform shape.

verbose

Integer. Verbosity level (default 1). Set to 0 for silence.

...

Additional arguments passed to underlying test functions (e.g., method, nsim for GFisher).

Value

A glow_test_result S3 object (list) with components:

pvalues

Named numeric vector of p-values.

statistics

Named numeric vector of test statistics, same names as pvalues.

region_info

The region_info argument, passed through.

variant_summary

The variant_summary argument, passed through.

settings

List with tests_run recording which tests were run.

raw

List of raw output from the underlying test functions.

Details

This function is the primary user-facing entry point for running GLOW tests. It wraps the underlying GLOW_Omni, GLOW_Burden, GLOW_SKAT, and GLOW_Fisher functions, adding input validation, structured output, and region metadata.

Test Modes:

tests = "omni" (default)

Runs GLOW_Omni, which computes all test statistics. With default specs: 5 SKAT, 3 Burden, 5 Fisher, BSF omnibus, SNV-level CCT, and final omnibus CCT (16 total).

tests = c("burden", "skat", "fisher")

Runs individual tests only. Each test returns its own set of p-values (varying number of weight schemes). Useful when only specific test types are needed.

P-value Naming: In omnibus mode, p-value names are derived dynamically from the row names produced by run_bsf_tests(), with a GLOW_ prefix added. With default test specs, this produces 16 names: GLOW_SKAT_BE_N, GLOW_Burden_BE, GLOW_Fisher_BE_N, GLOW_BSF_Omni, GLOW_SNV_CCT, GLOW_Omni, etc.

Custom Test Specs: Pass test_specs to configure which test families are run and how they are weighted. See default_test_specs for the format.

Single-Variant Handling: When only one variant remains (p = 1), all variant-set tests reduce to the marginal single-SNV test. The marginal p-value is assigned to all output slots, with names derived from generate_test_names().

References

Zhang, H., Liu, M., Landers, J. E., and Wu, Z. (2026). Integrated weighted association test with application to genetic association studies. The Annals of Applied Statistics, 20(3), 2074-2097. doi:10.1214/26-AOAS2223

See also

GLOW_Omni for the underlying omnibus test default_test_specs for the test specification format GLOW_Burden, GLOW_SKAT, GLOW_Fisher for individual tests

Examples

if (FALSE) { # \dontrun{
# Simulate inputs
set.seed(42)
p <- 10
marg_stats <- list(
  Zscores = rnorm(p),
  M_Z = diag(p),
  M_s = diag(p),
  s0 = 1
)
B <- rep(0.5, p)
PI <- runif(p, 0.1, 0.9)

# Run omnibus test (default: 16 p-values)
result <- glow_test(marg_stats, B, PI,
                    region_info = list(label = "GENE1", chr = "22"))
print(result)
as.data.frame(result)

# Custom 2-family spec
my_specs <- list(
  list(family = "SKAT", g = function(x) x^2, df = 1),
  list(family = "Burden", g = function(x) x, df = Inf)
)
result2 <- glow_test(marg_stats, B, PI, test_specs = my_specs)
} # }