Package 'fmridesign'

Description

Generates a baselinespec for modeling low-frequency drift in fMRI time series.

Usage

baseline(
  degree = 1,
  basis = c("constant", "poly", "bs", "ns"),
  name = NULL,
  intercept = c("runwise", "global", "none")
)

Arguments

Value

A baselinespec list instance.

Examples

baseline(degree = 3, basis = "bs")

Description

Builds a baseline model to account for noise and non-event-related variance. This model may include a drift term, a block intercept term, and nuisance regressors.

Usage

baseline_model(
  basis = c("constant", "poly", "bs", "ns"),
  degree = 1,
  sframe,
  intercept = c("runwise", "global", "none"),
  nuisance_list = NULL,
  nuisance_check = c("warn", "error", "drop", "none"),
  na_action = c("drop", "zero", "median")
)

Arguments

Value

An object of class "baseline_model".

Examples

sframe <- fmrihrf::sampling_frame(blocklens = c(100, 100), TR = 2)
bmod <- baseline_model(basis = "bs", degree = 3, sframe = sframe)
bmod_global <- baseline_model(basis = "bs", degree = 3, sframe = sframe, intercept = "global")
bmod_nointercept <- baseline_model(basis = "bs", degree = 3, sframe = sframe, intercept = "none")
stopifnot(ncol(design_matrix(bmod)) == 8)

Description

Extract baseline terms

Usage

## S3 method for class 'baseline_model'
baseline_terms(x, ...)

baseline_terms(x, ...)

Arguments

Value

A named list of baseline term objects.

Examples

sframe <- fmrihrf::sampling_frame(blocklens = 6, TR = 1)
bmod <- baseline_model(sframe = sframe)
baseline_terms(bmod)

Description

Generates the ⁠_b##⁠ suffix for HRF basis functions.

Usage

basis_suffix(j, nb)

Arguments

Value

Character vector of suffixes (e.g., ⁠_b01⁠, ⁠_b02⁠).

Examples

basis_suffix(1:3, 5)
basis_suffix(1:10, 10)

Description

Returns a block variable that is constant over the span of a scanning run.

Usage

block(x)

Arguments

Value

An object of class "blockspec".

Examples

block(run)

Description

Creates a generator function for use with the hrf_fun parameter in hrf(). The generator produces boxcar HRFs where each event's duration determines the boxcar width.

Usage

boxcar_hrf_gen(normalize = TRUE, min_duration = 0.1)

Arguments

Value

A function that takes an event data frame and returns a list of HRF objects.

See Also

weighted_hrf_gen() for weighted impulse HRFs

Examples

trial_data <- data.frame(
  onset = c(0, 10, 25),
  duration = c(2, 5, 3),
  condition = c("A", "B", "A"),
  run = 1
)
sf <- fmrihrf::sampling_frame(blocklens = 50, TR = 2)

emod <- event_model(
  onset ~ hrf(condition, hrf_fun = boxcar_hrf_gen()),
  data = trial_data, block = ~run, sampling_frame = sf, durations = trial_data$duration
)
print(emod)

Description

Generate the B-spline basis matrix for a polynomial spline.

Usage

BSpline(x, degree)

Arguments

Value

an BSpline list instance

See Also

bs

Examples

x_vals <- seq(0, 1, length.out = 6)
bs_obj <- BSpline(x_vals, degree = 3)
dim(bs_obj$y)
bs_obj$name

Description

Extract cells from a design object

Usage

## S3 method for class 'baseline_model'
cells(x, drop.empty = TRUE, ...)

cells(x, drop.empty = TRUE, ...)

## S3 method for class 'event'
cells(x, drop.empty = TRUE, ...)

## S3 method for class 'event_term'
cells(x, drop.empty = TRUE, ...)

## S3 method for class 'covariate_convolved_term'
cells(x, ...)

Arguments

Value

A data.frame/tibble of cells (categorical combinations) relevant to x.

Examples

sframe <- fmrihrf::sampling_frame(blocklens = 6, TR = 1)
bmod <- baseline_model(sframe = sframe)
head(cells(bmod))

Description

Convenience helper to quickly flag highly correlated regressors.

Usage

check_collinearity(X, threshold = 0.9)

Arguments

Value

A list with elements: ok (logical), pairs (data.frame with offending pairs and their correlations). Invisibly returns the same list.

Examples

# Create a simple event model
des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emodel <- event_model(onset ~ hrf(cond), data = des, block = ~run,
                      sampling_frame = sframe)

# Check for multicollinearity
res <- check_collinearity(design_matrix(emodel), threshold = 0.95)
if (!res$ok) print(res$pairs)

Description

Inspects a block-wise nuisance regressor list before it is added to a baseline model. The check is run per block and compares nuisance columns against the baseline terms that would be constructed from basis, degree, and intercept.

Usage

check_nuisance(
  nuisance_list,
  sframe,
  basis = c("constant", "poly", "bs", "ns"),
  degree = 1,
  intercept = c("runwise", "global", "none"),
  tol = sqrt(.Machine$double.eps),
  duplicate_threshold = 1 - sqrt(.Machine$double.eps),
  na_action = c("drop", "zero", "median")
)

Arguments

Value

A nuisance_check object with ok, problems, by_block, and normalized nuisance_list elements.

Description

Drops nuisance columns that are non-finite, zero-variance, or fail to increase QR rank after the block's baseline terms and earlier nuisance columns. Column order is respected, so when two columns are aliased the earlier column is kept.

Usage

clean_nuisance(
  nuisance_list,
  sframe,
  basis = c("constant", "poly", "bs", "ns"),
  degree = 1,
  intercept = c("runwise", "global", "none"),
  tol = sqrt(.Machine$double.eps),
  duplicate_threshold = 1 - sqrt(.Machine$double.eps),
  na_action = c("drop", "zero", "median")
)

Arguments

Value

A list with nuisance_list and report elements. Pass result$nuisance_list to baseline_model().

Description

Define a contrast by directly targeting design matrix columns using regex patterns. This is useful for contrasts involving continuous variables or specific basis functions.

Usage

column_contrast(pattern_A, pattern_B = NULL, name, where = NULL)

Arguments

Details

This contrast type operates by finding design matrix columns whose names match the provided patterns (pattern_A, pattern_B). It calculates weights such that the average effect of the 'A' columns is compared to the average effect of the 'B' columns (or baseline if pattern_B is NULL). Weights are assigned as +1/nA for 'A' columns and -1/nB for 'B' columns, ensuring the contrast sums to zero if both A and B groups are present.

