split_by_block: Extract sampling times

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

Extract sampling times

Description

Get the sampling times for a regressor or sampling frame. These times represent when fMRI data was acquired and can be either relative (within each run) or global (cumulative across runs). Sampling times are used to:

• Evaluate regressors at scan acquisition times

• Align model predictions with data collection

• Convert between TR-based and time-based representations

Split a vector or matrix of values into separate pieces based on block/run IDs. This function is useful for:

• Separating data into individual runs

• Processing blocks independently

• Analyzing run-specific patterns

Usage

split_by_block(x, ...)

Arguments

x	The object containing data to split (typically a sampling_frame or dataset)
...	Additional arguments passed to methods
blockids	Numeric vector specifying which blocks/runs to include (optional)
global	Logical; if TRUE, return cumulative times across runs (default: FALSE)

Value

A numeric vector of sampling times in seconds, where:

• Each value represents a scan acquisition time

• Times account for TR (repetition time) spacing

• If global=FALSE, times reset at the start of each run

• If global=TRUE, times accumulate across runs

A list where each element contains data from one block:

• List length equals number of blocks

• Each element contains values from one block

• Order matches the original block sequence

See Also

sampling_frame(), regressor(), global_onsets() Split variables by block ID

sampling_frame(), blockids(), blocklens()

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

Other block_operations: Fcontrasts()

Examples

# Create a sampling frame with multiple runs
sframe <- sampling_frame(
  blocklens = c(100, 100, 100),  # 100 scans per run
  TR = 2,                        # 2 seconds per scan
  start_time = 0                 # Start at time 0
)

# Get relative sampling times (reset each run)
rel_times <- samples(sframe)
# First few times: 0, 2, 4, 6, ... (resets each run)

# Get global sampling times (cumulative)
glob_times <- samples(sframe, global = TRUE)
# Shows: 0, 2, 4, ..., 198, 200, 202, ..., 598

# Get times for specific runs
run2_times <- samples(sframe, blockids = 2)
# Times for second run only

# Create regressor and get its sampling times
event_data <- data.frame(
  onsets = c(1, 10, 20),
  run = c(1, 1, 1)
)
reg <- regressor(
  onsets = event_data$onsets,
  sampling_frame = sframe
)
reg_times <- samples(reg)
# Create a sampling frame with multiple runs
sframe <- sampling_frame(
  blocklens = c(50, 50, 50),  # 3 runs of 50 scans each
  TR = 2
)

# Create some example data
data_values <- rnorm(150)  # 150 values (50 per run)

# Split data by run
run_data <- split_by_block(sframe, data_values)
# Returns list with 3 elements, each containing 50 values

# Create matrix dataset
X <- matrix(rnorm(150 * 10), 150, 10)  # 150 timepoints, 10 voxels
dset <- fmridataset::matrix_dataset(
  X,
  TR = 2,
  run_length = c(50, 50, 50)
)

# Split matrix data by run
run_matrices <- split_by_block(dset)
# Returns list with 3 matrices, each 50 x 10

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