Opens the chunk's GDS once and runs the single-region GLOW test
(GLOWr::glow_region_test()) over every window in a regions table,
accumulating the always-on flat results table and the artifacts requested by
output_policy. This is the orchestration core of the sliding-window
scan; the workflow scripts wrap it per chunk.
glow_scan_chunk(
gds_path,
regions,
null_model,
pi_models,
pi_features,
reference_medians,
b_func = NULL,
b_model = NULL,
filter_spec,
ld_threshold = 0.9,
mac_threshold = 10L,
collapse_method = "mean",
use_spa = NULL,
z_scale = 1,
region_summary = FALSE,
output_policy,
staar_context = NULL,
progress_every = 0L,
progress_callback = NULL,
variant_index = NULL,
verbose = 0,
debug_errors = FALSE
)Path to the chunk's GDS/aGDS file. Opened read-only once and reused across windows (closed on exit).
A regions table (the GLOWr::define_regions_window()
shape: chr, start, end, and ideally label). All
rows must be on a single chromosome (chunks are per-chromosome, and
reference_medians is that chromosome's cache).
Passed through to GLOWr::glow_region_test() for every window (exactly one
of b_func/b_model). reference_medians is the chunk
chromosome's cached annotation medians.
Logical or NULL (default NULL). Threaded to
GLOWr::glow_region_test(): selects GLOW's single-variant score statistics
(NULL = auto: SPA for binary, standard for continuous; TRUE = force SPA,
binary only; FALSE = force standard). GLOW-only — STAAR is decided solely by
staar_context and always runs non-SPA. Validated up front (a
TRUE + continuous mismatch fails once, before the GDS is opened).
Numeric scalar (default 1). Threaded to
GLOWr::glow_region_test(): the M2 single-variant confounding correction
(1/sqrt(inflation_factor)) applied to each unit's Z before the GLOW
combination. z_scale = 1 is a no-op.
Logical (default FALSE). Pass-through to
GLOWr::glow_region_test(): when TRUE the flat table gains 7 region-summary
columns (n_collapsed_units, min_MAF, max_MAF,
min_MAC, max_MAC, min_p_standard, min_p_SPA)
placed after is_single. These are the gene scan's per-gene
diagnostic columns; the gene scans turn this on. Default FALSE leaves
the sliding/coding flat schema unchanged.
A glow_output_policy from glow_output_policy().
A STAAR context (see GLOWr::glow_region_test()) or NULL
(STAAR off).
Integer. If positive, emit a progress line every N windows (after window N, 2N, ...). Default 0L (off). Useful for long chunks where a silent log otherwise looks indistinguishable from a hang.
Optional function(msg) taking the formatted
progress string. Default NULL routes to message(). Pass a logger (e.g.
the workflow's log_msg) to write progress into the run's per-chunk log.
A glow_variant_index for gds_path from
GLOWr::build_variant_index(), or NULL (default), in which case the
engine builds it once after opening the GDS. Every region's lookup uses
it (see GLOWr::extract_variant_set()); a caller that already holds
the index for this file (as run_scan_unit does) passes it
to avoid a second build.
Integer (default 0). Threaded to the single-region test.
Logical (default FALSE). Threaded to
GLOWr::glow_region_test(): when TRUE, the message of an error row carries the
failing call and the stack of function names. Results unchanged.
A list with:
A data.frame, one row per non-skipped window, with the
flat-table schema: label, chr, start, end, midpoint;
n_variants, n_after_annotation, n_after_filter, n_after_ld,
n_after_collapse, cMAC (where n_after_annotation = after
QC+type+annotation, before MAF/MAC; in the coding analysis = the
per-category raw SNV count); is_single; (when
region_summary = TRUE) the 7 region-summary columns; the 16
GLOW_* columns; the 8 STAAR_* columns. 0-row (full schema)
for an empty chunk.
A named list of per-window evidence packets (keyed by window
label) for kept windows, or NULL when write_evidence is off.
A named list of full STAAR() outputs (keyed by
label) for windows where STAAR ran, or NULL when write_staar_detail
is off.
A named list of per-window result rows (keyed by
label) when write_result_objects is on, else NULL. (The single-region test
exposes the flat row, not the raw glow_test_result S3 object.)
A data.frame(label, message) of windows that errored
(0-row when none).
A 1-row data.frame: n_windows, n_ok,
n_skip_empty, n_staar_skip_single, n_error, runtime_secs.
STAAR on/off is decided solely by staar_context: non-NULL
turns STAAR on for every window (passed straight to the single-region test); NULL
leaves the 8 STAAR columns all-NA. output_policy$write_staar_detail
therefore requires a non-NULL staar_context, which is validated here
(the single cross-check that glow_output_policy() deliberately omits).
Per-window status handling (from the single-region test's $status):
"ok" / "staar_skip_single"A flat row is appended; STAAR
columns carry the single-region test's p-values ("ok" with STAAR on) or NA
(staar_skip_single, or STAAR off). Evidence / staar_detail /
result_objects are stashed if the policy enables them and the single-region test
produced them.
"skip_empty"Tallied; no row.
"error"Tallied; the message recorded in $errors; no
row. One window's error never aborts the chunk.
Empty chunk (every window skip_empty — common at fine scale on
sparse data): $results is a 0-row data.frame carrying the full schema,
so a downstream file-presence check stays uniform.