Use standard R regex syntax for the patterns. Remember to escape special characters (e.g., ⁠\\[⁠, ⁠\\.⁠, ⁠\\*⁠).

Value

A column_contrast_spec object containing the specification.

Examples

# Test the main effect of a continuous modulator 'RT'
# Assumes RT is a column name, e.g., from columns(Scale(RT))
cc1 <- column_contrast(pattern_A = "^z_RT$", name = "Main_RT")

# Compare Condition.A vs Condition.B for the 'RT' modulator effect
# Assumes condition names like "Condition.A_z_RT", "Condition.B_z_RT"
cc2 <- column_contrast(pattern_A = "^Condition\\.A_z_RT$",
                       pattern_B = "^Condition\\.B_z_RT$",
                       name = "CondA_vs_CondB_for_RT")

# Test a specific basis function (e.g., basis spline #3)
# Assumes column names like "TermName_Condition.Tag_b03"
cc3 <- column_contrast(pattern_A = "_b03$", name = "Basis_3_Effect")

Description

Extract columns

Usage

## S3 method for class 'Scale'
columns(x, ...)

## S3 method for class 'ScaleWithin'
columns(x, ...)

## S3 method for class 'RobustScale'
columns(x, ...)

columns(x, ...)

Arguments

Value

Character vector of column names produced by the object.

Examples

bs_basis <- BSpline(seq(0, 1, length.out = 5), degree = 3)
columns(bs_basis)

Description

A lightweight wrapper around convolve() that post-processes the resulting design matrix into a named list of T x d matrices - one per experimental condition ("base condition tag"). This keeps all of the heavy lifting inside fmrireg while exposing a minimal, pipe-friendly API that can be used anywhere a condition -> basis split is required (e.g. for CFALS).

Usage

condition_basis_list(
  x,
  hrf,
  sampling_frame,
  ...,
  output = c("condition_list", "matrix")
)

Arguments

Value

A numeric matrix or a named list of matrices, depending on output.

Examples

term <- event_term(
  list(condition = factor(c("A", "B", "A"))),
  onsets = c(0, 10, 20),
  blockids = c(1, 1, 1)
)
sf <- fmrihrf::sampling_frame(blocklens = 30, TR = 1)
condition_basis_list(term, fmrihrf::HRF_SPMG1, sf)

Description

Map Display and Canonical Condition Names

Usage

condition_map(x, drop.empty = TRUE, expand_basis = FALSE, ...)

Arguments

Value

A tibble mapping display names to canonical names.

Examples

term <- event_term(
  list(
    category = factor(c("face", "scene", "face")),
    attention = factor(c("attend", "attend", "ignore"))
  ),
  onsets = c(0, 10, 20),
  blockids = c(1, 1, 1)
)
condition_map(term)

Description

Extract conditions from a design object

Usage

conditions(
  x,
  drop.empty = TRUE,
  expand_basis = FALSE,
  style = c("canonical", "display"),
  ...
)

## S3 method for class 'event_term'
conditions(
  x,
  drop.empty = TRUE,
  expand_basis = FALSE,
  style = c("canonical", "display"),
  ...
)

Arguments

Value

A character vector of condition names.

Examples

term <- event_term(
  list(condition = factor(c("A", "B", "A"))),
  onsets = c(0, 10, 20),
  blockids = c(1, 1, 1)
)
conditions(term)
conditions(term, style = "display")
conditions(term, expand_basis = TRUE)

Description

Construct method

Usage

## S3 method for class 'baselinespec'
construct(x, model_spec, ...)

## S3 method for class 'covariatespec'
construct(x, model_spec, sampling_frame = NULL, ...)

construct(x, ...)

Arguments

Value

A constructed object; return type depends on method.

Examples

sframe <- fmrihrf::sampling_frame(blocklens = 5, TR = 1)
drift_spec <- baseline(degree = 2, basis = "poly")
construct(drift_spec, sframe)

Description

Define a linear contrast using a formula expression.

Usage

contrast(form, name, where = NULL)

Arguments

Value

A list containing the contrast specification.

Examples

# A minus B contrast using display labels
contrast(~ A - B, name="A_B")

# With subsetting
contrast(~ A - B, name="A_B_block1", where = ~ block == 1)

Description

Drives the unified post-processing pipeline: expands the base mask across basis functions (when applicable), applies basis filtering, attaches the standard contrast list class, and returns an object compatible with downstream contrast_weights.event_model().

Usage

contrast_from_mask(mask, spec, term, classes = character())

Arguments

Details

Custom contrast types implement contrast_mask() and call this driver.

Value

A contrast object.

Description

contrast_mask() is the extension point for new contrast types: it returns a base contrast matrix with one row per base condition (no basis expansion) and one column per contrast column. The unified driver contrast_from_mask() handles basis expansion, basis filtering and packaging into a contrast object compatible with contrast_weights.event_model().

Usage

contrast_mask(x, term, ...)

Arguments

Details

To register a custom contrast type:

1. Define a constructor that produces a list with class c("my_spec", "contrast_spec", "list").

2. Implement contrast_mask.my_spec() returning the base weights.

3. Implement contrast_weights.my_spec() as a one-liner:

   contrast_weights.my_spec <- function(x, term, ...) {
     contrast_from_mask(contrast_mask(x, term, ...), x, term)
   }
   

The built-in spec classes (pair_contrast_spec, oneway_contrast_spec, poly_contrast_spec, ...) implement contrast_weights() directly, so they do not require contrast_mask() methods.

Value

A list with elements:

• weights : numeric matrix, ⁠n_base_conditions x n_contrast_cols⁠, row names = base condition names.

• condnames : character vector of base condition names.

Description

Construct a list of contrast_spec objects.

Usage

contrast_set(...)

Arguments

Value

A list of contrast_spec objects with class "contrast_set".

Examples

c1 <- contrast(~ A - B, name="A_B")
c2 <- contrast(~ B - C, name="B_C")
contrast_set(c1,c2)

Description

Compute the contrast weights for a unit_contrast_spec object.

Compute the contrast weights for an oneway_contrast_spec object.

Compute the contrast weights for an interaction_contrast_spec object.

Compute the contrast weights for a poly_contrast_spec object.

Compute the contrast weights for a pair_contrast_spec object.

Compute contrast weights for a column_contrast_spec object by targeting design matrix columns based on regex patterns.

Compute the contrast weights for a contrast_formula_spec object.

Compute the contrast weights for a contrast_diff_spec object.

Compute the contrast weights for each contrast specification within a contrast_set object.

Usage

## S3 method for class 'unit_contrast_spec'
contrast_weights(x, term, ...)

## S3 method for class 'oneway_contrast_spec'
contrast_weights(x, term, ...)

## S3 method for class 'interaction_contrast_spec'
contrast_weights(x, term, ...)

## S3 method for class 'poly_contrast_spec'
contrast_weights(x, term, ...)

## S3 method for class 'pair_contrast_spec'
contrast_weights(x, term, ...)

## S3 method for class 'column_contrast_spec'
contrast_weights(x, term, ...)

## S3 method for class 'contrast_formula_spec'
contrast_weights(x, term, ...)

## S3 method for class 'contrast_diff_spec'
contrast_weights(x, term, ...)

## S3 method for class 'contrast_set'
contrast_weights(x, term, ...)

contrast_weights(x, ...)

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

## S3 method for class 'event_model'
contrast_weights(x, ...)

Arguments

Details

If the weight matrices returned by a contrast specification contain row names, these are matched to the column names of the corresponding term in the design matrix. This allows contrasts to target only a subset of term levels.

Value

A list containing the term, name, weights, condition names, and contrast specification.

A list containing the term, name, weights, condition names, and contrast specification.

A list containing the term, name, weights, condition names, and contrast specification.

A list containing the term, name, weights, condition names, and contrast specification.

A list containing the term, name, weights, condition names, and contrast specification.

A list containing the contrast details:

A list containing the term, name, weights, condition names, and contrast specification.

A list containing the term, name, weights, condition names, and contrast specification.

A named list where each element is the result of calling contrast_weights on the corresponding contrast_spec in the set. The list names are the names of the individual contrasts.

A named list of contrast weight objects or matrices.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
cset <- contrast_set(
  diff = column_contrast(pattern_A = "cond.A", pattern_B = "cond.B", name = "diff")
)
emod <- event_model(onset ~ hrf(cond, contrasts = cset),
                    data = des, block = ~run, sampling_frame = sframe)
contrast_weights(emod)

Description

Extract contrasts

Usage

contrasts(x, ...)

Arguments

Value

A named list of contrast specifications.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
cset <- contrast_set(
  diff = column_contrast(pattern_A = "cond.A", pattern_B = "cond.B", name = "diff")
)
emod <- event_model(onset ~ hrf(cond, contrasts = cset),
                    data = des, block = ~run, sampling_frame = sframe)
contrasts(emod)

Description

This function collects the contrast specifications defined for each term within the model and returns them as a named list.

Usage

## S3 method for class 'event_model'
contrasts(x, ...)

Arguments

Value

A named list of contrast specifications.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
cset <- contrast_set(
  diff = column_contrast(pattern_A = "cond.A", pattern_B = "cond.B", name = "diff")
)
emod <- event_model(onset ~ hrf(cond, contrasts = cset),
                    data = des, block = ~run, sampling_frame = sframe)
contrasts(emod)

Description

This accessor returns the list of contrast specifications attached to the term's originating hrfspec, if any.

Usage

## S3 method for class 'event_term'
contrasts(x, ...)

Arguments

Value

A list of contrast specifications or NULL when none are defined.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
cset <- contrast_set(
  diff = column_contrast(pattern_A = "cond.A", pattern_B = "cond.B", name = "diff")
)
emod <- event_model(onset ~ hrf(cond, contrasts = cset),
                    data = des, block = ~run, sampling_frame = sframe)
contrasts(terms(emod)[[1]])

Description

Retrieve contrast specifications from an hrfspec

Usage

## S3 method for class 'hrfspec'
contrasts(x, ...)

Arguments

Value

The list of contrast specifications attached to the hrfspec, or NULL.

Examples

condition <- factor(c("A", "B"))
cset <- contrast_set(
  diff = column_contrast(pattern_A = "condition.A", pattern_B = "condition.B", name = "diff")
)
spec <- hrf(condition, contrasts = cset)
contrasts(spec)

Description

Convolve events with a hemodynamic response function

Usage

convolve(
  x,
  hrf,
  sampling_frame,
  drop.empty = TRUE,
  summate = TRUE,
  precision = 0.1,
  normalize = FALSE,
  ...
)

## S3 method for class 'event_term'
convolve(
  x,
  hrf,
  sampling_frame,
  drop.empty = TRUE,
  summate = TRUE,
  precision = 0.3,
  normalize = FALSE,
  ...
)

Arguments

Value

A matrix-like (often tibble) of convolved regressors.

Examples

term <- event_term(
  list(condition = factor(c("A", "B", "A"))),
  onsets = c(0, 5, 10),
  blockids = c(1, 1, 1)
)
sf <- fmrihrf::sampling_frame(blocklens = 20, TR = 1)
conv <- convolve(term, fmrihrf::HRF_SPMG1, sf)
names(conv)

Description

Convolves a HRF with a design matrix (one column per condition) to produce a list of regressors.

Usage

convolve_design(hrf, dmat, globons, durations, summate = TRUE, hrf_list = NULL)

Arguments

Value

A list of regressors (one for each column).

Examples

hrf <- fmrihrf::HRF_SPMG1
dmat <- data.frame(A = c(1, 0, 1), B = c(0, 1, 0))
globons <- c(0, 10, 20)
durations <- rep(0, 3)
regs <- convolve_design(hrf, dmat, globons, durations)
length(regs)

Description

Compute correlation map

Usage

correlation_map(x, ...)

Arguments

Value

A ggplot2 object visualizing regressor correlations.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run, sampling_frame = sframe)
correlation_map(emod)

