Construct an fMRI Event Model — event

This is the main constructor for event_model objects. It unifies the previous formula and list-based interfaces and uses a more efficient internal pipeline.

Usage

event_model(
  formula_or_list,
  data = NULL,
  block = NULL,
  sampling_frame,
  durations = 0,
  drop_empty = TRUE,
  precision = 0.3,
  parallel = FALSE,
  progress = FALSE,
  strict = FALSE,
  ...
)

Arguments

formula_or_list: Either a formula (e.g., onset ~ hrf(cond) + hrf(mod)) or a list of pre-defined hrfspec / featurespec objects. A one-sided formula (~ feature(...)) is allowed for feature-only models.
data: A data.frame containing event variables referenced in the formula or needed by the hrfspec objects. Optional for feature-only models.
block: A formula (e.g., ~ run) or vector specifying the block/run for each event. Optional for feature-only models.
sampling_frame: An object of class sampling_frame defining the scan timing (TR, block lengths).
durations: Numeric vector or scalar specifying event durations (seconds). Default is 0.
drop_empty: Logical indicating whether to drop empty events during term construction. Default is TRUE.
precision: Numeric precision for HRF sampling/convolution. Default is 0.3.
parallel: Logical compatibility shim reserved for future use. The current implementation always evaluates terms sequentially; when set to TRUE, a warning is emitted and sequential evaluation is used. Default is FALSE.
progress: Logical indicating whether to show a progress bar during term realisation. Default is FALSE.
strict: Logical controlling the onset bounds check. When FALSE (default) event onsets that fall outside the sampling frame (negative, at or after a run's end, or events extending past a run's end) trigger a warning(). When TRUE the same conditions raise an error. This is a backstop for gross onset/clock mistakes; a uniform in-bounds shift cannot be detected here.
...: Additional arguments (currently unused).

Value

An object of class c("event_model", "list") containing the terms, design matrix, sampling frame, and other metadata.

Details

Column Naming

The columns in the resulting design matrix follow the naming convention: term_tag + _ + condition_tag + _b## basis suffix

Where:

term_tag: The unique tag assigned to the hrf() term (see below).
condition_tag: Represents the specific factor level or continuous regressor within the term (e.g., condition.A, poly_RT_01, condition.A_task.go).
_b##: Optional suffix added for HRFs with multiple basis functions (e.g., _b01, _b02).

Within a multi-basis term, columns are ordered condition-major: all basis functions of the first condition, then all of the second, and so on (cond.A_b01, cond.A_b02, cond.B_b01, cond.B_b02, ...). The order returned by conditions(term, expand_basis = TRUE) is the same.

Term Naming and Clash Resolution

Each term in the model (typically defined by an hrf() call in a formula) gets a unique term_tag. This tag is used as the prefix for all columns generated by that term.

Default Naming: If no explicit id (or name) is given in hrf(), the tag is derived from the variable names (e.g., hrf(condition) -> condition, hrf(RT, acc) -> RT_acc).
Explicit Naming: Use id= within hrf() for an explicit tag (e.g., hrf(condition, id="CondMain")).
Sanitization: Dots (.) in tags are converted to underscores (_).
Clash Resolution: If multiple terms generate the same tag, # and a number are appended to ensure uniqueness (e.g., condition, condition#1).

This consistent naming scheme replaces the previous compact and qualified styles.

Examples

des <- data.frame(onset = seq(0, 90, by=10),
                  run = rep(1:2, each=5),
                  cond = factor(rep(c("A","B"), 5)),
                  mod = rnorm(10))
sframe <- fmrihrf::sampling_frame(blocklens=c(50, 60), TR=2)

ev_model_form <- event_model(onset ~ hrf(cond) + hrf(mod, basis="spmg3"),
                            data = des, block = ~run, sampling_frame = sframe)
print(ev_model_form)
#> 
#> ── fMRI Event Model ────────────────────────────────────────────────────────────
#> Number of Terms: 2
#> Number of Events: 10
#> Number of Blocks: 2
#> Total Scans: 110
#> Design Matrix Dimensions: 110 x 5
#> 
#> ── Terms ──
#> 
#> • cond (<event_term>)
#> • mod (<event_term>)
#> 
#> ── Design Matrix Preview ──
#> 
#>           cond_cond.A cond_cond.B mod_mod_b01 mod_mod_b02
#>    Scan 1   0.003       0.000      -0.002      -0.009    
#>    Scan 2   0.101       0.000      -0.074      -0.048    
#>    Scan 3   0.175       0.000      -0.128      -0.000    
#> ...
head(design_matrix(ev_model_form))
#> # A tibble: 6 × 5
#>   cond_cond.A cond_cond.B mod_mod_b01 mod_mod_b02 mod_mod_b03
#>         <dbl>       <dbl>       <dbl>       <dbl>       <dbl>
#> 1     0.00342     0          -0.00250   -0.00926      0.0124 
#> 2     0.101       0          -0.0735    -0.0485       0.0459 
#> 3     0.175       0          -0.128     -0.000169    -0.0527 
#> 4     0.127       0          -0.0929     0.0270      -0.0407 
#> 5     0.0576      0          -0.0421     0.0213       0.00204
#> 6     0.0136      0.00342    -0.0106     0.00891      0.0169 

spec1 <- hrf(cond)
spec2 <- hrf(mod, basis = "spmg3")
ev_model_list <- event_model(list(spec1, spec2), data = des,
                             block = des$run, sampling_frame = sframe)
print(ev_model_list)
#> 
#> ── fMRI Event Model ────────────────────────────────────────────────────────────
#> Number of Terms: 2
#> Number of Events: 10
#> Number of Blocks: 2
#> Total Scans: 110
#> Design Matrix Dimensions: 110 x 5
#> 
#> ── Terms ──
#> 
#> • cond (<event_term>)
#> • mod (<event_term>)
#> 
#> ── Design Matrix Preview ──
#> 
#>           cond_cond.A cond_cond.B mod_mod_b01 mod_mod_b02
#>    Scan 1   0.003       0.000      -0.002      -0.009    
#>    Scan 2   0.101       0.000      -0.074      -0.048    
#>    Scan 3   0.175       0.000      -0.128      -0.000    
#> ...