fsl_generate_fsf_lvl1_ev_syntax: This function generates syntax for FSL Feat .fsf files for...

In UNCDEPENdLab/fmri.pipeline: Analysis of fMRI Data on HPC clusters

This function generates syntax for FSL Feat .fsf files for the EVs tab of a first-level fMRI analysis. It accepts a numeric design matrix whose colum names correspond to individual EVs in the model

Description

This allows you to generate a design matrix dynamically based on a numeric matrix that has been setup in R using a function such as lm() to handle more complex designs appropriately. The syntax generated by this function can be combined with a .fsf template file to implement the entire LVL2 or LVL3 analysis setup.

Usage

fsl_generate_fsf_lvl1_ev_syntax(regressors)

Arguments

regressors

A list of regressors containing the specification for each one as an EV.

Details

Each element of the regressors list is itself a list specifying how to handle a given regressor. Required elements of the list are:

  $waveform: The type of input for this regressor. Options are:
     "custom_1"    : 1-column text file containing regressor values (can be convolved or unconvolved)
     "custom_3"    : 3-column FSL-format text file containing onset time, duration, and regressor value
     "empty"       : an all-zero regressor
     "square"      : for block design (not currently supported)
     "sinusoid"    : for periodic regressors (not currently supported)
     "interaction" : unclear what this is, but exists in .fsf files (not currently supported)

  $convolution: The type of convolution function to be applied to the $waveform. Options are:
     "none"         : no convolution is applied (esp. useful when using custom_1 files that are already convolved)
     "double_gamma" : convolve with FSL-variant of double gamma function
     "gaussian"     : convolve with Gaussian function (not tested)
     "gamma_basis"  : Gamma basis functions (not tested)
     "sine_basis"   : sine basis functions (not tested)
     "fir_basis"    : finite impulse response (FIR) basis functions (not tested)
     "alternate_double_gamma" : what it sounds like (not tested)

  $name: The name of the EV (i.e., regressor) in the model specification and output.

Optional elements of the list are:

  $timing_file: the name of the text file containing regressor values. Used by "custom_1" and "custom_3".
  $tempfilt: whether to apply temporal filtering to the regressor, as with the fMRI data. Default: 1 (TRUE)
  $deriv: whether to add a temporal derivative for this regressor to the model. Default 0 (FALSE)
  $convolve_phase: not entirely sure what it does but is 0/1. Default: 0 (FALSE)

Value

A character vector containing .fsf syntax for the EV portion of a first-level Feat analysis based on regressors.

Author(s)

Michael Hallquist

Examples

  regressors <- list(
    list(name="cue_onset", waveform="custom_3", timing_file="r1_cue_onset_3col.txt", convolution="double_gamma"),
    list(name="feedback",  waveform="custom_3", timing_file="r1_feedback_3col.txt", convolution="double_gamma"),
    list(name="RPE", waveform="custom_1", timing_file="r1_RPEs.1D", convolution="none")
  )

  ev_syntax <- fsl_generate_fsf_lvl1_ev_syntax(regressors)

UNCDEPENdLab/fmri.pipeline documentation built on April 3, 2025, 3:21 p.m.