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

blockids() on an event_model returns one run id per event, in event order: the run each onset belongs to. It does not return one id per scan. For per-scan run ids use blockids(x$sampling_frame). blocklens(x) gives the number of scans in each run.

Usage

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

Arguments

Details

fmrireg releases before its switch to fmridesign's method returned per-scan ids here whenever fmrireg was loaded. To flag the change, the first call in a session prints a one-time message (class fmridesign_blockids_per_event).

Value

Integer vector with one run id per event.

See Also

fmrihrf::blockids(), fmrihrf::blocklens()

Examples

sf <- fmrihrf::sampling_frame(blocklens = c(20, 20), TR = 2)
des <- data.frame(onset = c(0, 10, 0, 10, 20), run = c(1, 1, 2, 2, 2),
                  cond = factor(c("A", "B", "A", "B", "A")))
em <- event_model(onset ~ hrf(cond), data = des, block = ~run,
                  sampling_frame = sf)
blockids(em)                  # per event: 1 1 2 2 2
blockids(em$sampling_frame)   # per scan: 20 x 1, then 20 x 2
blocklens(em)                 # scans per run: 20 20

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_model'
cells(x, ...)

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

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

## S3 method for class 'feature_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. This is a pairwise check only: constant columns (including intercepts) are excluded, and ok = TRUE does not establish full rank, estimability or good contrast precision. Dependencies involving several columns, such as task regressors summing to an intercept in a no-rest design, can pass this check. Use check_estimability() on the full design, including baseline/nuisance regressors, to inspect those dependencies.

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

Diagnoses dependencies involving many regressors, including event regressors and the baseline. Unlike check_collinearity(), this uses the singular values of the full design rather than pairwise correlations.

Usage

check_estimability(
  x,
  contrasts = NULL,
  baseline = NULL,
  absolute = TRUE,
  condition_threshold = 10,
  coverage_threshold = 0.9,
  tol = 1e-08
)

## S3 method for class 'estimability_check'
print(x, ...)

Arguments

Details

Columns are scaled to unit Euclidean norm without centring, retaining the intercept. condition_number is the exact spectral ratio (largest/smallest singular value), or Inf for a numerically rank-deficient design. It is not the default approximation returned by kappa(). Zero columns are retained.

weakest_direction gives named loadings in the scaled coordinates and the corresponding coefficient direction in the original units. Its sign is arbitrary; when the smallest singular value is repeated, the direction is not unique. baseline_pattern labels a possible baseline-versus-regressors dependency when all loadings outside the baseline have one sign and baseline loadings have the opposite sign, in an ill-conditioned or deficient design. This is a heuristic interpretation, not proof of a particular task structure.

