fit_bayesglm: fit_bayesglm

Description

Performs spatial Bayesian GLM for task fMRI activation

Usage

fit_bayesglm(
  BOLD,
  design,
  nuisance = NULL,
  scrub = NULL,
  spatial,
  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
)

Value

A "BayesGLM" object: a list with elements

INLA_model_obj: The full result of the call to INLA::inla.
field_estimates: The estimated coefficients for the Bayesian model.
result_classical: Results from the classical model: field estimates, field standard error estimates, residuals, degrees of freedom, and the mask.
mesh: The model mesh.
mask: A mask of mesh indicating the locations inside mesh.
design: The design matrix, after centering and scaling, but before any nuisance regression or prewhitening.
field_names: The names of the fields.
session_names: The names of the sessions.
hyperpar_posteriors: Hyperparameter posterior densities.
theta_estimates: Theta estimates from the Bayesian model.
posterior_Sig_inv: For joint group modeling.
mu_theta: For joint group modeling.
Q_theta: For joint group modeling.
y: For joint group modeling: The BOLD data after any centering, scaling, nuisance regression, or prewhitening.
X: For joint group modeling: The design matrix after any centering, scaling, nuisance regression, or prewhitening.
prewhiten_info: Vectors of values across locations: phi (AR coefficients averaged across sessions), sigma_sq (residual variance averaged across sessions), and AIC (the maximum across sessions).
call: match.call() for this function call.

Arguments

BOLD, design, nuisance

Session-length list of numeric matrices/arrays, each with volumes along the first dimension.

scrub

Session-length list of spike regressors: numeric matrices, with volumes along the first dimension, valued at 1 for scrubbed volumes and 0 otherwise.

Scrubbing is performed by incorporating spike regressors in the nuisance matrix during nuisance regression (in a simultaneous framework), and then removing the scrubbed timepoints from the resulting BOLD and design.

spatial

Gives the spatial information:

surf: A list of two: vertices \(V \times 3\) numeric matrix of vertex locations in XYZ coordinate space, and faces, \(F \times 3\) matrix of positive integers defining the triangular faces.

mask

Mask of locations with valid data.

For voxel data, a list of six:

label: 3D array of labeled locations to include in the model.
trans_mat: Projection matrix to convert voxel indices to XYZ position. Can be NULL.
trans_units: XYZ units. Can be NULL.
nbhd_order: See documentation for BayesGLM.
buffer: See documentation for BayesGLM.

scale_BOLD

Controls scaling the BOLD response at each location.

"mean":: Scale the data to percent local signal change.

"sd":

Scale the data by local standard deviation.

"none":

Center the data but do not scale it.

Bayes

Perform spatial Bayesian modeling? Default: TRUE. If FALSE, only perform classical (massive univariate) modeling. (The classical GLM result is always returned, whether Bayes is TRUE or FALSE.)

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 0, do not prewhiten. Default: 6.

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 \(\sigma = \frac{FWHM}{2*sqrt(2*log(2)}\). Set to 0 to not smooth the estimates. Default: 5.

aic

(For prewhitening) Use the Akaike information criterion (AIC) to select AR model orders between 0 and ar_order? Default: FALSE.

n_threads

The maximum number of threads to use for parallel computations: prewhitening parameter estimation, and the inla-program model estimation. Default: 4. Note that parallel prewhitening requires the parallel package.

return_INLA

Return the INLA model object? (It can be large.) Use "trimmed" (default) returns the results sufficient for activations and BayesGLM2; "minimal" returns enough for BayesGLM2 but not activations; "full" returns the full inla output.

verbose

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.

meanTol, varTol

Tolerance for mean, variance and SNR of each data location. Locations which do not meet these thresholds are masked out of the analysis. Default: 1e-6 for mean and variance, 50 for SNR.

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.