r1_glm_betas: Rank-1 GLM Solver

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

Rank-1 GLM Solver

Description

Jointly estimates activation coefficients (betas) and an HRF shape (in a given basis) under a Rank-1 constraint. Allows optional nuisance regressors. Can optionally apply box constraints if m=3 and sign-flip to ensure positive correlation with a reference HRF.

Usage

r1_glm_betas(
  X,
  y,
  Z = NULL,
  hrf_basis,
  hrf_ref,
  maxit = 100,
  flip_sign = FALSE,
  use_box_constraints = FALSE
)

Arguments

X	A numeric matrix of size n \times (k*m), with n timepoints, k conditions, and m basis functions. Typically formed by convolving each event onset with m basis functions, then horizontally stacking them for k conditions.
y	A length-n numeric vector of fMRI data (single voxel).
Z	Optional numeric matrix of nuisance regressors, n \times q. If NULL, no nuisance.
hrf_basis	A T \times m matrix of basis functions for the HRF.
hrf_ref	A length-T numeric vector of some reference HRF shape, for an optional sign-flip check.
maxit	Max number of L-BFGS-B iterations. Default 100.
flip_sign	Logical. If TRUE, we ensure the final HRF is positively correlated with hrf_ref.
use_box_constraints	Logical. If TRUE and m=3, we forcibly set h[1]=1 and h[2:3] \in [-1,1].

Value

A list with:

beta

Numeric vector of length k (event amplitudes).

h

Numeric vector of length m (basis weights).

omega

Numeric vector of length q for nuisance, or numeric(0) if none.

converged

Logical, TRUE if the L-BFGS-B optimizer converged.

value

The final objective (residual sum of squares / 2).

Examples

# Minimal usage example
set.seed(42)
n <- 200; k <- 10; m <- 3
X <- matrix(rnorm(n*k*m), n, k*m)
y <- rnorm(n)
hrf_basis <- matrix(rnorm(32*m), 32, m)
hrf_ref   <- dgamma(seq(0, 31, length.out=32), shape=6, rate=1)

fit <- r1_glm_betas(X, y, NULL, hrf_basis, hrf_ref, maxit=50)
str(fit)

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