A contrast is estimable when it is orthogonal to the design's null space. Estimable contrasts receive a variance_factor, equal to $c'(X'X)^{-1}c$ for full-rank designs and the corresponding generalized inverse quadratic form otherwise. Non-estimable contrasts receive NA, never a misleading finite pseudoinverse variance. These are variances per unit independent residual variance in the original coefficient units; rescaling a contrast rescales its variance quadratically. F-contrast columns are assessed separately, not as an omnibus F statistic. For inference with temporal filtering or correlated errors, supply the actual filtered/whitened full design and matching contrasts.

Event coverage is the union of modelled event intervals, clipped to each run's ⁠[0, n_scans * TR)⁠ window. Overlapping events or repeated terms count once; zero-duration events occupy no time. Coverage uses retained event terms, including term-specific subsets/durations, and is unavailable (NULL) for raw matrices or models without event timing. High coverage suggests inspecting scientifically appropriate centred or reference-condition contrasts, which estimate different quantities from absolute coefficients.

Value

An estimability_check list with ok, rank, n_columns, n_observations, full_rank, condition_number, condition_threshold, ill_conditioned, singular_values, column_norms, weakest_direction, baseline_pattern, baseline (source and column names), contrasts (name, quantity, estimable, variance_factor, null_fraction), coverage (run, duration, covered, fraction, high_coverage), and explanatory messages. ok means full numerical rank and condition number within the threshold; it does not certify adequate precision for a scientific question.

See Also

validate_contrasts(), baseline_model()

Examples

# Every observation belongs to one task: absolute effects alias the intercept.
X <- cbind(task_A = c(1, 1, 0, 0), task_B = c(0, 0, 1, 1), intercept = 1)
check_collinearity(X)$ok
check_estimability(X, contrasts = list(A_vs_B = c(1, -1, 0)))

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.

Examples

sframe <- fmrihrf::sampling_frame(blocklens = 20, TR = 1)
motion <- cbind(
  linear = seq_len(20),
  duplicate = seq_len(20),
  constant = 1
)
report <- check_nuisance(list(motion), sframe, basis = "constant")
report$ok
report$by_block[[1]]$keep

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().

Examples

sframe <- fmrihrf::sampling_frame(blocklens = 20, TR = 1)
motion <- cbind(
  linear = seq_len(20),
  duplicate = seq_len(20),
  constant = 1
)
cleaned <- clean_nuisance(list(motion), sframe, basis = "constant")
colnames(cleaned$nuisance_list[[1]])

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

Weights are assigned as +1/nA to the nA columns matched by pattern_A and -1/nB to the nB columns matched by pattern_B, so the contrast compares the average effect of the 'A' columns with the average of the 'B' columns (or with baseline if pattern_B is NULL) and sums to zero when both groups are present. A contrast is evaluated within the single term it is attached to (via hrf(..., contrasts = )); only that term's columns are candidates.

What the patterns are matched against. Each pattern is matched, with grepl() semantics, against two names for every column of the term:

1. the design-matrix column name, exactly as shown by colnames(design_matrix(model)): term_tag_condition_tag, plus a ⁠_b##⁠ basis suffix for multi-basis HRFs (e.g. cond_cond.A, task_cond_task.face_cond.A, cond_cond.A_b02). See event_model() for the naming scheme and how the term tag is chosen;

2. the term-level condition name, i.e. the same name without the term_tag_ prefix (e.g. cond.A, cond.A_b02), as returned by conditions(term, expand_basis = TRUE). This is accepted for backward compatibility.

The design-matrix names take precedence: a pattern that matches at least one design-matrix column name selects exactly those columns, and the term-level names are consulted only when it matches none. Both routes therefore refer to the same columns ("^cond_cond\\.A$" and "^cond\\.A$" select the same column). If a pattern matches in both namespaces but selects different columns (for example, an unanchored "h" against hf_task.face and hf_task.house, where only task.house contains "h" at term level), the pattern is ambiguous and an error is raised; anchor it on the design-matrix names ("^hf_task\\.house$"). If a pattern matches nothing in either namespace a warning lists the available column names, and an error follows if neither pattern selected any column.

Use standard R regex syntax for the patterns. Remember to escape special characters (e.g., ⁠\\[⁠, ⁠\\.⁠, ⁠\\*⁠), and anchor patterns with ^ and $ to avoid accidental partial matches.

Value

A column_contrast_spec object containing the specification.

See Also

event_model() for the column naming scheme, pair_contrast() with ⁠basis = ⁠ for basis-restricted condition contrasts.

Examples

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

# Patterns written against the design-matrix column names
# (colnames are "cond_cond.A", "cond_cond.B")
cset <- contrast_set(
  column_contrast(pattern_A = "^cond_cond\\.A$",
                  pattern_B = "^cond_cond\\.B$", name = "A_vs_B")
)
emod <- event_model(onset ~ hrf(cond, contrasts = cset),
                    data = des, block = ~run, sampling_frame = sframe)
colnames(design_matrix(emod))
contrast_weights(emod)[["cond#A_vs_B"]]$offset_weights

# Multi-basis HRF: select only the first basis function (_b01) of each
# condition. Column names are "cond_cond.A_b01", "cond_cond.A_b02", ...
cset_mb <- contrast_set(
  column_contrast(pattern_A = "^cond_cond\\.A_b01$",
                  pattern_B = "^cond_cond\\.B_b01$", name = "A_vs_B_b01"),
  column_contrast(pattern_A = "_b01$", name = "canonical_mean")
)
emod_mb <- event_model(onset ~ hrf(cond, basis = "spmg3", contrasts = cset_mb),
                       data = des, block = ~run, sampling_frame = sframe)
colnames(design_matrix(emod_mb))
contrast_weights(emod_mb)[["cond#A_vs_B_b01"]]$offset_weights

# Legacy term-level patterns select the same columns
cc_legacy <- column_contrast(pattern_A = "^cond\\.A_b01$",
                             pattern_B = "^cond\\.B_b01$", name = "legacy")

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, ...)

## S3 method for class 'event_model'
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

For an event_model the result also has term and column_name: the design-matrix column of each condition, found by its canonical name (columns are ⁠<term tag>_<canonical>⁠). A condition with no column (an empty cell when drop.empty = FALSE, or a multi-basis term when expand_basis = FALSE) has column_name = NA.

Usage

## S3 method for class 'covariate_term'
condition_map(x, drop.empty = TRUE, expand_basis = FALSE, ...)

## S3 method for class 'covariate_convolved_term'
condition_map(x, drop.empty = TRUE, expand_basis = FALSE, ...)

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

## S3 method for class 'feature_term'
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

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

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

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

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"),
  ...
)

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