Description

Generates a correlation heatmap of the columns in a baseline_model's design matrix.

Usage

## S3 method for class 'baseline_model'
correlation_map(
  x,
  method = c("pearson", "spearman"),
  half_matrix = FALSE,
  absolute_limits = TRUE,
  ...
)

Arguments

Value

A ggplot2 plot object.

Examples

sframe <- fmrihrf::sampling_frame(blocklens = 5, TR = 1)
bmod <- baseline_model(sframe = sframe)
if (requireNamespace("ggplot2", quietly = TRUE)) correlation_map(bmod)

Description

Creates a heatmap visualization of the correlation matrix between regressors in an event_model object.

Usage

## S3 method for class 'event_model'
correlation_map(x, rotate_x_text = TRUE, ...)

Arguments

Value

A ggplot2 object showing the correlation matrix heatmap.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run, sampling_frame = sframe)
correlation_map(emod)

Description

Creates a covariate term that is added directly to the fMRI model without being convolved with a hemodynamic response function (HRF). This is useful for including nuisance variables, continuous covariates, or any other regressors that should not undergo HRF convolution.

Usage

covariate(..., data, id = NULL, prefix = NULL, subset = NULL)

Arguments

Details

In fMRI analysis, some predictors should not be convolved with the HRF because they represent:

