Tests one genomic region (a gene or a sliding window) with the GLOW variant-set procedure, optionally adding a STAAR-O test and an evidence packet. Both a gene-centric scan and a sliding-window scan call this function once per region, so the two analyses run identical per-region code.
glow_region_test(
gds,
region,
filter_spec,
null_model,
pi_models,
pi_features,
reference_medians,
b_func = NULL,
b_model = NULL,
ld_threshold = 0.9,
mac_threshold = 10L,
collapse_method = "mean",
use_spa = NULL,
z_scale = 1,
staar = NULL,
return_evidence = FALSE,
region_summary = FALSE,
variant_index = NULL,
verbose = 0,
debug_errors = FALSE
)An open SeqVarGDSClass connection. The orchestration
layer opens the GDS once per chunk and reuses it across windows, so this
function does not open or close it. (A file path also works because
extract_variant_set accepts one, but the intended contract is
an open connection to avoid re-opening the GDS in the hot loop.)
A list or single-row data.frame with chr, start,
end, and (optionally) label — the row shape produced by
define_regions_window / define_regions_gene.
A glow_variant_filter from
variant_filter or coding_filter.
A fitted glow_null_model from
fit_null_model. Its sample_id drives sample
extraction/ordering and its trait drives the score-stat dispatch.
A loaded PI ensemble (from load_PI_models) or a
model-directory path, passed to prepare_glow_input as PI_models.
Character vector of annotation column names for PI
prediction. Also the annotations extracted from the GDS, so any
staar$anno_cols must be a subset of these.
Named numeric vector of chromosome-wide annotation
medians (from compute_annotation_medians) for NA imputation in
both PI prediction and STAAR annotation imputation.
Function mapping a numeric MAF vector to B values. Mutually
exclusive with b_model.
A glow_B_model (from train_B_model /
load_B_model). Mutually exclusive with b_func.
Numeric (default 0.9). LD-pruning correlation threshold.
Integer (default 10). MAC threshold for rare-variant collapsing.
Character (default "mean"). B/PI aggregation method for collapsed groups.
Logical or NULL (default NULL). Selects GLOW's single-variant
score statistics: NULL auto-detects (SPA for binary, standard for
continuous); TRUE forces SPA (binary only — a non-binary trait errors);
FALSE forces standard for any trait. GLOW-only: every GLOW family test
combines the chosen Z, while STAAR (if requested) runs its own, always
non-SPA, path. SPA is recommended for rare variants / unbalanced
case-control; see the guidance in getZ_marg_score.
Numeric scalar (default 1). Single-variant confounding
correction (method M2) applied to every unit's Z before the GLOW
combination: z_scale = 1/sqrt(inflation_factor), where
inflation_factor is the single-variant genomic inflation (e.g. the
LD Score regression intercept from ldsc_regression). It
multiplies the score-statistic Z-scores that glow_test
combines (and the evidence-packet Z_standard/Z_SPA); the
correlation M_Z is invariant to a uniform Z rescaling and
M_s/s0 are left untouched. z_scale = 1 is a no-op.
STAAR context, or NULL (default) for GLOW only. When non-NULL, a
list with null_model (a STAAR::fit_null_glm object),
anno_cols (character vector of annotation column names, a subset of
pi_features), and rare_maf_cutoff (numeric).
Logical (default FALSE). If TRUE, build and return the
per-region evidence packet (post-filter variant table + per-unit
B/PI/Z/weights), and request weights from glow_test.
Logical (default FALSE). If TRUE, splice 7 region-level
diagnostic columns into $result (after cMAC, before the
GLOW_* p-values): n_collapsed_units (number of collapsed test
units), min_MAF/max_MAF and min_MAC/max_MAC
(MAF/MAC range over the post-collapse test units), and
min_p_standard/min_p_SPA (smallest per-unit single-variant
p-value on the standard / SPA channel; min_p_SPA is NA unless
the SPA Z exists, i.e. a binary trait). These are standard per-region
diagnostic columns. They are cheap (computed from input$G and
the score-stat Z this function already holds) and do not require
return_evidence. Default FALSE leaves the canonical row unchanged.
A glow_variant_index for gds from
build_variant_index, or NULL (default). Passed to
extract_variant_set: with it, the region's records are found
by binary search on the index instead of a read of the chromosome's variant
table, which is what makes a scan over thousands of regions cheap on a
whole-genome-sequencing chromosome. The orchestration layer builds it once
per chunk. Without it the extraction builds one for this call.
Integer (default 0). Verbosity threaded to the underlying calls.
Logical (default FALSE). When TRUE, the message of a
status = "error" result carries, after the error's own message, the call that
signaled it and the names of the functions on the stack from this function down to
the signal ("<message> [call: <call>. stack: f1 > f2 > ... > fk]"), so that a
failing region of a scan can be located without rerunning it. The status and every
result column are the same as with FALSE.
A list with components:
A single-row data.frame (the
as.data.frame.glow_test_result shape: region columns, variant
counts, and the GLOW p-value columns; plus the 7 region-summary columns
spliced after cMAC when region_summary = TRUE), or NULL when
status %in% c("skip_empty", "error").
The evidence packet, or NULL (non-NULL only when
return_evidence = TRUE and status kept a row).
A named list of the 8 STAAR family-omnibus p-values when a
staar context was supplied (all-NA on staar_skip_single or a
STAAR error), or NULL when STAAR was off.
The full STAAR::STAAR output, or NULL.
One of "ok", "skip_empty", "staar_skip_single",
"error" (see Details).
A diagnostic message: the error message when
status == "error", a STAAR error note when STAAR failed for a
non-skip reason (GLOW still succeeded), else NULL.
The processing pipeline, for one region, is:
extract_variant_set on the open gds (skip if the
region has no qualifying variants).
prepare_glow_input with B-source dispatch (exactly one
of b_func / b_model); LD-prune + rare-variant collapse
(skip if nothing survives).
compute_score_stats, honoring use_spa (default
NULL = auto: SPA for binary, standard for continuous). For a binary trait
the complementary single-variant Z is also computed for the evidence
packet (the SPA complement only when return_evidence = TRUE).
glow_test (omnibus), with weights returned when
return_evidence = TRUE.
If staar is non-NULL, STAAR::STAAR on the
post-filter / pre-LD-prune / pre-collapse genotype matrix
(vset$G), with missing annotations median-imputed against
reference_medians (STAAR does its own LD handling and collapsing).
If return_evidence = TRUE, a per-region evidence packet.
B-source contract. Exactly one of b_func, b_model must
be non-NULL (mirrors prepare_glow_input). Supplying both or
neither is a caller error and throws.
Status semantics. The caller reads $status rather than
string-matching a message:
"ok"GLOW produced a result row ($result non-NULL).
STAAR, if requested, either ran (p-values in $staar) or failed for
a non-skip reason ($staar all-NA, message in $message);
either way GLOW succeeded.
"skip_empty"extract_variant_set or
prepare_glow_input returned NULL (no qualifying variants).
$result is NULL.
"staar_skip_single"GLOW produced a row but STAAR could not run
(fewer than 2 rare variants — STAAR's design-intended exclusion).
$result is the GLOW row; $staar is all-NA.
"error"An unexpected error in the GLOW path. $result
is NULL and $message holds the error message.
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
Li, X., Li, Z., Zhou, H., et al. (2020). Dynamic incorporation of multiple in silico functional annotations empowers rare variant association analysis of large whole-genome sequencing studies at scale. Nature Genetics, 52, 969-983. doi:10.1038/s41588-020-0676-4
Li, Z., Li, X., Zhou, H., et al. (2022). A framework for detecting noncoding rare-variant associations of large-scale whole-genome sequencing studies. Nature Methods, 19, 1599-1611. doi:10.1038/s41592-022-01640-x
if (FALSE) { # \dontrun{
library(SeqArray)
gds <- seqOpen("chr22_essentialdb.gds")
on.exit(seqClose(gds))
region <- list(chr = "22", start = 16570000L, end = 16670000L,
label = "chr22:16570000-16670000")
spec <- variant_filter(rare_maf_cutoff = 0.5, variant_type = "SNV")
pi <- load_PI_models("path/to/piModels/")
feats <- c("cadd_phred", "linsight", "fathmm_xf")
meds <- compute_annotation_medians(gds, feats, spec,
sample_id = null_model$sample_id)
res <- glow_region_test(
gds, region, spec, null_model,
pi_models = pi, pi_features = feats, reference_medians = meds,
b_func = function(maf) sqrt(-0.14307 * log(maf * (1 - maf)) - 0.19522),
ld_threshold = 0.95, mac_threshold = 11L)
res$status
res$result
} # }