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

Matrix of Cholesky factorizations (upper triangular values) for all prior sessions (nN*nM x nChol)

Pivot/reordering applied to FC matrices prior to Cholesky factorization

Number of samples to draw

Indices of diagonal upper triangular elements

Indices of off-diagonal upper triangular elements

A nLxnL matrix indexing the upper triangular elements

(V \times Q matrix) mean maps for each network in the prior, where Q is the number of networks, V=nvox is the number of data locations.

(V \times Q matrix) between-subject variance maps for each network in prior

NULL for spatial independence model, otherwise a list of objects of class "BrainMap_mesh" containing the triangular mesh (see make_mesh) for each brain structure.

(V \times Q matrix) dimension-reduced fMRI data

(list) initial guess at parameter values: A (QxQ mixing matrix), nu0_sq (residual variance from first level) and (for spatial model only) kappa (SPDE smoothness parameter for each network map)

(Qx1) diagonal elements of matrix proportional to residual variance.

For dimension reduction of the spatial Bayesian brain map model, which assumes that all networks have the same smoothness parameter, \kappa

Maximum number of EM iterations. Default: 100.

Parallelize the computation? Default: FALSE. Can be the number of cores to use or TRUE, which will use the number available minus two. Not yet implemented for spatial Bayesian brain map.

Smallest proportion change between iterations. Default: 0.001.

Reduce the temporal dimension of the data using PCA? Default: TRUE for the spatial EM algorithm, and FALSE for the independent EM algorithm.

If TRUE, display progress of algorithm. Default: FALSE.

Center BOLD across columns (each image)? This is equivalent to performing global signal regression. Default: FALSE.

Inverse Wishart degrees of freedom parameter

Matrix dimension for IW distribution

Empirical mean of covariance matrices at element (i,j)

Empirical mean of covariance matrices at the ith diagonal element

Empirical mean of covariance matrices at the jth diagonal element

Inverse Wishart degrees of freedom parameter

Matrix dimension for IW distribution

Empirical mean of covariance matrices at element (i,j)

Value of kappa for which to compute log-likelihood

Mesh projection matrix

Matrix used in computation of SPDE precision

Matrix used in computation of SPDE precision

Matrix used in computation of SPDE precision

Sparse matrix containing estimated values of RHS of trace in part 2 of log-likelihood. In common smoothness model, represents the sum over q=1,...,Q.

Vector needed for part 3 of log-likelihood

Vector needed for part 3 of log-likelihood

For the unit variance case, \tau^2 = C1/\kappa^2, where C1 = 1/(4\pi) when \alpha=2, \nu=1, d=2

Equal to the number of networks for the common smoothness model, or NULL for the network-specific smoothness model

Vector of current parameter values

The args

The temporal resolution of the data, i.e. the time between volumes, in seconds. TR is required for detrending with hpf.

Vector of initial parameter values

Passed to UpdateTheta_BrainMap function

Passed to UpdateTheta_BrainMap function

Passed to UpdateTheta_BrainMap function

Passed to UpdateTheta_BrainMap function

Passed to UpdateTheta_BrainMap function

Passed to UpdateTheta_BrainMap function

Passed to UpdateTheta_BrainMap function

Passed to UpdateTheta_BrainMap function

For non-spatial model: updating nu0sq is recommended if dimension reduction was not performed, and is not recommended if it was.

Passed to UpdateTheta_BrainMap function

(V \times Q matrix) mean maps for each network in prior

(V \times Q matrix) between-subject variance maps for each network in prior

NULL for spatial independence model, otherwise a list of objects of class "BrainMap_mesh" containing the triangular mesh (see make_mesh) for each brain structure.

(V \times Q matrix) dimension-reduced fMRI data

(list) current parameter estimates

(Qx1) diagonal elements of residual covariance after dimension reduction

For dimension reduction

Vectorized prior means

Sparse diagonal matrix of prior standard deviations

The inverse of D times s0_vec

If TRUE, display progress of algorithm. Default: FALSE.

If TRUE. return the posterior mean and precision of the latent fields instead of the parameter estimates. Default: FALSE.

Which parameters to update. Either "all", "A" or "kappa".