• Continuous physiological measurements (e.g., heart rate, respiration)

• Motion parameters from head movement correction

• Scanner drift or other technical artifacts

• Behavioral measures that directly correlate with BOLD signal

• Global signal or other nuisance variables

The covariate term can be combined with standard HRF-convolved event terms in the same model. For example:

model <- event_model(onset ~ hrf(stimulus) + covariate(motion_x, motion_y, data = cov_data), 
                    data = events, block = ~ 1, sampling_frame = sframe)

Value

A list containing information about the covariate term with class 'covariatespec' that can be used within an event_model.

See Also

• event_model() for creating complete fMRI models

• hrf() for creating HRF-convolved event terms

Examples

# Add motion parameters as covariates
motion_data <- data.frame(
  x = rnorm(100),  # x translation
  y = rnorm(100)   # y translation
)
cv <- covariate(x, y, data = motion_data, prefix = "motion")

# Combine with event model
sframe <- sampling_frame(blocklens = c(100), TR = 2)
# 50 events, strictly increasing onsets per block
event_data <- data.frame(
  stimulus = factor(rep(c("A", "B"), 25)),
  onset = seq(0, by = 4, length.out = 50)
)

# Full model with both HRF-convolved events and non-convolved covariates
model <- event_model(
  onset ~ hrf(stimulus) + covariate(x, y, data = motion_data, id = "motion"),
  data = event_data,
  block = ~ 1,
  sampling_frame = sframe
)

Description

Returns a tibble with one row per column of the design matrix and structured metadata (term, condition, basis, role, run, etc.).

Usage

design_colmap(x, ...)

Arguments

Value

A tibble with per-column metadata.

Examples

# Create a simple event model
des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run, sampling_frame = sframe)

# Extract column metadata
colmap <- design_colmap(emod)
head(colmap)

# Query specific columns
colmap[colmap$condition == "A", ]

Description

Returns a tibble with one row per column of the design matrix and structured metadata derived from existing package attributes and naming conventions. This avoids ad-hoc string parsing in user code and provides a consistent, queryable view of the design.

Usage

## S3 method for class 'event_model'
design_colmap(x, ...)

Arguments

Value

A tibble with columns:

• col (integer): 1-based column index

• name (character): column name

• term_tag (character): term identifier (event tag or baseline term name)

• term_index (integer): position within terms(x)

• condition (character): condition/event label without basis suffix (if applicable)

• run (integer): block/run id when the column is block-specific; NA if pooled

• role (character): e.g., "task", "drift", "intercept", "nuisance"

• model_source (character): "event" or "baseline"

• basis_name (character): HRF or baseline basis identifier when available

• basis_ix (integer): within-condition basis index (HRF component); NA if not applicable

• basis_total (integer): total number of basis components for the column's term; NA if not applicable

• basis_label (character): human-readable label for the basis component when known

• pretty_name (character): concise, human-friendly label for display (e.g., "RT" or "RT_lag_02")

• is_block_diagonal (logical): TRUE when the regressor is per-run/block

• modulation_type (character): "amplitude", "parametric", or "covariate"

• modulation_id (character): modulator identifier when applicable (e.g., "RT", "RT_by_group")

Examples

# Create event model
des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run, sampling_frame = sframe)

# Get column metadata
colmap <- design_colmap(emod)
head(colmap)

# Query columns by condition
colmap[colmap$condition == "A", ]

Description

Compute design map

Usage

design_map(x, ...)

Arguments

Value

A ggplot2 object visualizing the design matrix.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run, sampling_frame = sframe)
design_map(emod)

Description

Produces a heatmap of all columns in the design matrix for a baseline_model object, with rows corresponding to scans and columns corresponding to regressors. By default, it draws horizontal lines separating runs (blocks), and rotates the column labels diagonally.

Usage

## S3 method for class 'baseline_model'
design_map(
  x,
  block_separators = TRUE,
  rotate_x_text = TRUE,
  fill_midpoint = NULL,
  fill_limits = NULL,
  ...
)

Arguments

Value

A ggplot2 plot object.

Examples

sframe <- fmrihrf::sampling_frame(blocklens = 5, TR = 1)
bmod <- baseline_model(sframe = sframe)
if (requireNamespace("ggplot2", quietly = TRUE)) design_map(bmod)

Description

Creates a heatmap visualization of the design matrix for an event_model object.

Usage

## S3 method for class 'event_model'
design_map(
  x,
  block_separators = TRUE,
  rotate_x_text = TRUE,
  fill_midpoint = NULL,
  fill_limits = NULL,
  ...
)

Arguments

Value

A ggplot2 object showing the design matrix heatmap.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run, sampling_frame = sframe)
design_map(emod)

Description

Extract or construct a design matrix

Usage

## S3 method for class 'baseline_model'
design_matrix(x, blockid = NULL, allrows = FALSE, ...)

## S3 method for class 'baseline_term'
design_matrix(x, blockid = NULL, allrows = FALSE, ...)

design_matrix(x, ...)

## S3 method for class 'event_model'
design_matrix(x, blockid = NULL, ...)

## S3 method for class 'event_term'
design_matrix(x, drop.empty = TRUE, ...)

Arguments

Value

A matrix-like object (often tibble) with rows = scans, cols = regressors.

Examples

sframe <- fmrihrf::sampling_frame(blocklens = 6, TR = 1)
bmod <- baseline_model(sframe = sframe)
head(design_matrix(bmod))

Description

Returns the col_metadata tibble attached to a design matrix produced by event_model(). If the attribute is missing (e.g., on a manually constructed matrix) returns NULL.

Usage

design_meta(x)

Arguments

Value

A tibble, or NULL.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des,
                    block = ~run, sampling_frame = sframe)
design_meta(emod)

Description

Generator for use with the hrf_fun parameter in hrf(). Creates per-onset HRFs by convolving a base HRF with a boxcar of each event's duration, then normalizing to peak = 1. This preserves the temporal shape of the duration-modulated response while equalizing amplitude across events.

Usage

duration_hrf_gen(base = fmrihrf::HRF_SPMG1, min_duration = 0)

Arguments

Value

A function for use with hrf_fun in hrf().

See Also

boxcar_hrf_gen() for duration-based boxcar HRFs

Examples

# Events with variable durations
trial_data <- data.frame(
  onset = c(0, 10, 25),
  duration = c(2, 5, 3),
  condition = c("A", "B", "A"),
  run = 1
)
sf <- fmrihrf::sampling_frame(blocklens = 50, TR = 2)

