Estimate Beta Coefficients for fMRI Data

Estimate trialwise (random) and condition-level (fixed) beta coefficients from fMRI data. Trialwise regressors given by ran are estimated with one of three methods: ridge/BLUP mixed-effects estimation ("mixed"), least-squares separate estimation ("lss"), or ordinary least squares ("ols"). Optional fixed regressors (fixed) capture effects that are constant across trials, and an optional baseline model is regressed out before estimation.

Usage

estimate_betas(x, ...)

# S3 method for class 'fmri_frame'
estimate_betas(
  x,
  fixed = NULL,
  ran,
  block,
  method = c("mixed", "lss", "ols"),
  basemod = NULL,
  maxit = 1000,
  fracs = 0.5,
  progress = TRUE,
  ...
)

Arguments

x: An fmri_frame (see matrix_frame(), neurovec_frame(), nifti_frame(), and latent_frame()). When the frame's feature space is a volume_space, the fixed and random betas are returned as NeuroVec objects on that grid; otherwise (index or basis spaces) they are returned as coefficient-by-feature matrices.
...: Additional arguments passed to the estimation method.
fixed: A formula specifying the fixed regressors that model constant effects (i.e., non-varying over trials).
ran: A formula specifying the random (trialwise) regressors that model single trial effects.
block: A formula specifying the block factor.
method: The regression method for estimating trialwise betas; one of "mixed", "lss", or "ols".
basemod: A baseline_model instance to regress out of data before beta estimation (default: NULL).
maxit: Maximum number of iterations for optimization methods (default: 1000).
fracs: Fraction of voxels used for prewhitening.
progress: Logical; show progress bar.

Value

A list of class "fmri_betas" containing the following components:

betas_fixed: fixed effect betas (NeuroVec for volumetric frames, matrix otherwise).
betas_ran: random effect betas (NeuroVec for volumetric frames, matrix otherwise).
design_ran: Design matrix for random effects.
design_fixed: Design matrix for fixed effects.
design_base: Design matrix for baseline model.
basemod: Baseline model object.
fixed_model: Fixed effect model object.
ran_model: Random effect model object.
estimated_hrf: The estimated HRF vector (NULL for most methods).

Details

This is a generic function whose fmri_frame method adapts to the frame's feature space: volumetric frames (volume_space) return NeuroVec betas, while matrix-format (index_space) and latent (basis_space) frames return coefficient matrices.

Available estimation methods (method) are:

mixed: Mixed-effects model using ridge/BLUP estimation
lss: Least-squares separate estimation
ols: Ordinary least squares

References

Mumford, J. A., et al. (2012). Deconvolving BOLD activation in event-related designs for multivoxel pattern classification analyses. NeuroImage, 59(3), 2636-2643.

Pedregosa, F., et al. (2015). Data-driven HRF estimation for encoding and decoding models. NeuroImage, 104, 209-220.

Examples

# Create example data
event_data <- data.frame(
  condition = factor(c("A", "B", "A", "B")),
  onset = c(1, 10, 20, 30),
  run = c(1, 1, 1, 1)
)

# Create sampling frame and dataset
sframe <- sampling_frame(blocklens = 100, TR = 2)
dset <- matrix_frame(
  matrix(rnorm(100 * 2), 100, 2),
  TR = 2,
  run_length = 100,
  event_table = event_data
)

# Estimate betas using mixed-effects model
betas <- estimate_betas(
  dset,
  fixed = onset ~ hrf(condition),
  ran = onset ~ trialwise(),
  block = ~run,
  method = "mixed"
)

if (FALSE) { # \dontrun{
facedes <- read.table(system.file("extdata", "face_design.txt", package = "fmrireg"), header=TRUE)
facedes$frun <- factor(facedes$run)
scans <- paste0("rscan0", 1:6, ".nii")

dset <- nifti_frame(scans=scans, mask="mask.nii", TR=1.5,
        run_length=rep(436,6), event_table=facedes)
fixed = onset ~ hrf(run)
ran = onset ~ trialwise()
block = ~ run

betas <- estimate_betas(dset, fixed=fixed, ran=ran, block=block, method="mixed")
} # }