Wrapper to dual_reg used by estimate_prior. The format of BOLD
(and BOLD2) must be provided, and template must be vectorized if applicable.
dual_reg2(
BOLD,
BOLD2 = NULL,
format = c("CIFTI", "xifti", "GIFTI", "gifti", "NIFTI", "nifti", "RDS", "data"),
template,
template_parc_table = NULL,
mask = NULL,
keepA = FALSE,
scale = c("local", "global", "none"),
scale_sm_surfL = NULL,
scale_sm_surfR = NULL,
scale_sm_FWHM = 2,
nuisance = NULL,
scrub = NULL,
drop_first = 0,
hpf = 0,
TR = NULL,
GSR = FALSE,
Q2 = 0,
Q2_max = NULL,
NA_limit = 0.1,
brainstructures = "all",
resamp_res = NULL,
varTol = 1e-06,
maskTol = 0.1,
verbose = TRUE
)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.
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.