For non-spatial model: updating nu0sq is recommended if dimension reduction was not performed, and is not recommended if it was.

(V \times Q matrix) mean maps for each network in the prior, where Q is the number of networks, and V=nvox is the number of data locations.

(V \times Q matrix) between-subject variance maps for each network in the prior.

(list) Parameters of functional connectivity prior.

Variational Bayes (VB) method for FC Bayesian brain mapping: "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.

For VB1, the number of samples to generate from u ~ Gamma, where A is Gaussian conditional on u. Default: 10000.

Level of posterior credible interval to construct for each FC element. Default: 0.95.

Should the FC samples (QxQxK) be returned, where K is the number of posterior samples generated? May be a large object. For VB1, K is equal to nsamp_u. For VB2, K is equal to the number of samples from p(G) contained in prior_FC.

Alpha and beta parameters of IG prior on \tau^2 (error variance). Default: 0.001 for both.

(V \times T matrix) preprocessed fMRI data.

Initial guesses at latent variables: A (TxQ mixing matrix), S (QxV matrix of spatial networks), and variance matrix S0_var.

Maximum number of VB iterations. Default: 100.

Minimum number of VB iterations. Default: 3.

Smallest proportion change in parameter estimates between iterations. Default: 0.001.

Parallelize the computation? Default: FALSE. 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 applicable 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. Default: FALSE.

The two terms. Each is a length-one character vector.

List of matrices

a k x k 'matrix'

how many times to repeat mat

The data FORMAT

The current parameter estimates

The prior

The C matrix

(V \times T matrix) preprocessed fMRI data

Print LL components?

NULL for spatial independence model, otherwise a list of objects of class "BrainMap_mesh" containing the triangular mesh (see make_mesh) for each brain structure.

Current estimates of SPDE parameter kappa for each latent field

Constant, equal to 1/(4*pi) for a 2-dimensional field with alpha=2

If TRUE. remove extra (non-data) vertices from the mesh for greater computational efficiency

Vectorized, dimension-reduced fMRI data, grouped by locations. A vector of length QV.

Sparse diagonal matrix of prior standard deviations

The inverse of D times s0_vec

Estimate of inverse spatial correlation matrix (sparse)

List of current parameter estimates

Permutation matrix for regrouping by locations (instead of by networks.)

Diagonals of residual covariance of the first level model. A vector of length Q.

A numeric matrix, with each column being a centered timeseries. For fMRI data, X should be T timepoints by V brain locations.

Number of latent dimensions to estimate. If NULL (default), estimated using PESEL (Sobczyka et al. 2020).

Maximal number of principal components for automatic dimensionality selection with PESEL. Default: 100.

Subject-level fMRI data in one of the following formats: a CIFTI file path, a "xifti" object, a NIFTI file path, a "nifti" object, or V \times T numeric matrices, where V is the number of data locations and T is the number of timepoints.

If BOLD2 is provided it must be in the same format as BOLD; BOLD will be the test data and BOLD2 will be the retest data.

If BOLD2 is not provided, BOLD will be split in half; the first half will be the test data and the second half will be the retest data.

Expected format of BOLD and BOLD2. Should be one of the following: a "CIFTI" file path, a "xifti" object, a "NIFTI" file path, a "nifti" object, or a "data" matrix.

The group ICA map or parcellation as a (vectorized) numeric matrix (V \times Q). If it's an ICA map, its columns will be centered.

If the template is a parcellation, provide the parcellation table here. Default: NULL.

Required if and only if the entries of BOLD are NIFTI file paths or "nifti" objects. This is a brain map formatted as a binary array of the same size as the fMRI data, with TRUE corresponding to in-mask voxels.

Keep the resulting A matrices, or only return the S matrices (default)?

"local" (default), "global", or "none". Local scaling will divide each data location's time series by its estimated standard deviation. Global scaling will divide the entire data matrix by the mean image standard deviation (mean(sqrt(rowVars(BOLD)))).

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: 2).

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) Nuisance matrix to regress from the BOLD data. If BOLD2 is provided, should be a length-2 list with the first entry corresponding to BOLD and the second to BOLD2. If NULL, do not remove any nuisance signals.

