Fit Bayesian brain mapping model using variational Bayes (VB) or expectation-maximization (EM).
BrainMap(
BOLD,
prior,
tvar_method = c("non-negative", "unbiased"),
scale = c("prior", "global", "local", "none"),
scale_sm_surfL = NULL,
scale_sm_surfR = NULL,
scale_sm_FWHM = "prior",
nuisance = NULL,
scrub = NULL,
drop_first = 0,
hpf = "prior",
TR = NULL,
GSR = "prior",
Q2 = "prior",
Q2_max = "prior",
covariates = NULL,
brainstructures = "prior",
mask = NULL,
varTol = "prior",
spatial_model = NULL,
resamp_res = NULL,
rm_mwall = TRUE,
reduce_dim = FALSE,
method_FC = c("VB1", "VB2", "none"),
maxiter = 100,
miniter = 3,
epsilon = 0.001,
kappa_init = 0.2,
usePar = TRUE,
PW = FALSE,
seed = 1234,
verbose = TRUE
)A (spatial) prior ICA object, which is a list containing:
subjNet_mean, the \(V \times L\) estimated independent components
S; subjNet_se, the standard errors of S; the
mask of locations without prior values due to too many low
variance or missing values; the nuisance design matrix or matrices if
applicable; and the function params such as the type of scaling and
detrending performed.
If BOLD represented CIFTI or NIFTI data, subjNet_mean and
subjNet_se will be formatted as "xifti" or "nifti"
objects, respectively.
Vector of subject-level fMRI data in one of the following
formats: CIFTI file paths, "xifti" objects, NIFTI file paths,
"nifti" objects, or \(V \times T\) numeric matrices, where \(V\)
is the number of data locations and \(T\) is the number of timepoints.
If multiple BOLD data are provided, they will be independently centered, scaled, detrended (if applicable), and denoised (if applicable). Then they will be concatenated together followed by computing the initial dual regression estimate.
Prior estimates in a format compatible with BOLD,
from estimate_prior.
Which calculation of the prior variance to use:
"non-negative" (default) or "unbiased". The unbiased prior
variance is based on the assumed mixed effects/ANOVA model, whereas the
non-negative prior variance adds to it to account for greater potential
between-subjects variation. (The prior mean is the same for either choice
of tvar_method.)
"global", "local", or "none".
Global scaling will divide the entire data matrix by the mean image standard
deviation (mean(sqrt(rowVars(BOLD)))). Local scaling will divide each
data location's time series by its estimated standard deviation. Default:
"prior", to use the same option used for estimation of the
prior.
Only applies if
scale=="local" and BOLD represents CIFTI-format data. To
smooth the standard deviation estimates used for local scaling, provide the
surface geometries along which to smooth as GIFTI geometry files or
"surf" objects, as well as the smoothing FWHM (default:
"prior" to use the same option used for estimation of the
prior).
If scale_sm_FWHM==0, no smoothing of the local standard deviation
estimates will be performed.
If scale_sm_FWHM>0 but scale_sm_surfL and
scale_sm_surfR are not provided, the default inflated surfaces from
the HCP will be used.
To create a "surf" object from data, see
make_surf. The surfaces must be in the same
resolution as the BOLD data.
(Optional) Signals to regress from the data, given as a
numeric matrix with the same number of rows as there are volumes in the
BOLD data. If multiple BOLD sessions are provided,
this argument can be a list to use different nuisance regressors for
different sessions. Nuisance regression is performed as a first step, before
centering, scaling, and denoising. An intercept column will automatically be
added to nuisance. If NULL, no extra nuisance signals will be
regressed from the data, but a nuisance regression will still be used if
warranted by scrub or hpf.
(Optional) A numeric vector of integers giving the indices
of volumes to scrub from the BOLD data. (List the volumes to remove, not the
ones to keep.) If multiple BOLD sessions are provided, this
argument can be a list to remove different volumes for different sessions.
Scrubbing is performed within nuisance regression by adding a spike
regressor to the nuisance design matrix for each volume to scrub. If
NULL (default), do not scrub.
(Optional) Number of volumes to drop from the start of each
BOLD session. Default: 0.
These arguments control detrending. TR is the temporal
resolution of the data, i.e. the time between volumes, in seconds;
hpf is the frequency of the high-pass filter, in Hertz. Detrending
is performed via nuisance regression of DCT bases. Default:
"prior" to use the values from the prior. Be sure to set the
correct TR if it's different for the new data compared to the data
used in estimate_prior.
Note that if multiple BOLD sessions are provided, their
TR and hpf must be the same; both arguments accept only one
value.
Center BOLD across columns (each image)? This
is equivalent to performing global signal regression. Default:
"prior", to use the same option used for estimation of the
prior.
Denoise the BOLD data? Denoising is based on modeling and removing nuisance ICs. It may result in a cleaner estimate for smaller datasets, but it may be unnecessary (and time-consuming) for larger datasets.
Set Q2 to control denoising: use a positive integer to specify the
number of nuisance ICs, NULL to have the number of nuisance ICs
estimated by PESEL, or zero to skip denoising.
If is.null(Q2), use Q2_max to specify the maximum number of
nuisance ICs that should be estimated by PESEL. Q2_max must be less
than \(T * .75 - Q\) where \(T\) is the number of timepoints in BOLD
and \(Q\) is the number of networks in the prior. If NULL, Q2_max
will be set to \(T * .50 - Q\), rounded.
The defaults for both arguments is "prior", to use the same option
used for estimation of the prior.
Numeric vector of covariates to take into account for model
estimation. Names should give the name of each variable. The covariates must
match those of the prior. Default: NULL (no covariates).
NOTE: Not implemented yet.
Only applies if the entries of BOLD are CIFTI
file paths. This is a character vector indicating which brain structure(s)
to obtain: "left" (left cortical surface), "right" (right
cortical surface) and/or "subcortical" (subcortical and cerebellar
gray matter). Can also be "all" (obtain all three brain structures).
Default: "prior" to use the same brainstructures present in the
prior).
Required only if the entries of BOLD are NIFTI
file paths or "nifti" objects. This is a binary array of the same
spatial dimensions as the fMRI data, with TRUE corresponding to
in-mask voxels.
Tolerance for variance of each data location. For each scan,
locations which do not meet this threshold are masked out of the analysis.
Default: "prior" to use the same brainstructures present in the
prior). Variance is calculated on the original data, before
any normalization. Set to 0 to avoid removing locations due to
low variance.
Should spatial modeling be performed? If NULL, assume
spatial independence. Otherwise, provide meshes specifying the spatial priors assumed on
each independent component. Each should represent a brain structure, between which
spatial independence can be assumed.
If BOLD represents CIFTI-format data, spatial_model should give the left and
right cortex surface geometries (whichever one(s) are being used) as "surf"
objects or GIFTI surface geometry file paths. Spatial modeling is not yet available for
the subcortex. This argument can also be TRUE, in which case spatial modeling
will be performed with the surfaces included in the first entry of BOLD if it is a
"xifti" object, or if those are not present available, the default inflated
surfaces from ciftiTools.
If BOLD represents NIFTI-format data, spatial modeling is not yet available.
If BOLD is a numeric matrix, spatial_model should be a list of meshes
(see make_mesh).
Only applies if BOLD represents CIFTI-format data.
The target resolution for resampling (number of cortical surface vertices
per hemisphere). For spatial modelling, a value less than 10000 is
recommended for computational feasibility. If NULL (default), do not
perform resampling.
Only applies if BOLD represents CIFTI-format data.
Should medial wall (missing data) locations be removed from the mesh?
If TRUE, faster computation but less accurate estimates at the
boundary of wall.
Reduce the temporal dimension of the data using PCA?
Default: TRUE. Skipping dimension reduction will slow the model
estimation, but may result in more accurate results. Ignored for FC prior
ICA
Variational Bayes (VB) method for FC prior ICA model:
"VB1" (default) uses a conjugate Inverse-Wishart prior for the cor(A);
"VB2" draws samples from p(cor(A)) to emulate the population distribution
using a combination of Cholesky, SVD, and random pivoting.
"none" Uses standard prior ICA without FC prior
Maximum number of EM or VB iterations. Default: 100.
Minimum number of EM or VB iterations. Default: 3.
Smallest proportion change between iterations. Default:
.001.
Starting value for kappa. Default: 0.2.
Parallelize the computation? Default: TRUE. Can be the
number of cores to use or TRUE, which will use the number available minus two.
Prewhiten to account for residual autocorrelation? Default: FALSE.
Only affects FC prior ICA models.
(Only applicable for FC calculation and if PW) Seed to use
for computing temporal effective sample size (ESS) to correct sums over
\(t\). If NULL, do not change the seed. Default: 1234.
If TRUE, display progress of algorithm
if (FALSE) {
tm <- estimate_prior(cii1_fnames, cii2_fnames, gICA_fname, usePar=FALSE)
BrainMap(newcii_fname, tm, spatial_model=TRUE, resamp_res=2000, usePar=FALSE)
}
Run the code above in your browser using DataLab