generate_spm_mat: Uses an object from build_design_matrix to generate a...

In PennStateDEPENdLab/dependlab: Useful functions for the UNC Chapel Hill DEPENd Lab (Director: Michael Hallquist)

Uses an object from build_design_matrix to generate a corresponding SPM GLM design matrix.

Description

Uses an object from build_design_matrix to generate a corresponding SPM GLM design matrix.

Usage

generate_spm_mat(
  bdm,
  ts_files = NULL,
  output_dir = "spm_out",
  hpf = 100,
  hrf_derivs = "none",
  nifti_tmpdir = tempdir(),
  cleanup_tmp = FALSE,
  condition_contrasts = TRUE,
  unit_contrasts = TRUE,
  effects_of_interest_F = TRUE,
  spm_execute_setup = FALSE,
  spm_execute_glm = FALSE,
  spm_execute_contrasts = FALSE,
  concatenate_runs = FALSE,
  generate_qsub = TRUE,
  execute_qsub = FALSE,
  spm_path = "/gpfs/group/mnh5174/default/lab_resources/spm12"
)

Arguments

bdm	The object (of class 'bdm') generated by build_design_matrix. In particular, the function uses the $design and $run_niftis elements to extract relevant regressors and information about the NIfTI files to analyze.
ts_files	A character vector of nuisance text files – one per run – to be added as covariates in SPM's multi_reg field.
output_dir	The path where SPM scripts and outputs should go for this design matrix. The path can be relative or absolute, but will be converted to absolute internally using normalizePath().
hpf	The high-pass filter cutoff (in seconds) used to remove low frequencies prior to analysis. Default: 100
hrf_derivs	Whether to include derivatives of the regressors in the model to capture HRF variation. Options are: "none", "time" (temporal derivative), "time_dispersion" (temporal and dispersion derivatives). Default: "none"
nifti_tmpdir	Where to place uncompressed NIfTIs for analysis (SPM doesn't handle .nii.gz)
cleanup_tmp	Whether to remove uncompressed .nii files after completing this function
condition_contrasts	Whether to setup contrasts for each condition. In multi-run data, these contrasts will represent the condition average across all runs (e.g., [ .5, .5 ] for 2 runs). Default: TRUE
unit_contrasts	Whether to estimate a unit-height contrast for every regressor in the design. This essentially includes a diagonal matrix in the contrast specification. Default: FALSE
effects_of_interest_F	Whether to include a single F test contrast with all regressors of interest. Useful in adjusting VOIs for nuisance regressors. Default: TRUE
spm_execute_setup	Whether to run the GLM setup script in MATLAB, creating SPM.mat. Default: FALSE
spm_execute_glm	Whether to run the GLM after creating SPM.mat. This could take a while! Default: FALSE
spm_execute_contrasts	Whether to compute contrasts after GLM is complete. Depends on spm_execute_glm. Default: FALSE
concatenate_runs	Whether to convert multi-run data into a single concatenated session. This will execute spm_fmri_concatenate after the GLM setup is complete. This script computes run-specific whitening and high-pass filters while keeping a single concatenated time series. This is useful as a preamble to DCM, which often uses concatenated time series. Default: FALSE
generate_qsub	Whether to create a qsub PBS script for running MATLAB scripts for design matrix creation and estimation. Default: TRUE
execute_qsub	Whether to submit the PBS script create by generate_qsub to the cluster using the qsub command. Default: FALSE
spm_path	The path to an spm12 directory. This will be included in MATLAB scripts to ensure that spm is found.
include_block_contrasts	Whether to estimate contrasts for the run-specific intercepts in the design. Note that this qualifies condition_contrasts and unit_contrasts, but does nothing on its own.

Details

This function is intended to setup a first-level (subject) fMRI GLM analysis in SPM12. It accepts an object from build_design_matrix and uses the contents of this object to setup timing and HRF settings (including parametric modulation) for all regressors.

At this point, the function is not very flexible in terms of allowing custom tweaks to each field. It is mostly intended to setup the necessary SPM structures to support DCM, which depends on an SPM.mat file. I discovered the spm12r package recently, which has a lot of flexibility for setting up a first-level model. In the future, we may wish to adapt the code below to use this instead. https://cran.rstudio.com/web/packages/spm12r/vignettes/fmri_task_processing.html

Value

A list containing the MATLAB syntax/scripts for GLM setup, execution, and contrast estimation

Author(s)

Michael Hallquist

PennStateDEPENdLab/dependlab documentation built on April 10, 2024, 5:15 p.m.