Nuisance regression is performed in a simultaneous regression with any spike regressors from scrub and DCT bases from hpf.

Note that the nuisance matrices should be provided with timepoints matching the original BOLD and BOLD2 irregardless of drop_first. Nuisance matrices will be truncated automatically if drop_first>0.

(Optional) 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 BOLD2 is provided, should be a length-two list with the first entry corresponding to BOLD and the second to BOLD2.

Scrubbing is performed within a nuisance regression by adding a spike regressor to the nuisance design matrix for each volume to scrub.

Note that indices are counted beginning with the first index in the BOLD session irregardless of drop_first. The indices will be adjusted automatically if drop_first>0.

(Optional) Number of volumes to drop from the start of each BOLD session. Default: 0.

The frequency at which to apply a highpass filter to the data during pre-processing, in Hertz. Default: 0 Hz (disabled). If the data has not already been highpass filtered, a recommended filter value is .01 Hz. The highpass filter serves to detrend the data, since low-frequency variance is associated with noise. Highpass filtering is accomplished by nuisance regression of discrete cosine transform (DCT) bases.

Note the TR argument is required for highpass filtering. If TR is not provided, hpf will be ignored.

The temporal resolution of the data, i.e. the time between volumes, in seconds. TR is required for detrending with hpf.

Center BOLD across columns (each image)? This is equivalent to performing global signal regression. Default: FALSE.

Obtain dual regression estimates after denoising? 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 (default) 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 minimum number of timepoints in each fMRI scan and Q is the number of networks in template. If NULL (default), Q2_max will be set to T * .50 - Q, rounded.

Only applies if the entries of BOLD are CIFTI file paths. 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: c("all").

Only applies if the entries of BOLD are CIFTI file paths. Resample the data upon reading it in? Default: NULL (no resampling).

Tolerance for variance of each data location. For each scan, locations which do not meet this threshold are masked out of the analysis. Default: 1e-6. Variance is calculated on the original data, before any normalization. Set to 0 to avoid removing locations due to low variance.

Tolerance for number of locations masked out due to low variance or missing values. If more than this many locations are masked out, this subject is skipped without calculating dual regression. maskTol can be specified either as a proportion of the number of locations (between zero and one), or as a number of locations (integers greater than one). Default: .1, i.e. up to 10\

If BOLD2 is provided, masks are calculated for each scan and then the intersection of the masks is used.

Display progress updates? Default: TRUE.

Fitted (spatial) Bayesian brain map from BrainMap.

Set a threshold value for engagement? A threshold value can be specified directly with u, or a z-score-like threshold in terms of standard deviations (the SD of values in the mean prior) can be specified with z. Only one type of threshold can be used. Default: NULL (do not use a threshold). Either argument can also be a vector to test multiple thresholds at once, as long as type is not "!=" (to ensure the engagement regions are successive subsets).

Significance level for hypothesis testing. Default: 0.01.

Type of region: ">" (default), "abs >", "<", or "!=". "abs >" tests for magnitude by taking the absolute value and then testing if they are greater than... .

If the input is a "bMap.[format]" model object, the type of multiple comparisons correction to use for p-values, or NULL for no correction. See help(p.adjust). Default: "BH" (Benjamini & Hochberg, i.e. the false discovery rate). Note that multiple comparisons will account for data locations, but not networks.

If TRUE, display progress of algorithm. Default: FALSE.

Indices of networks for which to identify engagements. If NULL (default), use all networks.

If TRUE identify significant deviations from the prior mean, rather than significant areas of engagement. Default: FALSE.

INLA mesh

data

index of the data locations in the mesh

If TRUE, a formula based on the trace is used, otherwise the inverse correlation is used

Empirical between-subject variance of covariance matrices (QxQ)

Empirical mean of covariance matrices (QxQ)

Empirical between-subject variance of covariance matrices (QxQ)

Empirical mean of covariance matrices (QxQ)

Vector of subject-level fMRI data in one of the following formats: CIFTI file paths, "xifti" objects, GIFTI file paths, "gifti" 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 BOLD2 is provided it must be in the same format as BOLD; BOLD will be the test data and BOLD2 will be the retest data. BOLD2 should be the same length as BOLD and have the same subjects in the same order. If BOLD2 is not provided, BOLD will be split in half; the first half will be the test data and the second half will be the retest data.

