Creates an object representing event-related regressors for fMRI modeling. This function defines event onsets and associates them with a hemodynamic response function (HRF) to generate predicted time courses.
Arguments
- onsets
A numeric vector of event onset times in seconds.
- hrf
The hemodynamic response function (HRF) to convolve with the events. This can be:
A pre-defined `HRF` object (e.g., `HRF_SPMG1`)
A custom `HRF` object created with `as_hrf`
A function `f(t)`
A character string referring to a known HRF type (e.g., "spmg1", "gaussian")
A **list of HRF objects** for trial-varying HRFs (one per event, or length 1 to recycle)
Defaults to `HRF_SPMG1`.
- duration
A numeric scalar or vector specifying the duration of each event in seconds. If scalar, it's applied to all events. Defaults to 0 (impulse events).
- amplitude
A numeric scalar or vector specifying the amplitude (scaling factor) for each event. If scalar, it's applied to all events. Defaults to 1.
- span
The temporal window (in seconds) over which the HRF is defined or evaluated. This influences the length of the convolution. If not provided, it may be inferred from the `hrf` object or default to 40s. For list HRFs, the maximum span across all HRFs is used. **Note:** Unlike some previous versions, the `span` is not automatically adjusted based on `duration`; ensure the provided or inferred `span` is sufficient for your longest event duration.
- summate
Logical scalar; if `TRUE` (default), the HRF response amplitude scales with the duration of sustained events (via weighted integration). If `FALSE`, weighted integration is normalized by total block weight so amplitude does not grow with duration.
Value
An S3 object of class `Reg` and `list` containing processed event information and the HRF specification. The object includes a `filtered_all` attribute indicating whether all events were removed due to zero or `NA` amplitudes, and an `hrf_is_list` attribute indicating whether trial-varying HRFs are used.
Details
This function serves as the main public interface for creating regressor objects. Internally, it utilizes the `Reg()` constructor which performs validation and efficient storage. The resulting object can be evaluated at specific time points using the `evaluate()` function.
Events with an amplitude of 0 are automatically filtered out.
## Trial-Varying HRFs
When `hrf` is a list of HRF objects, each event can have its own HRF. This is useful for trial-wise analyses where different events may have different temporal characteristics (e.g., different boxcar windows, different weights). The list must have either length 1 (recycled to all events) or length equal to the number of onsets.
Examples
# Create a simple regressor with 3 events
reg <- regressor(onsets = c(10, 30, 50), hrf = HRF_SPMG1)
# Regressor with durations and amplitudes
reg2 <- regressor(
onsets = c(10, 30, 50),
duration = c(2, 2, 2),
amplitude = c(1, 1.5, 0.8),
hrf = HRF_SPMG1
)
# Using different HRF types
reg_gamma <- regressor(onsets = c(10, 30), hrf = "gamma")
# Evaluate regressor at specific time points
times <- seq(0, 60, by = 0.1)
response <- evaluate(reg, times)
# Trial-varying HRFs: different boxcar windows for each event
hrf1 <- hrf_boxcar(width = 4, normalize = TRUE)
#> Warning: Parameters width, amplitude, normalize are not arguments to function boxcar[4] and will be ignored
hrf2 <- hrf_boxcar(width = 6, normalize = TRUE)
#> Warning: Parameters width, amplitude, normalize are not arguments to function boxcar[6] and will be ignored
reg_varying <- regressor(
onsets = c(10, 30),
hrf = list(hrf1, hrf2)
)