fit_bayesglm: fit_bayesglm

In mandymejia/BayesGLMfMRI: Spatial Bayesian Methods for Task Functional MRI Studies

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
)

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.

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.

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.

mandymejia/BayesGLMfMRI documentation built on April 12, 2025, 3:41 p.m.