Runs each variable's rendered code block ([render_variable()]) inside a fresh environment with baseenv() as parent and reports a per-variable status. This is the programmatic replacement for the demo glue loops: idempotent, re-runnable, and safe to call on an IR that mixes executable variables with `needs_human` review variables.
Contract: - `sources` must contain the base for the target dataset under the name `base` (preferred) or under the target dataset name lower-cased (e.g. `adsl` for target `ADSL`). It is the one-row-per-subject starting point and is assigned into the execution environment as the target dataset object. - Every other element of `sources` is assigned into the environment under its list name, e.g. `list(base = dm, ex = ex, vs = vs_bds)` creates `ADSL <- base`, `ex`, `vs_bds`. Step args like `on = "ex"` or `dataset_add = "ex"` must match those names. A `codelist_var` step needs a metacore object named `mc`; pass it as `sources$mc` (typically a [metacore::select_dataset()] subset of [mock_metacore()] output). - Each variable executes transactionally: errors roll back all its changes to target and source datasets, and dependent variables report ERROR. - Before each step's code runs, an idempotency guard removes columns (and computed PARAMCD rows) that this variable's steps would create, from the objects those steps land on - including imputation temp columns and their flag columns on foreign datasets. Calling `execute_ir()` twice therefore yields identical output, and a partially failed run can be retried without "already exists" warnings or stale values.
The `admiralagent` layer templates render bare `exprs()`/`params()` helpers; if `rlang`/`admiral` are installed these are pre-assigned into the environment, otherwise the affected variables report `ERROR`.
Usage
execute_ir(
ir,
sources = list(),
variables = NULL,
quiet = TRUE,
log_file = aa_log_file()
)Arguments
- ir
Non-empty list of `aa_variable_ir` objects (as produced by [classify_variables()]).
- sources
Named list of source data objects; must contain `base` (or the lower-cased target dataset name). See the Description for the full contract.
- variables
Optional character vector restricting execution to these spec variables (default all). Only selected variables run; required prior results must be supplied in sources. Unknown names are rejected.
- quiet
If `TRUE` (default), warnings from the evaluated blocks are suppressed and nothing is printed; if `FALSE`, warnings pass through and the status table is printed.
- log_file
Audit log destination. Logging is ON by default and writes one hash-chained record per variable (see [log_run()]) plus exactly one `run_manifest` record for the call, carrying that call's `run_id` so the manifest joins the executions it describes; the default destination comes from `getOption("admiralagent.log_file")`, then `ADMIRALAGENT_LOG_FILE`, then a session file in [tempdir()]. Pass `NA` to switch logging off for this call - that suppresses the manifest too.
Value
A list with elements: - `adsl`: the target dataset after execution (named after the IR's first dataset, so `ADSL` for an ADSL IR); - `status`: data.frame with columns `variable`, `status` (one of `EXECUTED`, `ERROR`, `REVIEW`), `note` (error message when `ERROR`, otherwise empty or the review reason); - `env`: the execution environment (useful for inspecting mutated source objects such as imputation temps on `ex`).
Examples
ir <- list(new_variable_ir("ADSL", "ITTFL",
steps = list(new_step("assign_conditional", list(
target = "ITTFL", condition = "AGE >= 18", true_value = "Y"
)))
))
res <- execute_ir(ir, sources = list(base = data.frame(AGE = c(15, 30))))
res$status
#> variable status note
#> 1 ITTFL EXECUTED