Generic functions for fmridesign package — event

This file contains the generic functions used throughout the fmridesign package. These generics define the interface for working with event models, baseline models, and related design components. Construct an event model

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,
  block,
  sampling_frame,
  durations = 0,
  drop_empty = TRUE,
  precision = 0.3,
  parallel = FALSE,
  progress = FALSE,
  ...
)

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

Arguments

formula_or_list: Either a formula (e.g., onset ~ hrf(cond) + hrf(mod)) or a list of pre-defined hrfspec objects.
data: A data.frame containing event variables referenced in the formula or needed by the hrfspec objects.
block: A formula (e.g., ~ run) or vector specifying the block/run for each event.
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 indicating whether to use parallel processing for term convolution (requires future.apply). Default is FALSE.
progress: Logical indicating whether to show a progress bar during term realisation. Default is FALSE.
...: Additional arguments (currently unused).

Value

An event_model object describing the task design.

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

Details

This function creates an event-based fMRI regression model, represented as a data structure.

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).

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

# Example using formula interface
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.062       0.000      -0.057      -0.179    
#>    Scan 2   1.138       0.000      -1.031      -0.577    
#>    Scan 3   1.744       0.000      -1.581       0.059    
#> ...
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.0624      0          -0.0566     -0.179     -0.371  
#> 2      1.14        0          -1.03       -0.577      0.175  
#> 3      1.74        0          -1.58        0.0595     0.290  
#> 4      1.20        0          -1.09        0.334      0.00392
#> 5      0.552       0          -0.500       0.232     -0.0741 
#> 6      0.192       0.0341     -0.246      -0.162     -0.744  

# Example using list interface (less common)
# 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)                         
                             
des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run, sampling_frame = sframe)
dim(design_matrix(emod))
#> [1] 40  2