emod <- event_model(
  onset ~ hrf(condition, hrf_fun = duration_hrf_gen()),
  data = trial_data, block = ~run, sampling_frame = sf,
  durations = trial_data$duration
)
print(emod)

Description

Extract elements from an object

Usage

elements(x, ...)

## S3 method for class 'event'
elements(x, what = c("values", "labels"), transformed = TRUE, ...)

## S3 method for class 'event_term'
elements(x, what = c("values", "labels"), ...)

Arguments

Value

Requested elements; structure depends on method (e.g., numeric values or labels).

Examples

# Create an event term with mixed categorical and continuous events
term <- event_term(
  list(
    condition = factor(c("A", "B", "A", "B")),
    intensity = c(1.2, 0.8, 1.5, 0.9)
  ),
  onsets = c(0, 10, 20, 30),
  blockids = c(1, 1, 1, 1)
)

# Extract values (actual numeric/factor codes)
elements(term, what = "values")

# Extract labels (descriptive names/levels)
elements(term, what = "labels")

Description

This is a user-facing wrapper around the internal event() constructor, specifically for creating event sequences modulated by a basis set.

Usage

event_basis(
  basis,
  name = NULL,
  onsets,
  blockids = 1,
  durations = 0,
  subset = NULL
)

Arguments

Value

An S3 object of class event and event_seq.

Examples

basis <- BSpline(1:21, 3)
onsets <- seq(0, 20, length.out = 21)
blockids <- rep(1, length(onsets))
ebasis <- event_basis(basis, onsets=onsets, blockids=blockids)
print(ebasis)
levels(ebasis)

Description

Retrieve per-event condition assignments

Usage

event_conditions(x, drop.empty = FALSE, ...)

Arguments

Value

Typically a factor aligned with the events of x.

Examples

term <- event_term(
  list(condition = factor(c("A", "B", "A"))),
  onsets = c(0, 10, 20),
  blockids = c(1, 1, 1)
)
event_conditions(term)

Description

This is a user-facing wrapper around the internal event() constructor, specifically for creating categorical event sequences from factors or characters.

Usage

event_factor(fac, name, onsets, blockids = 1, durations = 0, subset = NULL)

Arguments

Value

An S3 object of class event and event_seq.

See Also

event_model, event_variable, event_matrix, event_basis

Examples

ef_onsets <- seq(1, 100, length.out = 6)
efac <- event_factor(factor(c("a", "b", "c", "a", "b", "c")), "abc", 
        onsets = ef_onsets, blockids = rep(1, length(ef_onsets)))
print(efac)
levels(efac)

Description

This is a user-facing wrapper around the internal event() constructor, specifically for creating continuous event sequences from numeric matrices.

Usage

event_matrix(mat, name, onsets, blockids = 1, durations = 0, subset = NULL)

Arguments

Value

An S3 object of class event and event_seq.

Examples

mat <- matrix(rnorm(20), 10, 2, dimnames=list(NULL, c("Val1", "Val2")))
onsets <- seq(1, 100, length.out = 10)
durations <- rep(1, 10)
blockids <- rep(1, 10)
eset <- event_matrix(mat, "eset", onsets, blockids, durations)
print(eset)
columns(eset) # Alias for levels

Description

This file contains the generic functions used throughout the fmridesign package. These generics define the interface for working with event models, baseline models, and related design components. Construct an event model

This is the main constructor for event_model objects. It unifies the previous formula and list-based interfaces and uses a more efficient internal pipeline.

Usage

event_model(
  formula_or_list,
  data,
  block,
  sampling_frame,
  durations = 0,
  drop_empty = TRUE,
  precision = 0.3,
  parallel = FALSE,
  progress = FALSE,
  strict = FALSE,
  ...
)

event_model(
  formula_or_list,
  data,
  block,
  sampling_frame,
  durations = 0,
  drop_empty = TRUE,
  precision = 0.3,
  parallel = FALSE,
  progress = FALSE,
  strict = FALSE,
  ...
)

Arguments

Details

This function creates an event-based fMRI regression model, represented as a data structure.

Column Naming

The columns in the resulting design matrix follow the naming convention: term_tag + ⁠_⁠ + condition_tag + ⁠_b##⁠ basis suffix

Where:

• term_tag: The unique tag assigned to the hrf() term (see below).

• condition_tag: Represents the specific factor level or continuous regressor within the term (e.g., condition.A, poly_RT_01, condition.A_task.go).

• ⁠_b##⁠: Optional suffix added for HRFs with multiple basis functions (e.g., ⁠_b01⁠, ⁠_b02⁠).

Term Naming and Clash Resolution

Each term in the model (typically defined by an hrf() call in a formula) gets a unique term_tag. This tag is used as the prefix for all columns generated by that term.

• Default Naming: If no explicit id (or name) is given in hrf(), the tag is derived from the variable names (e.g., hrf(condition) -> condition, hrf(RT, acc) -> RT_acc).

• Explicit Naming: Use ⁠id=⁠ within hrf() for an explicit tag (e.g., hrf(condition, id="CondMain")).

• Sanitization: Dots (.) in tags are converted to underscores (⁠_⁠).

• Clash Resolution: If multiple terms generate the same tag, ⁠#⁠ and a number are appended to ensure uniqueness (e.g., condition, condition#1).

This consistent naming scheme replaces the previous compact and qualified styles.

Value

An event_model object describing the task design.

An object of class c("event_model", "list") containing the terms, design matrix, sampling frame, and other metadata.

Examples

des <- data.frame(onset = seq(0, 90, by=10),
                  run = rep(1:2, each=5),
                  cond = factor(rep(c("A","B"), 5)),
                  mod = rnorm(10))
sframe <- fmrihrf::sampling_frame(blocklens=c(50, 60), TR=2)

ev_model_form <- event_model(onset ~ hrf(cond) + hrf(mod, basis="spmg3"),
                            data = des, block = ~run, sampling_frame = sframe)
print(ev_model_form)
head(design_matrix(ev_model_form))

spec1 <- hrf(cond)
spec2 <- hrf(mod, basis = "spmg3")
ev_model_list <- event_model(list(spec1, spec2), data = des,
                             block = des$run, sampling_frame = sframe)
print(ev_model_list)

Description

Extract event table

Usage

event_table(x, ...)

Arguments

Value

A data.frame/tibble of event rows.

Examples

term <- event_term(
  list(condition = factor(c("A", "B", "A"))),
  onsets = c(0, 10, 20),
  blockids = c(1, 1, 1)
)
event_table(term)

Description

