Performs classical Bayesian GLM for task fMRI activation with CIFTI-format data, evaluating multiple design matrices. Includes the pre-processing steps of nuisance regression. Supports single-session analysis only.
multiGLM(
BOLD,
design,
brainstructures = c("left", "right"),
TR = NULL,
resamp_res = 10000,
hpf = NULL,
nuisance = NULL,
design_canonical = NULL,
verbose = 1,
meanTol = 1e-06,
varTol = 1e-06
)An object of class "mGLM": a list with elements
data.frame summarizing the spatial features of each brain structure modeled.
data.frame with the name, related task, and HRF_order of each field.
fMRI timeseries data in CIFTI format ("*.dtseries.nii").
For single-session analysis this can be a file path to a CIFTI file or a
"xifti" object from the ciftiTools package. For multi-session
analysis this can be a vector of file paths or a list of "xifti"
objects.
If BOLD is a "xifti" object(s), the surfaces, if any, will be
used for the spatial model. However, if surfL and surfR are
provided, they will override any surfaces in BOLD.
A 3D numeric array that is locations by fields by designs.
Character vector indicating which brain structure(s)
of BOLD to analyze: "left" cortex; "right" cortex;
and/or "subcortical" structures. Or "all" to model all three.
Default: c("left","right") (cortex only).
Temporal resolution of the data, in seconds.
For cortex spatial model. The number of vertices to which
each cortical surface should be resampled, or NULL to not resample.
For computational feasibility, a value of 10000 (default) or lower is
recommended for Bayesian spatial modeling. If Bayes=FALSE,
resamp_res can be set to NULL for full-resolution classical
modeling.
Add DCT bases to nuisance to apply a temporal high-pass
filter to the data, for detrending? hpf is the filter frequency.
Use NULL to skip detrending. Detrending is strongly recommended for
fMRI data, to help reduce the autocorrelation in the residuals, so
NULL will induce a warning. Use "already" to disable the
warning while skipping highpass filtering.
Using at least two DCT bases is as sufficient for detrending as using linear
and quadratic drift terms in the nuisance matrix. So if DCT detrending is
being used here, there is no need to add linear and quadratic drift terms to
nuisance.
(Optional) A \(T \times N_{nuis}\) matrix of nuisance signals, where \(T\) is the number of timepoints and \(N\) is the number of nuisance signals, or a list of these for multi-session analysis. Nuisance signals are regressed from the fMRI data and design matrix prior to GLM computation. Nuisance signals can include motion regressors, HRF derivatives not being modeled as tasks, and other sources of noise.
Detrending/high-pass filtering is accomplished by adding DCT bases to the
nuisance matrix; see the parameters hpf and DCT.
Do not add spike regressors for scrubbing to the nuisance matrix.
Rather, provide these in scrub so that their corresponding timepoints
are also removed from the BOLD data after nuisance regression.
TO DO
1 (default) to print occasional updates during model
computation; 2 for occasional updates as well as running INLA in
verbose mode (if Bayes), or 0 for no printed updates.
Tolerance for mean and variance of each data location.
Locations which do not meet these thresholds are masked out of the analysis.
Default: 1e-6 for both.
This function uses a system wrapper for the 'wb_command' executable. The user must first download and install the Connectome Workbench, available from https://www.humanconnectome.org/software/get-connectome-workbench .