Fcontrasts: Get block/run indices

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

Get block/run indices

Description

Get the block or run number associated with each scan/timepoint in the dataset. Block indices are used to:

• Track which scans belong to which runs

• Split data by experimental blocks

• Align events with their corresponding runs

• Apply run-specific processing

Get the number of scans or timepoints in each block/run of the dataset. Block lengths are used to:

• Define the temporal structure of the experiment by specifying scan counts and timing per run

• Allocate memory for data matrices by pre-allocating arrays based on scan counts

• Validate data dimensions across runs by checking against expected lengths

• Calculate global timing information by computing cumulative timing across runs

Create F-contrasts to test for overall effects of model terms. F-contrasts are used to:

categorical

Test for any effect of a categorical predictor

basis

Compare multiple basis functions simultaneously

nonlinear

Test for nonlinear effects of continuous predictors

overall

Evaluate overall significance of model terms

Usage

Fcontrasts(x, ...)

## S3 method for class 'convolved_term'
Fcontrasts(x, ...)

Arguments

x	The model term to generate contrasts for (typically an event_term or event_model)
...	Additional arguments passed to methods. Common arguments include: basis Character; type of basis functions used nbasis Integer; number of basis functions exclude Character vector of conditions to exclude

Value

A numeric vector where:

• Each element is the block/run ID for that scan

• IDs are sequential integers starting from 1

• Length matches the total number of scans

A numeric vector where:

• Each element is the number of scans in a block or run

• Length equals the number of blocks/runs

• Values are positive integers

A list of contrast specifications where each contains:

weights

Matrix of contrast weights

term

The model term being tested

name

Descriptive name for the contrast

df

Degrees of freedom for the contrast

See Also

blocklens(), split_by_block(), sampling_frame() Get block/run lengths

blockids(), split_by_block(), sampling_frame() Generate F-contrasts for a model term

event_model(), contrast_weights()

Other block_operations: split_by_block()

Other block_operations: split_by_block()

Examples

# Create a sampling frame with multiple runs
sframe <- sampling_frame(
  blocklens = c(50, 75, 50),  # Different length runs
  TR = 2
)

# Get block IDs for all scans
block_ids <- blockids(sframe)
# Returns: c(1,1,...,1, 2,2,...,2, 3,3,...,3)
# 50 ones, 75 twos, 50 threes

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

# Get block IDs from dataset
dataset_blocks <- blockids(dset)

# Use block IDs to split data by run
run_data <- split(1:nrow(X), dataset_blocks)
# Returns list with indices for each run
# Create a sampling frame with varying run lengths
sframe <- sampling_frame(
  blocklens = c(100, 150, 100),  # Different length runs
  TR = 2
)

# Get number of scans per run
run_lengths <- blocklens(sframe)  # Returns: c(100, 150, 100)

# Use block lengths to create a dataset
total_scans <- sum(run_lengths)  # 350 total timepoints
X <- matrix(rnorm(total_scans * 10), total_scans, 10)  # 10 voxels
dset <- fmridataset::matrix_dataset(
  X,
  TR = 2,
  run_length = run_lengths
)

# Verify block lengths in dataset
dset_lengths <- blocklens(dset)

# Use lengths to create time vectors for each run
time_vectors <- lapply(run_lengths, function(len) seq(0, by = 2, length.out = len))
# Create event data with multiple conditions
event_data <- data.frame(
  condition = factor(c("A", "B", "C", "A", "B", "C")),
  rt = c(0.8, 1.2, 0.9, 1.1, 0.7, 1.3),
  onsets = c(1, 10, 20, 30, 40, 50),
  run = c(1, 1, 1, 1, 1, 1)
)

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

# Create event model with multiple terms
evmodel <- event_model(
  onsets ~ hrf(condition) + hrf(rt),
  data = event_data,
  block = ~run,
  sampling_frame = sframe
)

# Get F-contrast for main effect of condition
cond_contrast <- Fcontrasts(evmodel)

# Create model with multiple basis functions
evmodel2 <- event_model(
  onsets ~ hrf(condition, basis = "fourier", nbasis = 3),
  data = event_data,
  block = ~run,
  sampling_frame = sframe
)

# Get F-contrasts testing all basis functions
basis_contrasts <- Fcontrasts(evmodel2)

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