Group-level template: either a group ICA (GICA), or a parcellation.

A GICA should be provided as a format compatible with BOLD, or a (vectorized) numeric matrix (V \times Q). Its columns will be centered.

A parcellation must be in CIFTI format for use with CIFTI BOLD data (other formats to be implemented in the future). The parcellation should have the same locations as the BOLD and one column, with integer values indicating the parcel to which each location belongs to. Each parcel is modeled as a brain map; instead of the first step of dual regression, the medial timecourse of each parcel is used.

Required if BOLD are NIFTI file paths or "nifti" objects, and optional for other formats. For NIFTI data, this is a logical array of the same spatial dimensions as the fMRI data, with TRUE corresponding to in-mask voxels. For other data, this is a logical vector with the same length as the number of locations in template, with TRUE corresponding to in-mask locations.

Numeric indices of the networks in template to include in the prior. If NULL, use all of the original networks (default).

If inds is provided, the networks not included will be removed after calculating dual regression, not before. This is because removing the networks prior to dual regression would leave unmodelled signals in the data, which could bias the priors.

"local" (default), "global", or "none". Local scaling will divide each data location's time series by its estimated standard deviation. Global scaling will divide the entire data matrix by the mean image standard deviation (mean(sqrt(rowVars(BOLD)))).

Only applies if scale=="local" and BOLD represents surface data (CIFTI or GIFTI). 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: 2).

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) Nuisance matrices to regress from the BOLD data. Should be a list of matrices, with time along the rows and nuisance signals along the columns, where each entry corresponds to a BOLD session; or, if BOLD2 is provided, should be a length-2 list of such lists with the first sublist corresponding to BOLD and the second sublist corresponding to BOLD2. If NULL, do not remove any nuisance signals.

Nuisance regression is performed in a simultaneous regression with any spike regressors from scrub and DCT bases from hpf.

Note that the nuisance matrices should be provided with timepoints matching the original BOLD and BOLD2 irregardless of drop_first. Nuisance matrices will be truncated automatically if drop_first>0.

(Optional) Numeric vectors of integers giving the indices of volumes to scrub from the BOLD data. (List the volumes to remove, not the ones to keep.) Should be a list of such vectors, where each entry corresponds to a BOLD session; or, if BOLD2 is provided, should be a length-2 list of such lists with the first sublist corresponding to BOLD and the second sublist corresponding to BOLD2. If NULL (default), do not scrub.

Scrubbing is performed within a nuisance regression by adding a spike regressor to the nuisance design matrix for each volume to scrub.

Note that indices are counted beginning with the first index in the BOLD session irregardless of drop_first. The indices will be adjusted automatically if drop_first>0.

(Optional) Number of volumes to drop from the start of each BOLD session. Default: 0.

The frequency at which to apply a highpass filter to the data during pre-processing, in Hertz. Default: 0 Hz (disabled). If the data has not already been highpass filtered, a recommended filter value is .01 Hz. The highpass filter serves to detrend the data, since low-frequency variance is associated with noise. Highpass filtering is accomplished by nuisance regression of discrete cosine transform (DCT) bases.

Note the TR argument is required for highpass filtering. If TR is not provided, hpf will be ignored.

The temporal resolution of the data, i.e. the time between volumes, in seconds. TR is required for detrending with hpf.

Center BOLD across columns (each image)? This is equivalent to performing global signal regression. Default: FALSE.

Obtain dual regression estimates after denoising? 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 (default) 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 minimum number of timepoints in each fMRI scan and Q is the number of networks in the template. If NULL (default), Q2_max will be set to T * .50 - Q, rounded.

Subjects by variables numeric matrix of covariates to take into account for model estimation. Column names should give the name of each variable. 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: c("all").

Only applies if the entries of BOLD are CIFTI file paths. Resample the data upon reading it in? Default: NULL (no resampling).

Keep the DR estimates of S? If FALSE (default), do not save the DR estimates and only return the priors. If TRUE, the DR estimates of S are returned too. If a single file path, save the DR estimates as an RDS file at that location rather than returning them.