Generates an event_term object which represents the combination of one or more event sequences (e.g., a factor crossed with a numeric modulator). It takes a list of variables (factors, numeric vectors, matrices, basis objects) along with shared onsets, block IDs, and durations. It uses the EV factory internally to create standardized event objects for each variable.

Usage

event_term(evlist, onsets, blockids, durations = 0, subset = NULL)

Arguments

Value

A list object with class c("event_term", "event_seq"). Contains:

Examples

x1 <- factor(rep(letters[1:3], 10))
x2 <- factor(rep(1:3, each = 10))
onsets <- seq(1, 100, length.out = 30)
blockids <- rep(1:3, each = 10)

eterm <- event_term(list(Condition = x1, Group = x2),
                    onsets = onsets,
                    blockids = blockids)
print(eterm)
head(event_table(eterm))
levels(eterm)
head(design_matrix(eterm))

term <- event_term(
  list(condition = factor(c("A", "B", "A"))),
  onsets = c(0, 10, 20),
  blockids = c(1, 1, 1)
)
head(design_matrix(term))

Description

Extract event terms

Usage

event_terms(x, ...)

Arguments

Value

A named list of event term objects.

Examples

# Create a simple experimental design
des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run, sampling_frame = sframe)

# Extract event terms (named list of event term objects)
terms_list <- event_terms(emod)
names(terms_list)

Description

This is a user-facing wrapper around the internal event() constructor, specifically for creating continuous event sequences from numeric vectors.

Usage

event_variable(vec, name, onsets, blockids = 1, durations = 0, subset = NULL)

Arguments

Value

An S3 object of class event and event_seq.

See Also

event_factor

Examples

ev_onsets <- seq(1, 100, length.out = 6)
evar <- event_variable(c(1, 2, 3, 4, 5, 6), "example_var", 
                       onsets = ev_onsets, blockids = rep(1, length(ev_onsets)))
print(evar)
is_continuous(evar)

Description

Retrieve canonical event information

Usage

events(x, drop.empty = FALSE, ...)

Arguments

Value

A data.frame (or tibble) with onset, duration, block, and condition columns.

Examples

# Create an event term with condition factor
term <- event_term(
  list(condition = factor(c("A", "B", "A"))),
  onsets = c(0, 10, 20),
  blockids = c(1, 1, 1)
)

# Extract canonical event information
evt_info <- events(term)
print(evt_info)

Description

Compute F-contrasts

Usage

Fcontrasts(x, ...)

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

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

Arguments

Details

Row names of the contrast matrices can specify which levels of the term are tested. Any matching is done against the design matrix column names.

Value

