fmriAR: Fast Autoregressive (AR) and ARMA Prewhitening for Functional MRI (fMRI) Design and Data

Description

Lightweight utilities to estimate autoregressive (AR) and autoregressive moving average (ARMA) noise models from residuals and apply matched generalized least squares (GLS) prewhitening to functional magnetic resonance imaging (fMRI) design and data matrices. The ARMA estimator follows Hannan and Rissanen (1982) doi:10.1093/biomet/69.1.81, and the Analysis of Functional NeuroImages (AFNI)-inspired restricted AR family mirrors the workflow described by Cox (2012) doi:10.1016/j.neuroimage.2011.08.056.

Estimate AR/ARMA noise models from residuals and apply matched GLS prewhitening to fMRI design and data matrices. Run-aware and censor-aware.

Details

The fmriAR package provides efficient implementations for:

• AR and ARMA model estimation from fMRI residuals

• Run-aware and censor-aware whitening transformations

• Parcel-based parameter pooling

• Sandwich standard error computation

Author(s)

Maintainer: Bradley Buchsbaum brad.buchsbaum@gmail.com

See Also

Useful links:

• https://bbuchsbaum.github.io/fmriAR/

Useful links:

• fit_noise for noise model estimation

• whiten_apply for applying whitening transformations

• whiten for one-step whitening

Autocorrelation diagnostics for residuals

Description

Autocorrelation diagnostics for residuals

Usage

acorr_diagnostics(
  resid,
  runs = NULL,
  max_lag = 20L,
  aggregate = c("mean", "median", "none")
)

Arguments

Value

List of autocorrelation values and nominal confidence interval.

Examples

# Generate example residuals with some autocorrelation
n_time <- 200
n_voxels <- 50
resid <- matrix(rnorm(n_time * n_voxels), n_time, n_voxels)

# Add some AR(1) structure
for (v in 1:n_voxels) {
  resid[, v] <- filter(resid[, v], filter = 0.3, method = "recursive")
}

# Check autocorrelation
acorr_check <- acorr_diagnostics(resid, max_lag = 10, aggregate = "mean")

# Examine lag-1 autocorrelation
lag1_acorr <- acorr_check$acf[2]  # First element is lag-0 (always 1)

Build an AFNI-style restricted AR plan from root parameters

Description

Build an AFNI-style restricted AR plan from root parameters

Usage

afni_restricted_plan(
  resid,
  runs = NULL,
  parcels = NULL,
  p = 3L,
  roots,
  estimate_ma1 = TRUE,
  exact_first = TRUE
)

Arguments

Value

An fmriAR_plan with method = "afni" that can be supplied to whiten_apply().

Examples

NULL

fmrireg compatibility interface

Description

Stable entry points to help upstream packages reuse fmriAR whitening without rewriting existing pipelines.

Usage

compat

Format

An object of class list of length 6.

Value

A list environment containing compatibility functions:

• plan_from_phi: Create whitening plan from AR coefficients

• whiten_with_phi: Apply whitening given AR coefficients

• update_plan: Update existing plan with new residuals

• plan_info: Extract information from a plan object

• whiteness_score: Compute whiteness metric from residuals

• afni_restricted_plan: Build AFNI-style restricted AR plan from root parameters (advanced; internal helper exposed via compat)

Examples

# Create compatibility interface
compat_funcs <- compat

# Example: Create whitening plan from AR coefficients
phi <- c(0.3, 0.1)  # AR(2) coefficients
plan <- compat_funcs$plan_from_phi(phi, exact_first = TRUE)

# Example: Compute whiteness score
resid <- matrix(rnorm(100 * 10), 100, 10)
score <- compat_funcs$whiteness_score(resid)

Fit an AR/ARMA noise model (run-aware) and return a whitening plan

Description

Fit an AR/ARMA noise model (run-aware) and return a whitening plan

Usage

