Skip to contents

Construct a Covariate Term

Source: R/covariate.R
covariate.Rd

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

...

Covariate expressions. Each expression may evaluate to a numeric vector, matrix, or data frame. Matrix/data-frame columns are expanded into separate regressors.

data

A data.frame containing the variables.

id

An optional term identifier. As elsewhere in fmridesign, the identifier becomes the term tag prepended to final design-matrix columns.

prefix

An optional term-tag prefix used when id is not supplied.

subset

Optional expression used to subset the covariate data.

Value

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

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.

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
)