Skip to contents

fmrihrf

Hemodynamic response functions and event-related regressors for fMRI analysis in R.

fmrihrf provides a composable toolkit for constructing, modifying, and convolving HRFs with experimental designs. It ships with standard basis sets (SPM canonical, B-spline, Fourier, FIR, Gamma, Gaussian, and more), decorators for time-shifting and blocking, and a fast C++ convolution backend.

Installation 

# From CRAN
install.packages("fmrihrf")

# Development version
remotes::install_github("bbuchsbaum/fmrihrf")

Quick start 

library(fmrihrf)

# Evaluate the SPM canonical HRF over 0-30 seconds
t <- seq(0, 30, by = 0.1)
y <- evaluate(HRF_SPMG1, t)
plot(t, y, type = "l", xlab = "Time (s)", ylab = "Response")

# Build a regressor from event onsets
reg <- regressor(onsets = c(2, 10, 18), hrf = HRF_SPMG1,
                 duration = 0, amplitude = 1,
                 span = 24, sampling_frame = sampling_frame(blocklens = 100, TR = 1))
plot(reg)

Key features

Multiple basis sets — Use a single canonical HRF or a flexible basis set to capture response variability.

HRF_SPMG1                                    # SPM canonical (double gamma)
HRF_SPMG3                                    # canonical + temporal & dispersion derivatives
hrf_bspline(t, N = 6)                        # B-spline basis
hrf_fourier(t, N = 5)                        # Fourier basis

Decorators — Modify any HRF through functional composition.

lag_hrf(HRF_SPMG1, lag = 2)                  # shift peak by 2 s
block_hrf(HRF_SPMG1, width = 15)             # sustained/blocked response
normalise_hrf(HRF_SPMG1)                     # unit peak-normalised

Custom HRFs — Wrap any f(t) into the HRF system.

my_hrf <- as_hrf(function(t) exp(-t / 5), name = "exponential", span = 20)
evaluate(my_hrf, seq(0, 20, by = 1))

Regressor construction — Convolve events with HRFs to produce design-matrix columns, with support for variable durations, amplitudes, and multi-basis expansion.

sf <- sampling_frame(blocklens = c(200, 200), TR = 2)
reg <- regressor(onsets = c(10, 30, 50), hrf = HRF_SPMG1,
                 duration = c(0, 5, 0), amplitude = c(1, 1.5, 1),
                 sampling_frame = sf)
evaluate(reg)

Fast convolution — Core routines are implemented in C++ (Rcpp / RcppArmadillo) for efficient large-scale design matrix generation.

Documentation

Full documentation is available at https://bbuchsbaum.github.io/fmrihrf/.

Vignettes cover the main workflows:

Command Line

Install the package:

install.packages("fmrihrf")

Install the command wrapper:

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

If needed, add the directory to PATH:

export PATH="$HOME/.local/bin:$PATH"

Check the command:

fmrihrf --help

List available HRFs:

fmrihrf list --details

Evaluate a canonical HRF:

fmrihrf eval --hrf spmg1 --from 0 --to 30 --by 0.5

Evaluate a flexible basis set as JSON:

fmrihrf eval --hrf bspline --nbasis 6 --span 24 --json

Evaluate one event regressor on an acquisition grid:

fmrihrf regressor \
  --onsets 0,12,24 \
  --blocklens 200 \
  --tr 2 \
  --hrf spmg1 \
  --output regressor.csv

Build a design matrix from an event table:

fmrihrf design \
  --events events.csv \
  --blocklens 200,200 \
  --tr 2 \
  --hrf spmg1 \
  --output design.csv

The default event columns are onset, condition, block, duration, and amplitude. Use --onset, --condition, --block, --duration, and --amplitude when a table uses different column names.

License

MIT

Albers theme

This package uses the albersdown theme. Existing vignette theme hooks are replaced so albers.css and local albers.js render consistently on CRAN and GitHub Pages. The defaults are configured via params$family and params$preset (family = ‘red’, preset = ‘interaction’). The pkgdown site uses template: { package: albersdown } together with generated pkgdown/extra.css and pkgdown/extra.js so the theme is linked and activated on site pages.