Keep the DR estimates of the FC cor(A)? If FALSE (default), do not save the DR estimates and only return the priors. If TRUE, the DR estimates of cor(A) and its Cholesky factor are returned too. If a single file path, save the DR estimates as an RDS file at that location rather than returning them.

Include the functional connectivity prior? Default: TRUE.

Number of pivots to use in Cholesky-based FC prior estimation. Set to zero to skip Cholesky-based FC prior estimation. Default: 100.

Number of FC matrix samples to generate across all pivots. This should be a multiple of FC_nPivots.

Tolerance for variance of each data location. For each scan, locations which do not meet this threshold are masked out of the analysis. Default: 1e-6. Variance is calculated on the original data, before any normalization.

For computing the dual regression results for each subject: tolerance for number of locations masked out due to low variance or missing values. If more than this many locations are masked out, a subject is skipped without calculating dual regression. maskTol can be specified either as a proportion of the number of locations (between zero and one), or as a number of locations (integers greater than one). Default: .1, i.e. up to 10 percent of locations can be masked out.

If BOLD2 is provided, masks are calculated for both scans and then the intersection of the masks is used, for each subject.

For computing the variance decomposition across all subjects: tolerance for number of subjects masked out due to low variance or missing values at a given location. If more than this many subjects are masked out, the location's value will be NA in the priors. missingTol can be specified either as a proportion of the number of locations (between zero and one), or as a number of locations (integers greater than one). Default: .1, i.e. up to 10 percent of subjects can be masked out at a given location.

Parallelize the DR computations over subjects? Default: FALSE. Can be the number of cores to use or TRUE, which will use the number on the PC minus two. If the input data is in CIFTI format, the wb_path must also be provided.

Display progress updates? Default: TRUE.

The FC estimates from estimate_prior.

Factor by which to adjust estimate of nu. Values < 1 will inflate the prior variance to avoid an over-informative prior on FC.

the test/retest dual regression estimates, as an array with dimensions M \times N \times (L \times V), where M is the number of visits (2), N is the number of subjects, L is the number of brain networks, and V is the number of data locations.

(L and V are collapsed because they are treated equivalently in the context of calculating the variance decomposition and priors).

A length-two integer vector giving the dimensions L and V to reshape the result. Default: NULL (do not reshape the result).

the test and retest dual regression estimates (N \times L \times V)

The result of estimate_prior

Use NULL (default) to just return the prior objects directly. Otherwise, use a character vector of length 3 or 4 of file path(s) to save the output to: the mean prior, the variance prior, the variance decomposition, and the FC prior if present, in that order. If one file name is provided, it will be appended with "_mean.[file_ext]" for the prior mean map, "_var.[file_ext]" for the prior variance map, "_varDecomp.rds" for the variance decomposition, and "_FC.rds" where [file_ext] will be "dscalar.nii" for CIFTI input, "nii" for NIFTI input, and "rds" for data input.

"non-negative" (default) or "unbiased"

See engagements.

If multiple u or z were provided, should just one name be returned? Default: FALSE

vector of p AR parameters

number of time points in timeseries

the file format

A numeric matrix

The frequency at which to apply a highpass filter to the data during pre-processing, in Hertz. Default: 0 Hz (disabled). If the data has not already been highpass filtered, a recommended filter value is .01 Hz. The highpass filter serves to detrend the data, since low-frequency variance is associated with noise. Highpass filtering is accomplished by nuisance regression of discrete cosine transform (DCT) bases.

Note the TR argument is required for highpass filtering. If TR is not provided, hpf will be ignored.

Value of hyperparameters

Data vector

SPDE G matrix

SPDE C matrix

Indices of data locations in the mesh

Vector of length two containing values of log kappa and log residual variance at which to compute log likelihood

Estimate of delta (subject effect or deviation)

Diagonal values of D matrix (prior standard deviations)

Object of class "BrainMap_mesh" containing the triangular mesh (see make_mesh)

For the unit variance case, \tau^2 = C1/\kappa^2, where C1 = 1/(4\pi) when \alpha=2, \nu=1, d=2

Equal to the number of networks for the common smoothness model, or NULL for the network-specific smoothness model

The number of networks

The number of spatial locations (V)