fit_noise(
  resid = NULL,
  Y = NULL,
  X = NULL,
  runs = NULL,
  method = c("ar", "arma"),
  p = "auto",
  q = 0L,
  p_max = 6L,
  exact_first = c("ar1", "none"),
  pooling = c("global", "run", "parcel"),
  parcels = NULL,
  parcel_sets = NULL,
  multiscale = c("pacf_weighted", "acvf_pooled"),
  ms_mode = NULL,
  p_target = NULL,
  beta = 0.5,
  hr_iter = 0L,
  step1 = c("burg", "yw"),
  parallel = FALSE
)

Arguments

Value

An object of class fmriAR_plan used by whiten_apply().

Examples

# Generate example data with AR(1) structure
n_time <- 200
n_voxels <- 50
phi_true <- 0.5

# Simulate residuals with AR(1) structure
resid <- matrix(0, n_time, n_voxels)
for (v in 1:n_voxels) {
  e <- rnorm(n_time)
  resid[1, v] <- e[1]
  for (t in 2:n_time) {
    resid[t, v] <- phi_true * resid[t-1, v] + e[t]
  }
}

# Fit AR model
plan <- fit_noise(resid, method = "ar", p = 1)

# With multiple runs
runs <- rep(1:2, each = 100)
plan_runs <- fit_noise(resid, runs = runs, method = "ar", pooling = "run")

Pretty-print an fmriAR whitening plan

Description

Pretty-print an fmriAR whitening plan

Usage

## S3 method for class 'fmriAR_plan'
print(x, ...)

Arguments

Value

The input plan, invisibly.

Examples

resid <- matrix(rnorm(60), 20, 3)
plan <- fit_noise(resid, method = "ar", p = 2)
print(plan)

GLS standard errors from whitened residuals

Description

GLS standard errors from whitened residuals

Usage

sandwich_from_whitened_resid(
  Xw,
  Yw,
  beta = NULL,
  type = c("iid", "hc0"),
  df_mode = c("rankX", "n-p"),
  runs = NULL
)

Arguments

Value

List containing standard errors, innovation variances, and XtX inverse.

Examples

# Generate example whitened data
n_time <- 200
n_pred <- 3
n_voxels <- 50
Xw <- matrix(rnorm(n_time * n_pred), n_time, n_pred)
Yw <- matrix(rnorm(n_time * n_voxels), n_time, n_voxels)

# Compute standard errors
se_result <- sandwich_from_whitened_resid(Xw, Yw, type = "iid")

# Extract standard errors for first voxel
se_voxel1 <- se_result$se[, 1]

Fit and apply whitening in one call

Description

Fit and apply whitening in one call

Usage

whiten(X, Y, runs = NULL, censor = NULL, ...)

Arguments

Value

List with whitened X and Y matrices.

Examples

# Create example data
n_time <- 200
n_pred <- 3
n_voxels <- 50
X <- matrix(rnorm(n_time * n_pred), n_time, n_pred)
Y <- X %*% matrix(rnorm(n_pred * n_voxels), n_pred, n_voxels) +
     matrix(rnorm(n_time * n_voxels, sd = 2), n_time, n_voxels)

# One-step whitening
whitened <- whiten(X, Y, method = "ar", p = 2)

Apply a whitening plan to design and data matrices

Description

Apply a whitening plan to design and data matrices

Usage

whiten_apply(
  plan,
  X,
  Y,
  runs = NULL,
  run_starts = NULL,
  censor = NULL,
  parcels = NULL,
  inplace = FALSE,
  parallel = TRUE
)

Arguments

Value

List with whitened data. Parcel plans return X_by per parcel; others return a single X matrix.

Examples

# Create example design matrix and data
n_time <- 200
n_pred <- 3
n_voxels <- 50
X <- matrix(rnorm(n_time * n_pred), n_time, n_pred)
Y <- X %*% matrix(rnorm(n_pred * n_voxels), n_pred, n_voxels) +
     matrix(rnorm(n_time * n_voxels), n_time, n_voxels)

# Fit noise model from residuals
residuals <- Y - X %*% solve(crossprod(X), crossprod(X, Y))
plan <- fit_noise(residuals, method = "ar", p = 2)

# Apply whitening
whitened <- whiten_apply(plan, X, Y)
Xw <- whitened$X
Yw <- whitened$Y