dual_reg2: Dual Regression wrapper

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

Dual Regression wrapper

Description

Wrapper to dual_reg used by estimate_template. The format of BOLD (and BOLD2) must be provided, and GICA must be vectorized if applicable.

Usage

dual_reg2(
  BOLD,
  BOLD2 = NULL,
  format = c("CIFTI", "xifti", "GIFTI", "gifti", "NIFTI", "nifti", "RDS", "data"),
  GICA,
  GICA_parc_table = NULL,
  mask = NULL,
  keepA = FALSE,
  scale = c("local", "global", "none"),
  scale_sm_surfL = NULL,
  scale_sm_surfR = NULL,
  scale_sm_FWHM = 2,
  TR = NULL,
  hpf = 0.01,
  GSR = FALSE,
  Q2 = 0,
  Q2_max = NULL,
  NA_limit = 0.1,
  brainstructures = "all",
  resamp_res = NULL,
  varTol = 1e-06,
  maskTol = 0.1,
  verbose = TRUE
)

Arguments

BOLD, BOLD2	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.
format	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.
GICA	Group ICA maps as a (vectorized) numeric matrix (V \times Q). Its columns will be centered.
GICA_parc_table	Is the GICA actually a parcellation? If so, provide the parcellation table here. Default: NULL.
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 size as the fMRI data, with TRUE corresponding to in-mask voxels.
keepA	Keep the resulting A matrices, or only return the S matrices (default)?
scale	"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)))).
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.
TR	The temporal resolution of the data, i.e. the time between volumes, in seconds. TR is required for detrending with hpf.
hpf	The frequency at which to apply a highpass filter to the data during pre-processing, in Hertz. Default: 0.01 Hertz. Set to 0 to disable the highpass filter. 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.
GSR	Center BOLD across columns (each image)? This is equivalent to performing global signal regression. Default: FALSE.
Q2, Q2_max	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 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. 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").
resamp_res	Only applies if the entries of BOLD are CIFTI file paths. Resample the data upon reading it in? Default: NULL (no resampling).
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.
maskTol	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.
verbose	Display progress updates? Default: TRUE.

Value

The dual regression S matrices, or both the S and A matrices if keepA, or NULL if dual regression was skipped due to too many masked data locations.

templateICAr documentation built on April 3, 2025, 7:41 p.m.