## S3 method for class 'feature_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, ...)

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

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.

Examples

term <- event_term(
  list(condition = factor(c("A", "B"))),
  onsets = c(0, 2),
  blockids = c(1, 1)
)
condition_names <- conditions(term, drop.empty = FALSE)
weights <- matrix(
  c(1, -1), ncol = 1,
  dimnames = list(condition_names, "A-B")
)
spec <- structure(
  list(name = "A-B", basis = NULL, basis_weights = NULL),
  class = c("example_contrast_spec", "contrast_spec", "list")
)
result <- contrast_from_mask(
  list(weights = weights, condnames = condition_names),
  spec,
  term
)
result$weights

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.

Examples

term <- event_term(
  list(condition = factor(c("A", "B"))),
  onsets = c(0, 2),
  blockids = c(1, 1)
)
spec <- structure(
  list(name = "A-B"),
  class = c("example_contrast_spec", "contrast_spec", "list")
)
contrast_mask.example_contrast_spec <- function(x, term, ...) {
  condition_names <- conditions(term, drop.empty = FALSE)
  weights <- matrix(
    c(1, -1), ncol = 1,
    dimnames = list(condition_names, x$name)
  )
  list(weights = weights, condnames = condition_names)
}
contrast_mask(spec, term)

Description

Construct a list of contrast_spec objects. Nested contrast_set arguments, including results from one_against_all_contrast() or pairwise_contrasts(), are recursively flattened in argument order. Individual specifications and their list names are preserved; names on enclosing sets are not used as prefixes. Empty sets contribute no specifications. Ordinary lists are not flattened; splice those explicitly with do.call(contrast_set, specs).

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)
contrast_set(c1, one_against_all_contrast(c("A", "B", "C"), "condition"))

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 the term's design matrix columns with regex patterns. Patterns are matched against the design-matrix column names (⁠term_tag_condition_tag[_b##]⁠) first and, only if they match none, against the term-level condition names; see column_contrast() for the precedence rules.

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, ...)

## S3 method for class 'feature_term'
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

Shows the pairwise correlations between design-matrix columns as the lower triangle of a matrix. The fill is the package's diverging palette, fixed at [-1, 1] by default with a neutral zero; for up to 20 columns each cell also prints r (two decimals for up to 10 columns). Cells with abs(r) at or above flag_threshold are outlined and counted in the subtitle, which also names the most strongly correlated pair.

Usage

## S3 method for class 'event_model'
correlation_map(
  x,
  rotate_x_text = TRUE,
  method = c("pearson", "spearman"),
  half_matrix = TRUE,
  limits = c("fixed", "data"),
  absolute_limits = NULL,
  annotate = NULL,
  flag_threshold = 0.5,
  vif_threshold = 5,
  title = "Regressor correlations",
  subtitle = NULL,
  within_run = FALSE,
  label_values = NULL,
  ...
)

