estimate_betas.fmri_dataset: Estimate betas using the Rank-1 GLM methods (R1 and R1-GLMS...

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

Estimate betas using the Rank-1 GLM methods (R1 and R1-GLMS with optimizations)

Description

This function estimates betas (regression coefficients) and the hemodynamic response function (HRF) simultaneously using the Rank-1 GLM (r1) and Rank-1 GLM with Mumford's separate beta estimation (r1_glms) methods. It includes optimizations to improve computational efficiency.

Usage

## S3 method for class 'fmri_dataset'
estimate_betas(
  x,
  fixed = NULL,
  ran,
  block,
  method = c("mixed", "mixed_cpp", "lss", "lss_naive", "lss_cpp", "r1", "pls",
    "pls_global", "ols", "fracridge", "lowrank_hrf"),
  basemod = NULL,
  hrf_basis = NULL,
  hrf_ref = NULL,
  maxit = 1000,
  fracs = 0.5,
  ...
)

Arguments

x	An object of class fmri_dataset representing the fMRI dataset.
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; use "r1" for the Rank-1 GLM method or "r1_glms" for the Rank-1 GLM with Mumford's approach.
basemod	A baseline_model instance to regress out of data before beta estimation (default: NULL).
hrf_basis	A matrix of basis functions for the HRF (default: NULL).
hrf_ref	A reference HRF vector for initializing and constraining the HRF estimation (default: NULL).
maxit	Maximum number of iterations for the optimization (default: 100).
fracs	Fraction of ridge regression to use (default: 0.5).
...	Additional arguments passed to the estimation method.

Details

The r1 method uses the Rank-1 GLM approach to jointly estimate the HRF and activation coefficients. The r1_glms method implements the Mumford approach by estimating each beta individually to reduce correlations, treating all events as coming from one condition. This implementation includes optimizations to improve computational efficiency:

• Precomputing the total sum of all trial regressors to avoid redundant computations.

• Precomputing the QR decomposition of design matrices to speed up linear algebra operations.

Value

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

• betas_fixed: NeuroVec object representing the fixed effect betas.

• betas_ran: NeuroVec object representing the random effect betas.

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

References

Pedregosa, F., et al. (2015). GLM with Rank-1 constraint (R1-GLM): a fast, spatially adaptive model for single trial fMRI data. NeuroImage, 104, 271–285.

Mumford, J. A., Turner, B. O., Ashby, F. G., & Poldrack, R. A. (2012). Deconvolving BOLD activation in event-related designs for multivoxel pattern classification analyses. NeuroImage, 59(3), 2636–2643.

See Also

fmri_dataset, baseline_model, event_model

Examples

## Not run: 
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 <- fmri_dataset(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="r1_glms")

## End(Not run)

bbuchsbaum/fmrireg documentation built on March 1, 2025, 11:20 a.m.