dot-resample_param: Simulate fMRI Time Courses, Return Shared Onsets +...

In bbuchsbaum/fmrireg: R package for the anlysis of fmri data

Simulate fMRI Time Courses, Return Shared Onsets + Column-Specific Amplitudes/Durations

Description

Generates n time-series (columns) with a single set of onsets, but resampled amplitudes/durations for each column if amplitude_sd>0 or duration_sd>0. Each column also gets independent noise. The result is a list containing:

• time_series: a matrix_dataset with T \times n. The event_table uses the first column's amplitude/duration draws.

• ampmat: an n\_events \times n matrix of per-column amplitudes.

• durmat: an n\_events \times n matrix of per-column durations.

• hrf_info: info about the HRF.

• noise_params: info about noise generation (type + AR coefficients + SD).

Usage

.resample_param(
  base,
  sd,
  dist = c("lognormal", "gamma", "gaussian"),
  allow_negative = FALSE
)

Arguments

base	Base values to resample from
sd	Standard deviation for resampling
dist	Distribution to use for resampling
allow_negative	Whether to allow negative values
n	Number of time-series (columns).
total_time	Numeric. Total scan length (seconds).
TR	Numeric. Repetition time (seconds).
hrf	Hemodynamic response function, e.g. fmrihrf::HRF_SPMG1.
n_events	Number of events (ignored if onsets is provided).
onsets	Optional numeric vector of event onsets. If NULL, will be generated.
isi_dist	One of "even", "uniform", or "exponential". Default is "even" so events are evenly spaced from 0..total_time.
isi_min, isi_max	For isi_dist="uniform".
isi_rate	For isi_dist="exponential".
durations	Numeric, scalar or length-n_events. If duration_sd>0, random sampling is done per column.
duration_sd	Numeric. If >0, random variation in durations.
duration_dist	"lognormal" or "gamma" (strictly positive).
amplitudes	Numeric, scalar or length-n_events. If amplitude_sd>0, random sampling is done per column.
amplitude_sd	Numeric. If >0, random variation in amplitudes.
amplitude_dist	"lognormal", "gamma", or "gaussian" (can be negative).
single_trial	If TRUE, each event is a separate single-trial regressor that gets summed.
noise_type	"none", "white", "ar1", or "ar2".
noise_ar	Numeric vector for AR(1) or AR(2). If missing or insufficient, defaults are used (0.3 for AR(1); c(0.3,0.2) for AR(2)).
noise_sd	Std dev of the noise.
random_seed	Optional integer for reproducibility.
verbose	If TRUE, prints messages.

Details

• If noise_type="ar1" and you do not provide noise_ar, we default to c(0.3).

• If noise_type="ar2" and you do not provide a 2-element noise_ar, we default to c(0.3, 0.2).

• Onsets are either provided or generated once for all columns.

• Amplitudes/durations are re-sampled inside the loop so each column can differ randomly. The final arrays ampmat and durmat each have one column per time-series.

• The matrix_dataset's event_table records the first column's amplitudes/durations. If you need each column's, see ampmat and durmat.

Value

A list containing:

time_series

A matrix_dataset with T \times n data and event_table for the first column's random draws.

ampmat

An n\_events \times n numeric matrix of amplitudes.

durmat

An n\_events \times n numeric matrix of durations.

hrf_info

A list with HRF metadata.

noise_params

A list describing noise generation.

bbuchsbaum/fmrireg documentation built on June 10, 2025, 8:18 p.m.