BayesGLM {BayesfMRI}

BayesGLM

Description

Performs spatial Bayesian GLM for fMRI task activation

Usage

BayesGLM(
  data,
  vertices = NULL,
  faces = NULL,
  mesh = NULL,
  mask = NULL,
  task_names = NULL,
  session_names = NULL,
  combine_sessions = TRUE,
  scale_BOLD = c("auto", "mean", "sd", "none"),
  scale_design = TRUE,
  Bayes = TRUE,
  ar_order = 6,
  ar_smooth = 5,
  aic = FALSE,
  num.threads = 4,
  return_INLA = c("trimmed", "full", "minimal"),
  verbose = 1,
  meanTol = 1e-06,
  varTol = 1e-06
)

Arguments

data

A list of sessions in the "BfMRI.sess" object format. Each session is a list with elements "BOLD", "design", and optionally "nuisance". Each element should be a numeric matrix with T rows. The name of each element in data is the name of that session. See ?is.BfMRI.sess for details.

Note that the argument session_names can be used instead of providing the session names as the names of the elements in data.

vertices, faces

If Bayes, the geometry data can be provided with either both the vertices and faces arguments, or with the mesh argument.

vertices is a V \times 3 matrix, where each row contains the Euclidean coordinates at which a given vertex in the mesh is located. V is the number of vertices in the mesh.

faces is a F \times 3 matrix, where each row contains the vertex indices for a given triangular face in the mesh. F is the number of faces in the mesh.

mesh

If Bayes, the geometry data can be provided with either both the vertices and faces arguments, or with the mesh argument.

mesh is an "inla.mesh" object. This can be created for surface data using make_mesh.

mask

(Optional) A length V logical vector indicating the vertices to include.

task_names

(Optional) Names of tasks represented in design matrix.

session_names

(Optional, and only relevant for multi-session modeling) Names of each session. Default: NULL. In BayesGLM this argument will overwrite the names of the list entries in data, if both exist.

combine_sessions

If multiple sessions are provided, should their data be combined and analyzed as a single session?

If TRUE (default), the multiple sessions will be concatenated along time after scaling and nuisance regression, but before prewhitening. If FALSE, each session will be analyzed separately, except that a single estimate of the AR model coefficients for prewhitening is used, estimated across all sessions.

scale_BOLD

Option for scaling the BOLD response.

"auto" (default) will use "mean" scaling except if demeaned data is detected (if any mean is less than one), in which case "sd" scaling will be used instead.

"mean" scaling will scale the data to percent local signal change.

"sd" scaling will scale the data by local standard deviation.

"none" will only center the data, not scale it.

scale_design

Scale the design matrix by dividing each column by its maximum and then subtracting the mean? Default: TRUE. If FALSE, the design matrix is centered but not scaled.

Bayes

If TRUE (default), will fit a spatial Bayesian GLM in addition to the classical GLM. (The classical GLM is always returned.)

ar_order

(numeric) Controls prewhitening. If greater than zero, this should be a number indicating the order of the autoregressive model to use for prewhitening. If zero, do not prewhiten. Default: 6. For multi-session models, note that a single AR model is used; the parameters are estimated by averaging the estimates from each session.

ar_smooth

(numeric) FWHM parameter for smoothing the AR model coefficient estimates for prewhitening. Remember that \sigma = \frac{FWHM}{2*sqrt(2*log(2)}. Set to 0 or NULL to not do any smoothing. Default: 5.

aic

Use the AIC to select AR model order between 0 and ar_order? Default: FALSE.

num.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) to return only the more relevant results, which is enough for both id_activations and BayesGLM2, "minimal" to return just enough for BayesGLM2 but not id_activations, or "full" to return the full output of inla.

verbose

Should updates be printed? Use 1 (default) for occasional updates, 2 for occasional updates as well as running INLA in verbose mode (if applicable), or 0 for no updates.

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: 1e-6 for both.

Value

A "BayesGLM" object: a list with elements

INLA_model_obj

The full result of the call to INLA::inla.

task_estimates

The task coefficients for the Bayesian model.

result_classical

Results from the classical model: task estimates, task standard error estimates, residuals, degrees of freedom, and the mask.

mesh

The model mesh including only the locations analyzed, i.e. within mask, without missing values, and meeting meanTol and varTol.

mesh_orig

The original mesh provided.

mask

A mask of mesh_orig indicating the locations inside mesh.

design

The design matrix, after centering and scaling, but before any nuisance regression or prewhitening.

task_names

The names of the tasks.

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.