templateICA: Template ICA

In templateICAr: Estimate Brain Networks and Connectivity with ICA and Empirical Priors

Template ICA

Description

Perform template independent component analysis (ICA) using expectation-maximization (EM).

Usage

templateICA(
  BOLD,
  template,
  tvar_method = c("non-negative", "unbiased"),
  scale = c("global", "local", "none"),
  scale_sm_surfL = NULL,
  scale_sm_surfR = NULL,
  scale_sm_FWHM = 2,
  detrend_DCT = 0,
  center_Bcols = FALSE,
  normA = FALSE,
  Q2 = NULL,
  Q2_max = NULL,
  brainstructures = c("left", "right"),
  mask = NULL,
  time_inds = NULL,
  varTol = 1e-06,
  spatial_model = NULL,
  resamp_res = NULL,
  rm_mwall = TRUE,
  reduce_dim = TRUE,
  maxiter = 100,
  epsilon = 0.01,
  kappa_init = 0.2,
  usePar = FALSE,
  verbose = TRUE
)

Arguments

BOLD	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, and detrended (if applicable), and then they will be concatenated together followed by denoising (if applicable) and computing the initial dual regression estimate.
template	Template estimates in a format compatible with BOLD, from estimate_template.
tvar_method	Which calculation of the template variance to use: "non-negative" (default) or "unbiased". The unbiased template variance is based on the assumed mixed effects/ANOVA model, whereas the non-negative template variance adds to it to account for greater potential between-subjects variation. (The template mean is the same for either choice of tvar_method.)
scale	"global" (default), "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.
scale_sm_surfL, scale_sm_surfR, scale_sm_FWHM	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.
detrend_DCT	Detrend the data? This is an integer number of DCT bases to use for detrending. If 0 (default), do not detrend.
center_Bcols	Center BOLD across columns (each image)? This is equivalent to performing global signal regression. Default: FALSE.
normA	Scale each IC timeseries (column of A) in the dual regression estimates? Default: FALSE (not recommended). Note that the product A \times S remains the same with either option.
Q2, Q2_max	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 (default), 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 group ICs. If NULL (default), Q2_max will be set to T * .50 - Q, rounded.
brainstructures	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("left","right") (cortical surface only).
mask	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 spatial dimensions as the fMRI data, with TRUE corresponding to in-mask voxels.
time_inds	Subset of fMRI BOLD volumes to include in analysis. If NULL (default), use all volumes. Subsetting is performed before any centering, scaling, detrending, and denoising.
varTol	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.
spatial_model	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).
resamp_res	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.
rm_mwall	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_dim	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.
maxiter	Maximum number of EM iterations. Default: 100.
epsilon	Smallest proportion change between iterations. Default: .01.
kappa_init	Starting value for kappa. Default: 0.2.
usePar	Parallelize the computation over data locations? Default: FALSE. Can be the number of cores to use or TRUE, which will use the number on the PC minus two.
verbose	If TRUE, display progress of algorithm

Value

A (spatial) template ICA object, which is a list containing: subjICmean, the V \times L estimated independent components S; subjICse, the standard errors of S; the mask of locations without template values due to too many low variance or missing values; and the function params such as the type of scaling and detrending performed.

If BOLD represented CIFTI or NIFTI data, subjICmean and subjICse will be formatted as "xifti" or "nifti" objects, respectively.

Examples

## Not run: 
 tm <- estimate_template(cii1_fnames, cii2_fnames, gICA_fname)
 templateICA(newcii_fname, tm, spatial_model=TRUE, resamp_res=2000)

## End(Not run)

templateICAr documentation built on Feb. 16, 2023, 8:14 p.m.