## S3 method for class 'baseline_model'
correlation_map(
  x,
  method = c("pearson", "spearman"),
  half_matrix = TRUE,
  limits = c("fixed", "data"),
  absolute_limits = NULL,
  rotate_x_text = TRUE,
  annotate = NULL,
  flag_threshold = 0.5,
  vif_threshold = 5,
  title = "Baseline regressor correlations",
  subtitle = NULL,
  within_run = TRUE,
  label_values = NULL,
  ...
)

Arguments

Details

Pairwise correlations miss multicollinearity, so the diagonal shows each column's variance inflation factor, VIF_j = 1 / (1 - R2_j), from regressing column j on all other columns after removing each run's mean (per-run intercepts). VIFs at or above vif_threshold are drawn in a warning colour, and a column that is an exact linear combination of others is marked "aliased".

Correlations are computed over all scans of the full design matrix, with runs concatenated (as stated in the caption). Columns keep design order and are grouped by term, so the map lines up with design_map().

Value

A ggplot object.

See Also

design_map(), check_collinearity()

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)
bmod <- baseline_model(basis = "poly", degree = 2,
                       sframe = fmrihrf::sampling_frame(c(40, 40), TR = 1))
correlation_map(bmod)

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)

Final columns follow the package-wide term_tag_condition_tag convention. The default term tag is cov; id or prefix replaces it. Thus covariate(x, y, data = d) produces cov_x and cov_y, while id = "motion" produces motion_x and motion_y. Named matrix columns become condition tags; unnamed or duplicated matrix columns use deterministic feature_suffix() tags such as f01 and f02.

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")

# A matrix is expanded using its column names
lag_set <- cbind(lag_m2 = rnorm(100), lag_0 = rnorm(100),
                 lag_p2 = rnorm(100))
lag_data <- data.frame(row = seq_len(100))
lag_data$lag_set <- lag_set
cv_lags <- covariate(lag_set, data = lag_data, id = "alignment")

# 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", "covariate", or "feature"

• 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

Draws the design matrix as an image in the style of SPM: one row per scan (time runs downward), one column per regressor. Columns are grouped by model term under a spanner, runs are separated by thin rules and labelled in the left margin, and the right margin marks the first scan of each run.

Usage

## S3 method for class 'event_model'
design_map(
  x,
  block_separators = TRUE,
  rotate_x_text = TRUE,
  fill_midpoint = NULL,
  fill_limits = NULL,
  scale = c("column", "none"),
  palette = c("diverging", "grey"),
  y_axis = c("scan", "time"),
  title = "Design matrix",
  subtitle = NULL,
  max_labels = 60,
  ...
)

## S3 method for class 'baseline_model'
design_map(
  x,
  block_separators = TRUE,
  rotate_x_text = TRUE,
  fill_midpoint = NULL,
  fill_limits = NULL,
  scale = c("column", "none"),
  palette = c("diverging", "grey"),
  y_axis = c("scan", "time"),
  title = "Baseline design matrix",
  subtitle = NULL,
  max_labels = 60,
  ...
)

Arguments

Details

By default each column is divided by its maximum absolute value (scale = "column", stated in the legend) so regressors in different units share one fill scale; zero is always the neutral midpoint of the package's diverging palette. Because rescaling would make a near-flat regressor look healthy, real magnitudes stay visible: a strip of bars under the matrix shows each column's peak absolute value relative to the largest in its term, and columns below 5% of that (or all zero) are marked in orange, outlined over the matrix, and named in the subtitle. With 12 or fewer columns each label also carries the column's raw range. Use scale = "none" to plot raw values, or palette = "grey" for an SPM-style greyscale.

For baseline models, columns are grouped by term (drift, intercept, nuisance) and then run, with a "Run k" sub-spanner over each run's columns, so the block-diagonal structure reads as a staircase; nuisance columns are drawn at reduced opacity so they do not dominate.

Value

A ggplot object.

See Also

