Skip to contents

fmrireg t-tests for Group Analysis

Source: R/fmri_ttest.R
fmri_ttest.Rd

Performs group-level t-tests on fMRI data with support for one-sample, two-sample, paired, and ANCOVA designs. Provides both meta-analysis and classical t-test engines, mirroring AFNI 3dttest++ functionality within the fmrireg framework. The classic and Welch engines are fmrigds's "ols:voxelwise" and "ttest:welch" reducers; the meta engine is fmrireg's meta-regression (see fmri_meta()).

Usage

fmri_ttest(
  gd,
  formula = ~1,
  engine = c("auto", "meta", "classic", "welch"),
  paired = FALSE,
  mu0 = 0,
  contrast = NULL,
  mc = NULL,
  alpha = 0.05,
  sign = c("AminusB", "BminusA"),
  mask = NULL,
  voxelwise_cov = NULL,
  center_voxelwise = TRUE,
  voxel_name = "voxel_cov",
  weights = c("ivw", "equal", "custom"),
  weights_custom = NULL,
  combine = NULL
)

Arguments

gd

A gds-backed group_data() object (or an fmrigds gds), a legacy group_data object, or a data frame accepted by group_data(). gds data must hold one subject-level contrast; every engine and option works on it, except that the meta engine on gds data supports neither mu0 nor voxelwise_cov.

formula

R formula for between-subjects design. Examples:

  • ~ 1: One-sample t-test

  • ~ 1 + group: Two-sample t-test

  • ~ 1 + group + age: ANCOVA with covariate

engine

Character string; analysis engine to use:

  • "auto": "meta" when sampling variances are available (always for gds data), otherwise "classic" (default). The fit records the engine that ran.

  • "meta": Use inverse-variance meta-analysis (requires SE)

  • "classic": Use OLS/Student t-test. A subject with a non-finite value for a feature is dropped from that feature only, so degrees of freedom can differ between features.

  • "welch": Welch t-test for unequal variances; needs formula = ~ 1 + group with a two-level factor group. Non-finite subjects are dropped per feature.

paired

Logical; if TRUE, the effects are within-subject differences and are tested against mu0 with the classic one-sample engine (default: FALSE)

mu0

Numeric scalar; constant to test against for one-sample tests (default: 0)

contrast

Optional named numeric vector for linear combination of coefficients

mc

Character string or NULL; multiple comparisons correction:

  • NULL: No correction (default)

  • "bh": Benjamini-Hochberg FDR

  • "by": Benjamini-Yekutieli FDR

  • "spatial_fdr": Spatially-aware FDR

alpha

Numeric scalar; FDR level if mc is not NULL (default: 0.05)

sign

Character string; sign convention for group differences:

  • "AminusB": A - B (default)

  • "BminusA": B - A

mask

Optional mask object or path

voxelwise_cov

Optional S x P matrix of voxelwise covariates

center_voxelwise

Logical; center voxelwise covariate per feature (default: TRUE)

voxel_name

Character string; name for voxelwise coefficient (default: "voxel_cov")

weights

Character string for meta-engine weighting: "ivw" (default, uses provided SE), "equal" (equal weights), or "custom" (supply weights_custom). "equal"/"custom" are relative weights with an estimated residual scale (weighted least squares; see fmri_meta). Ignored for classic/welch engines.

weights_custom

Numeric vector (length S) or matrix (S x P) of custom weights when weights = "custom".

combine

Optional. When using the meta engine with t-only inputs (i.e., per-subject t-statistics and df), specify the t-combination method: "stouffer", "fisher", or "lancaster". Passed through to fmri_meta() when delegating to the meta engine on group_data_*.

Value

An fmri_ttest_fit object containing:

  • beta: Matrix of coefficients

  • se: Matrix of standard errors (if available)

  • t: Matrix of t-statistics (classic engine)

  • z: Matrix of z-scores

  • p: Matrix of p-values

  • df: Matrix of degrees of freedom

  • q: Matrix of FDR-adjusted p-values (if mc is used)

  • z_contrast: Vector of contrast z-scores (if contrast is used)

  • p_contrast: Vector of contrast p-values (if contrast is used)

Examples

if (FALSE) { # \dontrun{
# One-sample t-test
fit <- fmri_ttest(gd, formula = ~ 1)

# Two-sample t-test
fit <- fmri_ttest(gd, formula = ~ 1 + group)

# Paired t-test
fit <- fmri_ttest(gd_diff, formula = ~ 1, paired = TRUE)

# ANCOVA with age covariate
fit <- fmri_ttest(gd, formula = ~ 1 + group + age)

# With spatial FDR correction
fit <- fmri_ttest(gd, formula = ~ 1 + group, mc = "spatial_fdr", alpha = 0.05)
} # }