Validates one or more fmri_jobs against the structural contract their
template implies, collecting issues per job. Intended to run on the driver
before run_jobs() / export_jobs().
Usage
preflight(x, check_files = FALSE, on_issue = c("warn", "error", "collect"))Arguments
- x
A single fmri_job or a list of them.
- check_files
Logical; for file-backed jobs, verify scan paths exist.
- on_issue
One of
"warn"(default),"error"(stop if any issue), or"collect"(return silently).
Value
Invisibly, an object of class fmri_preflight with an
$issues data frame (job_id, message) and $ok.
Details
Checks performed per job: template validity; every variable referenced by the
design formula and block is a column of that job's event table;
TR is positive; run lengths are consistent with the data
(matrix_frame: rows match sum(run_length);
nifti_frame: one run_length per scan file); nuisance regressor
rows match the total number of scans; and, when check_files = TRUE,
that file-backed scans exist on disk.
The design-column check uses all.vars() on the formula, so it is
deliberately conservative: a formula with a variable-valued HRF argument
(e.g. hrf(x, basis = my_basis)) may flag my_basis as a missing
column. Arguments of feature() are excluded, because those series live
in the formula environment rather than the event table. Event tables supplied
as file paths are not yet validated here.
Examples
tmpl <- fmri_template(onset ~ hrf(condition), ~ run)
job <- instantiate(tmpl, list(id = "sub-01",
scans = matrix(rnorm(80 * 2), 80, 2), TR = 2,
run_length = c(40, 40),
events = data.frame(onset = c(5, 45),
condition = factor(c("A", "B")),
run = c(1, 2))))
preflight(job)