correlation_map(), plot_contrasts(), theme_fmridesign()

Examples

des <- data.frame(
  onset = c(0, 10, 20, 30, 5, 15, 25, 35),
  run = rep(1:2, each = 4),
  cond = factor(c("A", "B", "A", "B", "B", "A", "B", "A"))
)
sframe <- fmrihrf::sampling_frame(blocklens = c(40, 40), TR = 2)
emod <- event_model(onset ~ hrf(cond), data = des, block = ~run,
                    sampling_frame = sframe)
design_map(emod)
design_map(emod, palette = "grey", y_axis = "time")
bmod <- baseline_model(basis = "poly", degree = 3, sframe = sframe)
design_map(bmod)

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 'convolved_term'
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 = NULL,
  block = NULL,
  sampling_frame,
  durations = 0,
  drop_empty = TRUE,
  precision = 0.3,
  parallel = FALSE,
  progress = FALSE,
  strict = FALSE,
  ...
)

event_model(
  formula_or_list,
  data = NULL,
  block = NULL,
  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⁠).

Within a multi-basis term, columns are ordered condition-major: all basis functions of the first condition, then all of the second, and so on (⁠cond.A_b01, cond.A_b02, cond.B_b01, cond.B_b02, ...⁠). The order returned by conditions(term, expand_basis = TRUE) is the same.

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, ...)

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

## S3 method for class 'feature_term'
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, ...)

## S3 method for class 'feature_term'
events(x, ...)

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, ...)

## S3 method for class 'feature_term'
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.

For terms with a multi-basis HRF (e.g. "spmg2", "spmg3", FIR), the term-level contrast $C$ (one row per condition) is expanded to $C \otimes I_{nb}$: the condition effect is tested jointly in every basis function, so a term with $k$ conditions and $nb$ basis functions yields a $(k \cdot nb) \times ((k-1) \cdot nb)$ matrix for its main effect. Columns are named ⁠<contrast column>_b##⁠.

Terms with no categorical variable (e.g. hrf(rt), covariates, feature terms) contribute no F-contrasts; a model made only of such terms returns an empty list. Calling Fcontrasts() directly on such an event_term still signals an error.

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

Specify a continuously sampled feature (for example RMS energy) to be convolved with an HRF via fmrihrf::feature_regressor(). Unlike hrf(), this is a time series, not a list of trials.

Usage

feature(
  x,
  dt = NULL,
  times = NULL,
  start = 0,
  center = TRUE,
  scale = c("none", "sd"),
  mask = NULL,
  basis = "spmg1",
  nbasis = 1,
  lag = 0,
  span = NULL,
  precision = NULL,
  id = NULL,
  name = NULL,
  prefix = NULL
)

Arguments

Details

x may be a numeric vector or a samples-by-features matrix (one run), or a list of those with one element per sampling_frame block. Supply exactly one of dt or times. Feature-only models are allowed: event_model(~ feature(x, dt = 0.1, id = "rms"), sampling_frame = sframe).

Value

A featurespec object for use on the RHS of an event_model() formula or in the list interface.

See Also

fmrihrf::feature_regressor(), hrf(), event_model()

Examples

dt <- 0.5
rms <- abs(sin(seq(0, 20, by = dt)))
sframe <- sampling_frame(blocklens = 15, TR = 2)
emod <- event_model(
  ~ feature(rms, dt = dt, id = "rms", center = FALSE, scale = "none"),
  sampling_frame = sframe
)
ncol(design_matrix(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

fmridesign_palette() returns the package's categorical palette (a colour-vision-deficiency-checked ordering) or its diverging ramp, so custom plots can match the built-in ones.

Usage

fmridesign_palette(type = c("categorical", "diverging"), n = NULL)

Arguments

Value

A character vector of hex colours.

Examples

fmridesign_palette("categorical", 4)
fmridesign_palette("diverging", 11)

Description

Re-exported functions from the fmrihrf package for convenience. See the upstream fmrihrf documentation for details on usage and return values of each function.

Value

See the corresponding fmrihrf function documentation.

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