fmrireg

Documentation · Getting started · API reference · Changelog

fmrireg is an R package for specifying and fitting voxelwise fMRI regression models from event tables and preprocessed time series. It turns formulas such as onset ~ hrf(condition) into HRF-convolved designs, estimates condition effects across voxels, and carries named contrasts into group analysis.

Status: Version 0.2.0 is experimental and requires R 4.1 or later. APIs may change while the package is under active development.

Installation

Install the development version from GitHub:

install.packages("remotes")
remotes::install_github("bbuchsbaum/fmrireg")

Quick start

This synthetic example makes one task-responsive time series and fits it without external imaging files:

library(fmrireg)

TR <- 2
n_timepoints <- 120
acquisition_time <- seq(TR / 2, by = TR, length.out = n_timepoints)
set.seed(42)
events <- data.frame(
  onset = cumsum(sample(c(6, 8, 10), 24, replace = TRUE)),
  condition = factor(sample(rep(c("faces", "scenes"), each = 12))),
  duration = 0,
  run = 1L
)

task_regressor <- function(condition) {
  fmrihrf::regressor(
    events$onset[events$condition == condition]
  ) |>
    fmrihrf::evaluate(acquisition_time) |>
    as.numeric()
}

faces <- task_regressor("faces")
scenes <- task_regressor("scenes")
bold <- cbind(
  face_roi = 100 + 1.5 * faces + 0.1 * scenes + rnorm(n_timepoints, sd = 0.04)
)

dataset <- matrix_dataset(
  bold, TR = TR, run_length = n_timepoints,
  event_table = events
)
fit <- fmri_lm(
  onset ~ hrf(condition), block = ~ run, dataset = dataset
)

results <- subset(
  tidy(fit), term %in% levels(events$condition),
  select = c(voxel, term, estimate, std_error)
)
results$estimate <- round(results$estimate, 2)
results$std_error <- round(results$std_error, 2)
results
#> # A tibble: 2 x 4
#>   voxel term   estimate std_error
#>   <int> <chr>     <dbl>     <dbl>
#> 1     1 faces      1.49      0.01
#> 2     1 scenes     0.1       0.01

The recovered pattern matches the simulation: the region responds more to faces than to scenes. For real analyses, replace bold and events with time-by-voxel data and the matching event table; the modeling interface is the same.

What it covers

• Build task and baseline models from formulas, including canonical, flexible, and custom hemodynamic response functions.
• Fit matrix-backed or imaging-backed datasets with ordinary, robust, and autoregressive regression paths.
• Define named t- and F-contrasts and export coefficient or statistic maps.
• Carry subject-level betas and standard errors—or t-statistics and degrees of freedom—into group analysis.
• Use controlled simulations, known-truth benchmark datasets, and explicit approximation diagnostics for accelerated methods.

Fit and boundaries

fmrireg is the regression layer of an fMRI workflow. It expects preprocessed time series and aligned event information; it does not perform motion correction, anatomical registration, or spatial normalization. Matrix-backed examples are useful for regions of interest and testing, while the dataset and export guides cover image- and file-backed workflows.

The package is still experimental. Exact, AR-corrected, robust, and accelerated engines have different statistical contracts; use the relevant guide rather than assuming that every option is interchangeable.

Documentation

• Overview and workflow — start with a complete fit, then unpack datasets, designs, and contrasts.
• Dataset management, simulation, linear modeling, and contrasts — the core single-subject workflow.
• Multi-subject fan-out and group analysis — move from subject fits to group inference.
• Functional connectivity — seed-regressor inference with autocorrelation and multiplicity control.
• Sketched GLM, plugin development, and benchmark datasets — advanced engines, extensions, and numerical oracles.
• API reference — exported functions, arguments, and return values.

Optional command-line wrapper

Install the wrapper into a directory on PATH:

fmrireg::install_cli("~/.local/bin", overwrite = TRUE)

Then inspect available commands or bundled benchmark datasets:

fmrireg --help
fmrireg benchmark list

Contributing

See CONTRIBUTING.md for the development workflow and test commands. Please report reproducible bugs through the issue tracker.

Citation

Run citation("fmrireg") for the current package citation.

License

fmrireg is licensed under the MIT License.