BayesGLM {BayesfMRI} | R Documentation |
BayesGLM for CIFTI
Description
Performs spatial Bayesian GLM for task fMRI activation with CIFTI-format data. The cortex is modeled as a surface mesh, and subcortical structures are modeled as distinct volumetric regions. Includes the pre-processing steps of nuisance regression, prewhitening, scaling, and variance normalization. Supports both single- and multi-session analysis. Can also compute just the classical (spatially-independent)
Usage
BayesGLM(
BOLD,
brainstructures = c("left", "right"),
subROI = c("Amygdala-L", "Amygdala-R", "Caudate-L", "Caudate-R", "Hippocampus-L",
"Hippocampus-R", "Thalamus-L", "Thalamus-R"),
design,
nuisance = NULL,
scrub = NULL,
hpf = NULL,
TR = NULL,
surfL = NULL,
surfR = NULL,
resamp_res = 10000,
nbhd_order = 1,
buffer = c(1, 1, 3, 4, 4),
session_names = NULL,
scale_BOLD = c("mean", "sd", "none"),
Bayes = TRUE,
hyperpriors = c("informative", "default"),
ar_order = 6,
ar_smooth = 5,
aic = FALSE,
n_threads = 4,
return_INLA = c("trimmed", "full", "minimal"),
verbose = 1,
meanTol = 1e-06,
varTol = 1e-06
)
Arguments
BOLD |
fMRI timeseries data in CIFTI format ("*.dtseries.nii").
For single-session analysis this can be a file path to a CIFTI file or a
If |
brainstructures |
Character vector indicating which brain structure(s)
of |
subROI |
Which subcortical ROIs should be analyzed? Can be |
design |
A numeric matrix or |
nuisance |
(Optional) A Detrending/high-pass filtering is accomplished by adding DCT bases to the
nuisance matrix; see the parameters Do not add spike regressors for scrubbing to the |
scrub |
(Optional) A The spike regressors will be included in the nuisance
regression, and afterwards the timepoints indicated in |
hpf |
Add DCT bases to 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
|
TR |
Temporal resolution of the data, in seconds. |
surfL , surfR |
For cortex spatial model. Left and right cortex surface
geometry in GIFTI format ("*.surf.gii"). These can be a file path to
a GIFTI file or a Surfaces can alternatively be provided through the |
resamp_res |
For cortex spatial model. The number of vertices to which
each cortical surface should be resampled, or For computational feasibility, a value of |
nbhd_order |
For volumetric model. What order neighborhood around data
locations to keep? |
buffer |
For volumetric model. The number of extra voxel layers around
the bounding box. Set to |
session_names |
The names of the task-fMRI |
scale_BOLD |
Controls scaling the BOLD response at each location.
|
Bayes |
Perform spatial Bayesian modeling? Default: |
hyperpriors |
Should informative or default non-informative hyperpriors be assumed on SPDE hyperparameters? |
ar_order |
(For prewhitening) The order of the autoregressive (AR) model
to use for prewhitening. If For multi-session modeling, note that a single AR model is used; its coefficients will be the average estimate from each session. |
ar_smooth |
(For prewhitening) The FWHM parameter for spatially
smoothing the coefficient estimates for the AR model to use for
prewhitening. Recall that
|
aic |
(For prewhitening) Use the Akaike information criterion (AIC) to
select AR model orders between |
n_threads |
The maximum number of threads to use for parallel
computations: prewhitening parameter estimation, and the inla-program model
estimation. Default: |
return_INLA |
Return the INLA model object? (It can be large.) Use
|
verbose |
|
meanTol , varTol |
Tolerance for mean and variance of each data location.
Locations which do not meet these thresholds are masked out of the analysis.
Default: |
Details
To use BayesGLM
, the design matrix must first be constructed
with make_design
.
Value
An object of class "BayesGLM"
: a list with elements
- betas_Bayesian
The field coefficients for the Bayesian model.
- betas_classical
The field coefficients for the classical model.
- GLMs_Bayesian
The entire list of GLM results, except for parameters estimated for the classical model.
- GLMs_classical
Parameters estimated for the classical model from the GLM.
- brainstructures
data.frame
summarizing the spatial features of each brain structure modeled.- sessions
data.frame
with thename
andnTime
of each BOLD session.- fields
data.frame
with thename
, relatedtask
, andHRF_order
of each field.
Connectome Workbench Requirement
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 .
INLA Requirement
This function requires the INLA
package, which is not a CRAN package.
See https://www.r-inla.org/download-install for easy installation instructions.
INLA Latent Fields Limit
INLA computation times increase greatly when the number of columns in the
design matrix exceeds five: when there are more than five tasks, or more
than three tasks each with a temporal derivative modeled as a field. In
cases like the latter, we recommend modeling the temporal derivatives as
nuisance signals using the option dHRF_as="nuisance"
, rather than
modeling the temporal derivatives as fields.