SBHM Pipeline with fmridesign Models — lss_sbhm

Run the SBHM end-to-end pipeline using fmridesign's event_model and optional baseline_model, mirroring the convenience of lss_design() but producing SBHM shape coefficients and (optionally) scalar event-design trial coefficients in the component named amplitude.

Usage

lss_sbhm_design(
  Y,
  sbhm,
  event_model,
  baseline_model = NULL,
  prewhiten = NULL,
  prepass = list(),
  match = list(),
  oasis = list(),
  amplitude = list(),
  return = c("amplitude", "coefficients", "both"),
  validate = TRUE,
  ...
)

Arguments

Y: Numeric matrix T×V of fMRI time series (timepoints × voxels).
sbhm: SBHM object as returned by sbhm_build().
event_model: An event_model from fmridesign::event_model() defining the trial structure (typically created with trialwise()).
baseline_model: Optional baseline_model from fmridesign::baseline_model(). Its drift, block, and nuisance terms are projected out as confounds.
prewhiten: Optional prewhitening options (see ?lss).
prepass: Optional list forwarded to sbhm_prepass().
match: Optional list forwarded to sbhm_match().
oasis: Optional SBHM OASIS override list. Supported fields are ridge_mode, ridge_x, ridge_b, and block_cols; false-valued return_se and return_diag are accepted, while true values fail because SBHM uncertainty/design diagnostics are not exposed. The basis rank, trial count, intercept policy, and trial/basis map are fixed internally from sbhm and the event model.
amplitude: Amplitude options (see ?lss_sbhm).
return: One of "amplitude", "coefficients", or "both".
validate: Logical; when TRUE, performs basic checks (sampling frame compatibility, temporal alignment) analogous to lss_design().
...: Reserved for future use.

Value

Same return contract as lss_sbhm().

Details

This function wraps lss_sbhm() by locating the unique trialwise event term, rebuilding it with the SBHM basis, and retaining run identities and heterogeneous durations. Non-trial event terms and baseline_model columns enter the fixed nuisance span. Multi-run regressors are constructed within runs so HRF tails cannot cross run boundaries.

Examples

# \donttest{
  library(fmridesign)
  sframe <- fmrihrf::sampling_frame(blocklens = 60, TR = 1)
  trials <- data.frame(onset = c(5, 20, 35), run = 1)
  emod <- event_model(onset ~ trialwise(basis = "spmg1"), data = trials,
                      block = ~run, sampling_frame = sframe)
  times <- fmrihrf::samples(sframe, global = TRUE)
  H <- cbind(exp(-times / 5), exp(-times / 7))
  sbhm <- sbhm_build(library_H = H, r = 2, sframe = sframe,
                     normalize = TRUE, baseline = NULL)
  Y <- matrix(rnorm(60 * 4), 60, 4)
  out <- lss_sbhm_design(Y, sbhm, emod)
# }