fmri_lm: Fit a Linear Regression Model for fMRI Data Analysis

View source: R/fmrilm.R

fmri_lmR Documentation

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.