fmri_lm: Fit a Linear Regression Model for fMRI Data Analysis

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

Fit a Linear Regression Model for fMRI Data Analysis

Description

This function fits a linear regression model for fMRI data analysis using the specified model formula, block structure, and dataset. The model can be fit using either a runwise or chunkwise data splitting strategy, and robust fitting can be enabled if desired. When cor_struct is set to one of the AR options ("ar1", "ar2", "arp"), the function performs fast AR prewhitening to account for temporal autocorrelation in the residuals.

Usage

fmri_lm(
  formula,
  block,
  baseline_model = NULL,
  dataset,
  durations = 0,
  drop_empty = TRUE,
  robust = FALSE,
  robust_options = NULL,
  ar_options = NULL,
  strategy = c("runwise", "chunkwise"),
  nchunks = 10,
  use_fast_path = FALSE,
  progress = FALSE,
  extra_nuisance = NULL,
  keep_extra_nuisance_in_model = FALSE,
  ar_voxelwise = FALSE,
  parallel_voxels = FALSE,
  cor_struct = NULL,
  cor_iter = NULL,
  cor_global = NULL,
  ar1_exact_first = NULL,
  ar_p = NULL,
  robust_psi = NULL,
  robust_max_iter = NULL,
  robust_scale_scope = NULL,
  ...
)

Arguments

formula	The model formula for experimental events.
block	The model formula for block structure.
baseline_model	(Optional) A baseline_model object. Default is NULL.
dataset	An fmri_dataset object containing the time-series data.
durations	A vector of event durations. Default is 0.
drop_empty	Logical. Whether to remove factor levels with zero size. Default is TRUE.
robust	Logical or character. Either FALSE (no robust fitting), TRUE (use Huber), or one of "huber" or "bisquare". Default is FALSE.
robust_options	List of robust fitting options. See Details.
ar_options	List of autoregressive modeling options. See Details.
strategy	The data splitting strategy, either "runwise" or "chunkwise". Default is "runwise".
nchunks	Number of data chunks when strategy is "chunkwise". Default is 10.
use_fast_path	Logical. If TRUE, use matrix-based computation for speed. Default is FALSE.
progress	Logical. Whether to display a progress bar during model fitting. Default is FALSE.
extra_nuisance	Optional matrix or formula specifying additional nuisance regressors.
keep_extra_nuisance_in_model	Logical. Whether to keep extra nuisance regressors in the final model. Default is FALSE.

Details

robust_options may contain:

• type: Character or logical. Type of robust fitting (FALSE, "huber", "bisquare")

• k_huber: Numeric. Tuning constant for Huber's psi (default: 1.345)

• c_tukey: Numeric. Tuning constant for Tukey's bisquare psi (default: 4.685)

• max_iter: Integer. Maximum IRLS iterations (default: 2)

• scale_scope: Character. Scope for scale estimation ("run" or "global")

• reestimate_phi: Logical. Whether to re-estimate AR parameters after robust fitting

ar_options may contain:

• struct: Character. Correlation structure ("iid", "ar1", "ar2", "arp")

• p: Integer. AR order when struct = "arp"

• iter_gls: Integer. Number of GLS iterations (default: 1)

• global: Logical. Use global AR coefficients (default: FALSE)

• voxelwise: Logical. Estimate AR parameters voxel-wise (default: FALSE)

• exact_first: Logical. Apply exact AR(1) scaling to first sample (default: FALSE)

Value

A fitted linear regression model for fMRI data analysis.

See Also

fmri_dataset, fmri_lm_fit, fmri_lm_control

Examples

facedes <- subset(read.table(system.file("extdata", "face_design.txt", package = "fmrireg"), 
header=TRUE), face_gen != "n/a")
facedes$face_gen <- droplevels(factor(facedes$face_gen))
sframe <- sampling_frame(rep(430/2,6), TR=2)
ev <- event_model(onset ~ hrf(face_gen, basis="gaussian"), data=facedes, 
block= ~ run, sampling_frame=sframe)
globonsets <- fmrihrf::global_onsets(sframe, facedes$onset, fmrihrf::blockids(ev))
reg1_signal <- regressor(globonsets[facedes$face_gen == "male"], hrf=HRF_GAUSSIAN)
reg2_signal <- regressor(globonsets[facedes$face_gen == "female"], hrf=HRF_GAUSSIAN)
time <- samples(sframe, global=TRUE)
y1 <- fmrihrf::evaluate(reg1_signal, time)*1.5
y2 <- fmrihrf::evaluate(reg2_signal, time)*3.0
y <- y1+y2
ys1 <- y + rnorm(length(y), sd=.02)
ys2 <- y + rnorm(length(y), sd=.02)

h <<- gen_hrf(hrf_bspline, N=7, span=25)
dset <- matrix_dataset(cbind(ys1,ys2), TR=2, run_length=fmrihrf::blocklens(sframe), event_table=facedes)
flm <- fmri_lm(onset ~ hrf(face_gen, basis=gen_hrf(hrf_bspline, N=7, span=25)), block = ~ run, 
strategy="chunkwise", nchunks=1, dataset=dset)

bbuchsbaum/fmrireg documentation built on June 10, 2025, 8:18 p.m.