A named list of matrices with F-contrast weights.

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30),
  run = 1,
  cond = factor(c("A", "B", "A", "B"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run, sampling_frame = sframe)
names(Fcontrasts(emod))

Description

Generates the f## suffix for multi-column continuous events.

Usage

feature_suffix(j, nf)

Arguments

Value

Character vector of suffixes (e.g., f01, f02).

Examples

feature_suffix(1:3, 5)

Description

Returns all function names that should be recognized in formulas from registered external packages.

Usage

get_all_external_hrf_functions()

Value

Character vector of function names

Examples

register_hrfspec_extension(
  spec_class = "demo_hrfspec",
  package = "demoPkg",
  formula_functions = "demo_hrf"
)
get_all_external_hrf_functions()

Description

Accepts either a single class name or a class vector (the typical output of class(x)). Returns the first matching registration entry, walking the class vector from most-specific to least-specific so a subclass's registration takes precedence over its parent.

Usage

get_basis_entry(class_name)

Arguments

Value

Registration entry (a list) or NULL if no class is registered.

Examples

get_basis_entry("Poly")

Description

Returns the function name(s) that should be recognized in formulas for a given external HRF specification class.

Usage

get_external_hrfspec_functions(spec_class)

Arguments

Value

Character vector of function names, or NULL if not registered

Examples

register_hrfspec_extension(
  spec_class = "demo_hrfspec",
  package = "demoPkg",
  formula_functions = c("demo_hrf", "demo_trialwise")
)
get_external_hrfspec_functions("demo_hrfspec")

Description

Get Information About a Registered External HRF Specification

Usage

get_external_hrfspec_info(spec_class)

Arguments

Value

A list with registration information, or NULL if not registered

Examples

register_hrfspec_extension(
  spec_class = "demo_hrfspec",
  package = "demoPkg",
  requires_external_processing = TRUE,
  formula_functions = "demo_hrf"
)
get_external_hrfspec_info("demo_hrfspec")

Description

This function is to be used in formulas for fitting functions, e.g. onsets ~ hrf(fac1,fac2) ... It captures the variables/expressions provided and packages them with HRF/contrast information into an hrfspec object, which is then processed by event_model.

Usage

hrf(
  ...,
  basis = "spmg1",
  hrf_fun = NULL,
  onsets = NULL,
  durations = NULL,
  prefix = NULL,
  subset = NULL,
  precision = 0.3,
  nbasis = 1,
  contrasts = NULL,
  id = NULL,
  name = NULL,
  lag = 0,
  summate = TRUE,
  normalize = FALSE
)

Arguments

Value

an hrfspec instance

Examples

form1 <- onsets ~ hrf(condition, basis="spmg1")

form2 <- onsets ~ hrf(condition) + hrf(RT)

form3 <- onsets ~ hrf(condition, RT, basis="spmg3")

library(rlang)
con1 <- pair_contrast(~ condition == "A", ~ condition == "B", name="AvB")
form4 <- onsets ~ hrf(condition, Poly(RT, 2), contrasts=con1)

form5 <- onsets ~ hrf(condition, hrf_fun = boxcar_hrf_gen())

form6 <- onsets ~ hrf(condition,
                      hrf_fun = weighted_hrf_gen("sub_times", "sub_weights"))

Description

A basis that applies identity transform to a set of raw variables.

Usage

Ident(...)

Arguments

Value

an instance of class Ident extending ParametricBasis

Examples

# Create identity basis from numeric vectors
x <- c(1, 2, 3, 4, 5)
y <- c(2, 4, 6, 8, 10)
ident_basis <- Ident(x, y)
print(ident_basis$y)

Description

Create an interaction contrast specification

Usage

interaction_contrast(A, name, where = NULL)

Arguments

Value

An interaction_contrast_spec object containing the specification for generating interaction contrast weights

See Also

oneway_contrast for main effects, pair_contrast for pairwise comparisons

Examples

# Create an interaction contrast for factors A and B
con <- interaction_contrast(~ A * B, name = "A_by_B")

# Create an interaction contrast with a 'where' clause
con <- interaction_contrast(~ A * B, name = "A_by_B",
                          where = ~ block == 1)

Description

Check if categorical

Usage

is_categorical(x, ...)

## S3 method for class 'event'
is_categorical(x, ...)

Arguments

Value

Logical scalar indicating whether x is categorical.

Examples

# Create a categorical event from factor data
cat_event <- event_factor(
  factor(c("faces", "houses", "faces", "houses")),
  name = "condition",
  onsets = c(0, 10, 20, 30),
  blockids = rep(1, 4)
)
is_categorical(cat_event)  # Returns TRUE

# Create a continuous event from numeric data
cont_event <- event_variable(
  c(1.2, 0.8, 1.5, 0.9),
  name = "reaction_time",
  onsets = c(0, 10, 20, 30),
  blockids = rep(1, 4)
)
is_categorical(cont_event)  # Returns FALSE

# Event term with mixed types is considered categorical
mixed_term <- event_term(
  list(condition = factor(c("A", "B", "A", "B")),
       modulator = c(1.1, 0.9, 1.2, 0.8)),
  onsets = c(0, 10, 20, 30),
  blockids = rep(1, 4)
)
is_categorical(mixed_term)  # Returns TRUE

Description

Check if continuous

Usage

is_continuous(x, ...)

## S3 method for class 'event'
is_continuous(x, ...)

Arguments

Value

Logical scalar indicating whether x is continuous.

Examples

# Create a continuous event from numeric vector
cont_event <- event_variable(
  c(1.2, 0.8, 1.5, 0.9),
  name = "reaction_time",
  onsets = c(0, 10, 20, 30),
  blockids = rep(1, 4)
)
is_continuous(cont_event)  # Returns TRUE

# Create a continuous event from matrix
mat_event <- event_matrix(
  matrix(c(1.1, 0.9, 1.2, 0.8, 2.1, 1.9, 2.2, 1.8), nrow = 4),
  name = "coordinates",
  onsets = c(0, 10, 20, 30),
  blockids = rep(1, 4)
)
is_continuous(mat_event)  # Returns TRUE

# Categorical event is not continuous
cat_event <- event_factor(
  factor(c("faces", "houses", "faces", "houses")),
  name = "condition",
  onsets = c(0, 10, 20, 30),
  blockids = rep(1, 4)
)
is_continuous(cat_event)  # Returns FALSE

# Event term with all continuous events
cont_term <- event_term(
  list(rt = c(1.1, 0.9, 1.2, 0.8),
       accuracy = c(0.95, 0.87, 0.92, 0.88)),
  onsets = c(0, 10, 20, 30),
  blockids = rep(1, 4)
)
is_continuous(cont_term)  # Returns TRUE

Description

Check if a Class is a Registered External HRF Specification

Usage

is_external_hrfspec(x)

Arguments

Value

Logical indicating if the class is registered as an external HRF spec

Examples

register_hrfspec_extension(
  spec_class = "demo_hrfspec",
  package = "demoPkg"
)
is_external_hrfspec("demo_hrfspec")

Description

Returns a character vector of formatted labels for an event object, using the Variable[Level] style for categorical events, Variable[Index] for multi-column continuous events, or just Variable for single continuous events. Useful for getting consistent labels for individual event components. This is distinct from levels() which returns the raw level names or column names. Relies on the internal .level_vector helper function.

Usage

## S3 method for class 'event'
labels(object, ...)

Arguments

Value

A character vector of formatted labels, or character(0) if not applicable.

Examples

fac <- factor(rep(c("A", "B"), 3))
onsets <- 1:6
ev_fac <- event_factor(fac, "Condition", onsets, blockids = rep(1, length(onsets)))
labels(ev_fac) # Should return c("Condition[A]", "Condition[B]")

vals <- 1:6
ev_num <- event_variable(vals, "Modulator", onsets, blockids = rep(1, length(onsets)))
labels(ev_num) # Should return "Modulator"

mat <- matrix(1:12, 6, 2)
colnames(mat) <- c("C1", "C2")
ev_mat <- event_matrix(mat, "MatrixVar", onsets, blockids = rep(1, length(onsets)))
labels(ev_mat) # Should return c("MatrixVar[1]", "MatrixVar[2]")

Description

Extract levels from various fmrireg objects. These methods extend the base R levels generic to work with fmrireg-specific classes.

Usage

## S3 method for class 'Scale'
levels(x, ...)

## S3 method for class 'ScaleWithin'
levels(x, ...)

## S3 method for class 'RobustScale'
levels(x, ...)

## S3 method for class 'event'
levels(x, ...)

## S3 method for class 'event'
columns(x, ...)

Arguments

Value

A character vector of levels or names, depending on the object type:

• For categorical events: the factor levels

• For continuous events: the column names (matrices) or variable name (vectors)

• For scale objects: the variable name being scaled

Functions

• columns(event): Alias for levels.event

Examples

# Create a categorical event
fac_event <- event_factor(
  factor(c("A", "B", "A", "B")),
  name = "condition",
  onsets = c(1, 10, 20, 30),
  blockids = rep(1, 4)
)
levels(fac_event)  # Returns: c("A", "B")

# Create a continuous event
cont_event <- event_variable(
  c(1.2, 0.8, 1.5, 0.9),
  name = "reaction_time",
  onsets = c(1, 10, 20, 30),
  blockids = rep(1, 4)
)
levels(cont_event)  # Returns: "reaction_time"

Description

List All Registered External HRF Specifications

Usage

list_external_hrfspecs()

Value

A character vector of registered class names

Examples

register_hrfspec_extension(
  spec_class = "demo_hrfspec",
  package = "demoPkg"
)
list_external_hrfspecs()

Description

List Registered Parametric Basis Classes

Usage

list_registered_bases()

Value

Character vector of registered class names.

Examples

list_registered_bases()

Description

Superseded by conditions(x, style = "canonical").

Usage

longnames(x, ...)

Arguments

Value

Character vector of long (fully qualified) names.

Examples

# Create a simple event term with one condition factor
term <- event_term(
  list(condition = factor(c("A", "B", "A"))),
  onsets = c(0, 10, 20),
  blockids = c(1, 1, 1)
)
longnames(term)  # Returns: "condition.A" "condition.B"

# Create event term with multiple factors
term2 <- event_term(
  list(
    category = factor(c("face", "scene", "face")),
    attention = factor(c("attend", "attend", "ignore"))
  ),
  onsets = c(0, 10, 20),
  blockids = c(1, 1, 1)
)
longnames(term2)
# Returns: "category.face_attention.attend"
#          "category.scene_attention.attend"
#          "category.face_attention.ignore"

Description

Get number of basis functions from hrfspec

Usage

## S3 method for class 'hrfspec'
nbasis(x, ...)

Arguments

Value

The number of basis functions

Examples

# Create hrfspec with canonical HRF (1 basis function)
spec1 <- hrf(condition, basis = "spmg1")
nbasis(spec1)

# Create hrfspec with derivative HRF (2 basis functions)
spec2 <- hrf(condition, basis = "spmg2")
nbasis(spec2)

# Create hrfspec with FIR basis (custom number of basis functions)
spec3 <- hrf(condition, basis = "fir", nbasis = 10)
nbasis(spec3)

Description

Returns a nuisance term specification from a numeric matrix.

Usage

nuisance(x)

Arguments

Value

An object of class "nuisancespec".

Examples

mat <- matrix(rnorm(10), nrow = 5)
nuisance(mat)

Description

Construct contrasts comparing each factor level against the average of the other levels.

Usage

one_against_all_contrast(levels, facname, where = NULL)

Arguments

Value

A contrast_set object containing contrasts comparing each factor level against the average of the other levels.

Examples

fac <- factor(rep(c("A", "B", "C"), 2))
con <- one_against_all_contrast(levels(fac), "fac")

Description

Create a one-way contrast specification

Usage

oneway_contrast(A, name, where = NULL, basis = NULL, basis_weights = NULL)

Arguments

Value

A oneway_contrast_spec object that can be used to generate contrast weights

See Also

interaction_contrast for testing interactions, pair_contrast for pairwise comparisons

Examples

# Create a one-way contrast for a factor 'basis'
con <- oneway_contrast(~ basis, name = "Main_basis")

# Create a one-way contrast with a 'where' clause
con <- oneway_contrast(~ basis, name = "Main_basis",
                      where = ~ block == 1)

# Test only first two basis functions
con <- oneway_contrast(~ condition, name = "Main_early", basis = 1:2)

Description

Construct a sum-to-zero contrast between two logical expressions. This function is particularly useful for comparing specific conditions or combinations of conditions.

Usage

pair_contrast(A, B, name, where = NULL, basis = NULL, basis_weights = NULL)

Arguments

Details

The contrast is constructed as (A - B), where A and B are logical expressions that evaluate to TRUE/FALSE for each observation. The resulting contrast weights sum to zero.

When using multi-basis HRFs (e.g., bspline with 5 basis functions), the basis argument allows you to test specific temporal components of the response. For example:

• basis = 1: Test only the first basis function (often the canonical/early response)

• basis = 2:3: Test the second and third basis functions together

• basis = NULL or basis = "all": Test all basis functions (default behavior)

The basis_weights argument allows non-uniform weighting across selected basis functions:

• basis_weights = c(.1, .2, .4, .2, .1): Gaussian-like emphasis on peak

• basis_weights = c(1, 0, 0, 0, 0): Isolate first basis (equivalent to basis = 1)

• Weights are applied within each condition, maintaining contrast sum-to-zero property

Value

A pair_contrast_spec object containing:

See Also

pairwise_contrasts for all pairwise comparisons, contrast_set for creating sets of contrasts

Examples

# Compare faces vs scenes (all basis functions)
pair_contrast(~ category == "face", ~ category == "scene", name = "face_vs_scene")

# Test only the second basis function (e.g., linear component for polynomial HRF)
pair_contrast(~ category == "face", ~ category == "scene",
             basis = 2, name = "face_vs_scene_basis2")

# Test early response components (first 3 basis functions)
pair_contrast(~ category == "face", ~ category == "scene",
             basis = 1:3, name = "face_vs_scene_early")

# Compare with subsetting
pair_contrast(~ category == "face", ~ category == "scene",
             name = "face_vs_scene_block1",
             where = ~ block == 1)

# Complex logical expressions
pair_contrast(~ stimulus == "face" & emotion == "happy",
             ~ stimulus == "face" & emotion == "sad",
             name = "happy_vs_sad_faces")

Description

Construct pairwise contrasts for all combinations of factor levels.

Usage

pairwise_contrasts(levels, facname, where = NULL, name_prefix = "con")

Arguments

Value

A contrast_set object containing pairwise contrasts for all combinations of factor levels.

Examples

# Assuming 'my_factor' is a column name
pairwise_contrasts(c("A", "B", "C"), facname = "my_factor")
pairwise_contrasts(c("A", "B", "C"), facname = "my_factor", name_prefix = "pair")

Description

Generic function for plotting contrasts.

Usage

plot_contrasts(x, ...)

Arguments

Value

A plot object (typically ggplot2) displaying the contrasts. The exact type depends on the method used.

Examples

# Create example data
des <- data.frame(
  onset = c(1, 3, 5, 7),
  cond = factor(c("A", "B", "A", "B")),
  run = c(1, 1, 1, 1)
)

# Create sampling frame and event model
sframe <- fmrihrf::sampling_frame(blocklens = 40, TR = 1)

# Create contrast set
cset <- contrast_set(
  main_A = unit_contrast(~ cond == "A", name = "A_vs_baseline"),
  diff = pair_contrast(~ cond == "A", ~ cond == "B", name = "A_vs_B")
)

# Create event model with contrasts
emod <- event_model(onset ~ hrf(cond, contrasts = cset),
                    data = des, block = ~run, sampling_frame = sframe)

# Plot the contrasts
plot_contrasts(emod)

Description

Produces a heatmap of all contrasts defined for an event_model. Rows = each contrast (or column of an F-contrast), columns = each regressor in the full design matrix, and the fill color = the contrast weight.

Usage

## S3 method for class 'event_model'
plot_contrasts(
  x,
  absolute_limits = FALSE,
  rotate_x_text = TRUE,
  scale_mode = c("auto", "diverging", "one_sided"),
  coord_fixed = TRUE,
  ...
)

Arguments

Value

A ggplot2 object (a heatmap).

Examples

# Create event model with contrasts
des <- data.frame(
  onset = c(0, 10, 20, 30, 40, 50),
  run = 1,
  cond = factor(c("A", "B", "C", "A", "B", "C"))
)
sframe <- fmrihrf::sampling_frame(blocklens = 60, TR = 1)
cset <- contrast_set(
  A_vs_B = pair_contrast(~ cond == "A", ~ cond == "B", name = "A_vs_B"),
  B_vs_C = pair_contrast(~ cond == "B", ~ cond == "C", name = "B_vs_C")
)
emod <- event_model(onset ~ hrf(cond, contrasts = cset),
                    data = des, block = ~run, sampling_frame = sframe)
plot_contrasts(emod)