Estimate template for Template ICA based on fMRI data
estimate_template(
BOLD,
BOLD2 = NULL,
GICA,
mask = NULL,
inds = NULL,
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,
brainstructures = "all",
resamp_res = NULL,
keep_S = FALSE,
keep_FC = FALSE,
FC = TRUE,
FC_nPivots = 100,
FC_nSamp = 50000,
varTol = 1e-06,
maskTol = 0.1,
missingTol = 0.1,
usePar = FALSE,
wb_path = NULL,
verbose = TRUE
)estimate_template.cifti(
BOLD,
BOLD2 = NULL,
GICA,
inds = NULL,
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,
brainstructures = "all",
resamp_res = resamp_res,
keep_S = FALSE,
keep_FC = FALSE,
FC = FALSE,
varTol = 1e-06,
maskTol = 0.1,
missingTol = 0.1,
usePar = FALSE,
wb_path = NULL,
verbose = TRUE
)
estimate_template.gifti(
BOLD,
BOLD2 = NULL,
GICA,
inds = NULL,
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,
brainstructures = "all",
keep_S = FALSE,
keep_FC = FALSE,
FC = FALSE,
varTol = 1e-06,
maskTol = 0.1,
missingTol = 0.1,
usePar = FALSE,
wb_path = NULL,
verbose = TRUE
)
estimate_template.nifti(
BOLD,
BOLD2 = NULL,
GICA,
inds = NULL,
scale = c("local", "global", "none"),
TR = NULL,
hpf = 0.01,
GSR = FALSE,
Q2 = 0,
Q2_max = NULL,
mask = NULL,
keep_S = FALSE,
keep_FC = FALSE,
FC = FALSE,
varTol = 1e-06,
maskTol = 0.1,
missingTol = 0.1,
usePar = FALSE,
wb_path = NULL,
verbose = TRUE
)
A list: the template and var_decomp with entries in
matrix format; the mask of locations without template values due to
too many low variance or missing values; the function params such as
the type of scaling and detrending performed; the dat_struct which can be
used to convert template and var_decomp to "xifti" or
"nifti" objects if the BOLD format was CIFTI or NIFTI data;
and DR results if isTRUE(keep_S) and/or isTRUE(keep_FC).
Use summary to print a description of the template results, and
for CIFTI-format data use plot to plot the template mean and variance
estimates. Use export_template to save the templates to
individual RDS, CIFTI, or NIFTI files (depending on the BOLD format).
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 ICA maps in a format compatible with BOLD. Can also
be a (vectorized) numeric matrix (\(V \times Q\)) no matter the format of
BOLD. Its columns will be centered.
New: can also be a parcellation in CIFTI format (other formats to be implemented in the future). The parcellation should have the same locations 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 brain map
formatted as 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
GICA, with TRUE corresponding to in-mask locations.
Numeric indices of the group ICs to include in the template. If
NULL, use all group ICs (default).
If inds is provided, the ICs not included will be removed after
calculating dual regression, not before. This is because removing the ICs
prior to dual regression would leave unmodelled signals in the data, which
could bias the templates.
"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.
The temporal resolution of the data, i.e. the time between volumes,
in seconds. TR is required for detrending with 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.
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 group ICs. If NULL
(default), Q2_max will be set to \(T * .50 - Q\), rounded.
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 templates. 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 templates. 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 template? Default: TRUE.
Number of pivots to use in Cholesky-based FC template estimation. Set to zero to skip Cholesky-based FC template 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 templates. 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.
All fMRI data (entries in BOLD and BOLD2, and GICA) must
be in the same spatial resolution.
nT <- 21
nV <- 140
nQ <- 6
mU <- matrix(rnorm(nV*nQ), nrow=nV)
mS <- mU %*% diag(seq(nQ, 1)) %*% matrix(rnorm(nQ*nT), nrow=nQ)
BOLD <- list(B1=mS, B2=mS, B3=mS)
BOLD <- lapply(BOLD, function(x){x + rnorm(nV*nT, sd=.05)})
GICA <- mU
estimate_template(BOLD=BOLD, GICA=mU, FC_nSamp=2000)
if (FALSE) {
estimate_template(
run1_cifti_fnames, run2_cifti_fnames,
gICA_cifti_fname, brainstructures="all",
scale="global", TR=0.71, Q2=NULL, varTol=10
)
}
Run the code above in your browser using DataLab