A V \times T numeric matrix. Each row is a location.

Tolerance for mean and variance of each data location. Locations which do not meet these thresholds are masked out of the analysis. Defaults: -Inf for meanTol (ignore), and 1e-6 for varTol.

Print messages counting how many locations are removed?

Object of class "surf". See make_surf and is.surf.

Subset of vertices to include in analysis, e.g. non-medial wall locations.

Subset of vertices to retain in mesh, e.g. non-medial wall locations. Must be a superset of inds_data.

Brain mask (matrix of 0 and 1 or TRUE and FALSE).

fMRI numeric data matrix (V \times T)

Center BOLD data across rows (each data location's time series) or columns (each time point's image)? Default: TRUE for row centering, and FALSE for column centering.

"local" (default), "global", or "none". Local scaling will divide each data location's time series by its estimated standard deviation. Global scaling will divide the entire data matrix by the mean image standard deviation (mean(sqrt(rowVars(BOLD)))).

Only applies if scale=="local" and BOLD represents CIFTI-format data. To smooth the standard deviation estimates used for local scaling, provide a "xifti" object with data locations in alignment with BOLD, as well as the smoothing FWHM (default: 2). If no "xifti" object is provided (default), do not smooth.

For local scaling with smoothing, the data must be unmasked to be mapped back to the surface. So if the data are masked, provide the mask here.

The frequency at which to apply a highpass filter to the data during pre-processing, in Hertz. Default: 0 Hz (disabled). If the data has not already been highpass filtered, a recommended filter value is .01 Hz. The highpass filter serves to detrend the data, since low-frequency variance is associated with noise. Highpass filtering is accomplished by nuisance regression of discrete cosine transform (DCT) bases.

Note the TR argument is required for highpass filtering. If TR is not provided, hpf will be ignored.

The temporal resolution of the data, i.e. the time between volumes, in seconds. TR is required for detrending with hpf.

A square matrix to be orthonormalized.

The result of BrainMap with CIFTI data

"mean" (default) or "se".

Show the BrianMap estimates on the brain? Default: TRUE.

Show the FC estimates? Default: TRUE. Note that only the mean estimate is available for FC, not the SE.

Additional arguments to view_xifti

The result of BrainMap with NIFTI data

Additional arguments

The result of BrainMap with NIFTI data

"mean" (default), "se"

Anatomical plane and which slice indices to show. Default: 9 axial slices.

Additional arguments

The engagements from engagements.cifti

"engaged" (default), "pvals", "pvals_adj", "tstats", or "vars".

Additional arguments to view_xifti

The prior from estimate_prior.cifti

Which prior statistic to plot: the "mean" (default), "sd" for the square root of the variance template, or "var" for the variance template.

Show the prior maps on the brain? Default: TRUE.

Empirical ("emp") (default), Inverse-Wishart ("IW"), Cholesky ("Chol"), or "none".

"non-negative" (default) or "unbiased", for the variance estimate of the maps. Note that FC variance estimates are always non-negative.

Additional arguments to view_xifti

The prior from estimate_prior.gifti

"mean", "sd", or "both" (default). By default the square root of the variance prior is shown; another option is stat="var" to instead display the variance prior directly.

"non-negative" (default) or "unbiased"

Additional arguments to view_xifti

The prior from estimate_prior.matrix

Additional arguments

The prior from estimate_prior.nifti

"mean" (default), "sd", or "var". ("sd" will show the square root of the variance prior.)

Anatomical plane and which slice indices to show. Default: 9 axial slices.

"non-negative" (default) or "unbiased"

Additional arguments to oro.nifti::image

Estimated A matrix (T x Q)

Order of the AR model used to prewhiten the data at each location. If !aic (default), the order will be exactly ar_order. If aic, the order will be between zero and ar_order, as determined by the AIC.

The "prior.cifti" object.

"cortex_left", "cortex_right", and/or "subcortical".

The "prior.cifti" object.

The new resampling resolution.

Give occasional updates? Default: FALSE.

the row-centered V by T data

We need an initial estimate of the brain networks, so that we can avoid removing them during removal of the estimated noise ICs. Provide either DR if dual regression has already been calculated, or prior_mean (in this context, equivalent to a template result) if it hasn't. Exactly one must be provided.

