event_model: Construct an event model

In bbuchsbaum/fmrireg: R package for the anlysis of fmri data

Construct an event model

Description

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

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

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

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.

Value

A list containing the following elements:

formula

The formula used to create the model.

design

The design matrix for the model, with one row per time point and one column per predictor variable.

block_indices

A list of indices defining the start and end time points of each block.

baseline

A vector containing the estimated baseline fMRI signal level for each block.

dur

A vector containing the duration (in seconds) of each event or block in the design.

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

Examples

# Create a data frame with experimental design
event_data <- data.frame(fac=c("a", "B", "A", "B"), onsets=c(1,10,20,80), run=c(1,1,1,1))

# Create a sampling frame with 50-second blocks and a TR of 2 seconds
sframe <- sampling_frame(blocklens=50, TR=2)

# Create an event model using the `onsets` variable as a predictor, 
#  with a separate baseline for each run
evmodel <- event_model(onsets ~ hrf(onsets), data=event_data, block=~run, sampling_frame=sframe)
dmat <- design_matrix(evmodel)
# 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)
head(design_matrix(ev_model_form))

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

bbuchsbaum/fmrireg documentation built on June 10, 2025, 8:18 p.m.