onsets: Return a set of data chunks

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

Return a set of data chunks

Description

Split a dataset into manageable chunks for processing. This is particularly useful for parallel processing of large fMRI datasets. Chunks can be created either by run (runwise=TRUE) or by dividing the data into a specified number of pieces. Each chunk contains a subset of the data and metadata about its position in the full dataset.

Extract the onset times of events from a model object. Onsets represent the timing of experimental events in an fMRI design, typically in seconds from the start of each run. These times are used to:

• Create regressors by convolving with HRF

• Verify event timing in the design

• Analyze temporal patterns of events

Usage

onsets(x)

Arguments

x	The object containing event information (typically an event_term or event_model)
nchunks	Integer; number of chunks to create (ignored if runwise=TRUE)
...	Additional arguments passed to methods. Common arguments include: runwise Logical; if TRUE, create one chunk per run parallel Logical; if TRUE, prepare chunks for parallel processing

Value

An iterator object that yields data chunks, where each chunk contains:

data

Matrix of data values for this chunk

chunk_num

Index of this chunk

voxel_ind

Indices of voxels in this chunk

row_ind

Indices of timepoints in this chunk

A numeric vector of onset times in seconds, where:

• Each value represents the start time of an event

• Times are relative to the start of each run

• Order matches the original event sequence

See Also

matrix_dataset(), fmri_dataset(), foreach::foreach() Get event onsets from an object

event_term(), event_model(), global_onsets()

Other timing: durations(), nbasis(), split_by_block()

Examples

# Create a simple matrix dataset
X <- matrix(rnorm(100 * 1000), 100, 1000)  # 100 timepoints, 1000 voxels
dset <- fmridataset::matrix_dataset(
  X, 
  TR = 2,
  run_length = c(50, 50)  # Two runs of 50 timepoints each
)

# Create chunks by run
run_chunks <- fmridataset::data_chunks(dset, runwise = TRUE)

# Process each run chunk
foreach::foreach(chunk = run_chunks) %do% {
  # chunk$data contains the data for one run
  # chunk$row_ind shows which timepoints are included
  mean_signal <- colMeans(chunk$data)
}

# Create arbitrary number of chunks
vox_chunks <- fmridataset::data_chunks(dset, nchunks = 4)

# Process chunks in parallel
foreach::foreach(chunk = vox_chunks) %dopar% {
  # chunk$data contains subset of voxels
  # chunk$voxel_ind shows which voxels are included
  apply(chunk$data, 2, sd)
}
# Create event data with multiple conditions
event_data <- data.frame(
  condition = factor(c("face", "house", "face", "house")),
  onsets = c(1, 10, 20, 30),
  run = c(1, 1, 1, 1)
)

# Create sampling frame
sframe <- sampling_frame(blocklens = 50, TR = 2)

# Create event term
eterm <- event_term(
  list(condition = event_data$condition),
  onsets = event_data$onsets,
  blockids = event_data$run
)

# Get onsets from term
onset_times <- onsets(eterm)  # Returns: c(1, 10, 20, 30)

# Create and get onsets from event model
evmodel <- event_model(
  onsets ~ hrf(condition),
  data = event_data,
  block = ~run,
  sampling_frame = sframe
)

model_onsets <- onsets(evmodel)

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