The number of nuisance ICs. If NULL (default) will estimate using PESEL.

If Q2 is NULL, PESEL's estimate will be less than or equal to Q2_max. If Q2_max is NULL (default), do not limit PESEL's estimate.

Check row means, and raise an error if they are nonzero? Default: TRUE.

If TRUE, display progress updates.

Return (estimated) Q2 too? Default: FALSE.

"local" (default), "global", or "none". Local scaling will divide each data location's time series by its estimated standard deviation. Global scaling will divide the entire data matrix by the mean image standard deviation (mean(sqrt(rowVars(BOLD)))).

A numerical matrix

if inverse=TRUE, compute inverse of square root

The prior

"CIFTI", "GIFTI", "NIFTI", or "DATA"

The input mask

The params

The data structure

Object of class "bMap.cifti".

further arguments passed to or from other methods.

The result of BrainMap with CIFTI data

Object of class "bMap.matrix".

further arguments passed to or from other methods.

The prior from estimate_prior.cifti

Object of class "bMap.nifti".

further arguments passed to or from other methods.

The prior from estimate_prior.cifti

Object of class "bMap_eng.cifti".

further arguments passed to or from other methods.

The engagements from engagements.cifti

Object of class "bMap_eng.matrix".

further arguments passed to or from other methods.

The engagements from engagements

Object of class "bMap_eng.nifti".

further arguments passed to or from other methods.

The engagements from engagements

Object of class "prior.cifti".

further arguments passed to or from other methods.

The prior from estimate_prior.cifti

Object of class "prior.gifti".

further arguments passed to or from other methods.

The prior from estimate_prior.gifti

Object of class "prior.matrix".

further arguments passed to or from other methods.

The prior from estimate_prior.cifti

Object of class "prior.nifti".

further arguments passed to or from other methods.

The prior from estimate_prior.nifti

Most recent estimates of posterior moments for these variables.

(T \times V matrix) preprocessed fMRI data.

Number of timepoints, number of , number of locations

Samples from Gamma for multivariate t prior on A

IW parameters for FC prior

Parallelize the computation? Default: FALSE. Can be the number of cores to use or TRUE, which will use the number available minus two.

If TRUE, return cov_A. Default: FALSE

Most recent estimates of posterior moments for these variables.

(T \times V matrix) preprocessed fMRI data.

Number of timepoints, number of networks, number of locations

IW parameters for FC prior

If TRUE, return cov_A. Default: FALSE

If FALSE, at intermediate steps (final = FALSE) will attempt to approximate V_k as described in the appendix of Mejia et al. 2024. Setting exact = TRUE may be helpful when using spatial ESS correction, which can lead to a lower rate of usable prior samples for the approximation.

Parallelize the computation? Default: FALSE. Can be the number of cores to use or TRUE, which will use the number available minus two.

If TRUE, display progress of algorithm. Default: FALSE.

Most recent posterior estimates

Some pre-computed quantities.

(T \times V matrix) preprocessed fMRI data.

Number of networks, number of data locations, and time series length

If TRUE, return cov_S. Default: FALSE

(T \times V matrix) preprocessed fMRI data.

A precomputed quantity, sum(BOLD^2)

Current posterior estimates

Alpha and beta parameters of IG prior on \tau^2 (error variance).

Number of timepoints in data and the number of data locations.

Tolerance for variance of each data location. For each scan, locations which do not meet this threshold are masked out of the analysis. Default: 1e-6. Variance is calculated on the original data, before any normalization. Set to 0 to avoid removing locations due to low variance.

Inverse Wishart degrees of freedom parameter

Matrix dimension for IW distribution

Empirical between-subject variance of covariance matrices at element (i,j)

Empirical mean of covariance matrices at element (i,j)

Empirical mean of covariance matrices at the ith diagonal element

Empirical mean of covariance matrices at the jth diagonal element

Inverse Wishart degrees of freedom parameter

Matrix dimension for IW distribution

Empirical between-subject variances of CORRELATION matrix (upper triangle)

Empirical mean of CORRELATION matrix (upper triangle)

Penalty to assign if theoretical variance is smaller than empirical variance