HRFBold

HRFBold#

class brainmass.HRFBold(k_1=5.6, V_0=0.02, period=Quantity(1000., 'ms'), downsample_period=Quantity(4., 'ms'), kernel=None, convolution_mode='valid', method='fft', history=None)#

Convolution-based fMRI BOLD observation (HRF kernel).

Forms the BOLD signal by convolving downsampled neural activity with a closed-form hemodynamic response function (HRF) kernel, then decimating to the repetition time (TR). The pipeline is:

  1. Downsample neural activity from the simulation step dt to downsample_period with a TemporalAverage.

  2. Convolve each region’s series (after prepending a warm-up history, zeros by default) with kernel evaluated on the downsample_period grid.

  3. Scale to BOLD: \(\mathrm{BOLD} = k_1 V_0 (c - 1)\), where \(c\) is the convolution output (the -1 removes the unit baseline, matching the TVB convention).

  4. Decimate to the TR by taking every round(period / downsample_period) sample.

Unlike the four-state Balloon-Windkessel ODE in brainmass.BOLDSignal, this is a single linear convolution – fast, simple and fully differentiable in its scalar parameters, which makes it the natural choice for fitting. Prefer brainmass.BOLDSignal when biophysical realism matters. Both are kept.

Parameters:

  • k_1 (float) – BOLD signal scaling factor (default 5.6).

  • V_0 (float) – Resting blood volume fraction (default 0.02).

  • period (brainunit.Quantity) – Final BOLD sampling period / TR (default 1000 * u.ms).

  • downsample_period (brainunit.Quantity) – Intermediate downsampling period the kernel is sampled on (default 4 * u.ms).

  • kernel (HRFKernel) – HRF kernel to convolve with (default FirstOrderVolterraHRFKernel).

  • convolution_mode ({'valid', 'same', 'full'}) – Convolution edge mode (default 'valid'; with the zero history prepend this yields a causal output of length T_ds + 1).

  • method ({'fft', 'direct'}) – 'fft' uses jax.scipy.signal.fftconvolve(); 'direct' uses jax.numpy.convolve(). They agree numerically (default 'fft').

  • history (array-like, optional) – Warm-up buffer prepended before convolution, shape (round(duration / downsample_period), *regions). None (default) prepends zeros.

See also

brainmass.BOLDSignal

the physiologically detailed Balloon-Windkessel ODE BOLD.

TemporalAverage

the windowed-mean downsampler used internally.

Examples

>>> import brainmass
>>> import brainunit as u
>>> import jax.numpy as jnp
>>> t = jnp.arange(2000.)
>>> z = 1.0 + 0.5 * jnp.sin(2 * jnp.pi * t[:, None] / 800.0)
>>> bold = brainmass.HRFBold(
...     period=200. * u.ms, downsample_period=4. * u.ms,
...     kernel=brainmass.FirstOrderVolterraHRFKernel(duration=400. * u.ms),
... )
>>> y = bold(z, dt=1. * u.ms)
>>> y.shape[1]
1
__init__(k_1=5.6, V_0=0.02, period=Quantity(1000., 'ms'), downsample_period=Quantity(4., 'ms'), kernel=None, convolution_mode='valid', method='fft', history=None)[source]#