CompCor {fMRItools}R Documentation

Anatomical CompCor

Description

The aCompCor algorithm for denoising fMRI data using noise ROIs data

Usage

CompCor(
  X,
  ROI_data = "infer",
  ROI_noise = NULL,
  noise_nPC = 5,
  noise_erosion = NULL,
  center = TRUE,
  scale = TRUE,
  nuisance = NULL
)

Arguments

X

Wide numeric data matrix (T observations by V variables, T << V). For example, if X represents an fMRI run, T should be the number of timepoints and V should be the number of brainordinate vertices/voxels.

Or, a 4D array or NIFTI or file path to a NIFTI (I by J by K by T observations), in which case ROI_data must be provided. (The vectorized data will be T timepoints by V_{in-mask} voxels)

Or, a ciftiTools "xifti" object or a file path to a CIFTI (The vectorized data will be T timepoints by V_{left+right+sub} grayordinates).

ROI_data

Indicates the data ROI. Allowed arguments depend on X:

If X is a matrix, this must be a length V logical vector, where the data ROI is indicated by TRUE values. If "infer" (default), all columns of X will be included in the data ROI (rep(TRUE, V)).

If X is an array or NIFTI, this must be either a vector of values to expect for out-of-mask voxels in X, or a (file path to a) 3D NIFTI. In the latter case, each of the volume dimensions should match the first three dimensions of X. Voxels in the data ROI should be indicated by TRUE and all other voxels by FALSE. If "infer" (default), will be set to c(0, NA, NaN) (include all voxels which are not constant 0, NA, or NaN).

If X is a "xifti" this must be the brainstructures argument to ciftiTools::read_cifti. If "infer" (default), brainstructures will be set to "all" (use both left and right cortex vertices, and subcortical voxels).

If NULL, the data ROI will be empty. This is useful for obtaining just the noise ROI, if the data and noise are located in separate files.

ROI_noise

Indicates the noise ROIs for aCompCor. Should be a list where each entry corresponds to a distinct noise ROI. The names of the list should be the ROI names, e.g. "white_matter" and "csf". The expected formats of the list entries depends on X:

For all types of X, ROI_noise entries can be a matrix of noise ROI data. The matrix should have T rows, with each column being a data location's timeseries.

If X is a matrix, entries can also indicate a noise ROI within X. These entries must be a length V logical vector with TRUE values indicating locations in X within that noise ROI. Since the ROIs must not overlap, the masks must be mutually exclusive with each other, and with ROI_data.

If X is an array or NIFTI, entries can also indicate a noise ROI within X. These entries must be a logical array or (file path to) a 3D NIFTI with the same spatial dimensions as X, and with TRUE values indicating voxels inside the noise ROI. Since the ROIs must not overlap, the masks must be mutually exclusive with each other, and with ROI_data.

(If X is a "xifti", entries must be data matrices, since no grayordinate locations in X are appropriate noise ROIs).

noise_nPC

The number of principal components to compute for each noise ROI. Alternatively, values between 0 and 1, in which case they will represent the minimum proportion of variance explained by the PCs used for each noise ROI. The smallest number of PCs will be used to achieve this proportion of variance explained.

Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: 5 (compute the top 5 PCs for each noise ROI).

noise_erosion

The number of voxel layers to erode the noise ROIs by. Should be a list or numeric vector with the same length as ROI_noise. It will be matched to each ROI based on the name of each entry, or if the names are missing, the order of entries. If it is an unnamed vector, its elements will be recycled. Default: NULL, which will use a value of 0 (do not erode the noise ROIs). Note that noise erosion can only be performed if the noise ROIs are volumetric.

center, scale

Center the columns of the noise ROI data by their medians, and scale by their MADs? Default: TRUE for both. Note that this argument affects the noise ROI data and not the data that is being cleaned with aCompCor. Centering and scaling of the data being cleaned can be done after this function call.

nuisance

Nuisance signals to regress from each data column in addition to the noise ROI PCs. Should be a T by N numeric matrix where N represents the number of nuisance signals. To not perform any nuisance regression set this argument to NULL, 0, or FALSE. Default: NULL.

Details

First, the principal components (PCs) of each noise region of interest (ROI) are calculated. For each ROI, voxels are centered and scaled (can be disabled with the arguments center and scale), and then the PCs are calculated via the singular value decomposition.

Next, aCompCor is performed to remove the shared variation between the noise ROI PCs and each location in the data. This is accomplished by a nuisance regression using a design matrix with the noise ROI PCs, any additional regressors specified by nuisance, and an intercept term. (To detrend the data and perform aCompCor in the same regression, nuisance can be set to DCT bases obtained with the function dct_bases.)

Value

A list with entries "data", "noise", and potentially "ROI_data".

The entry "data" will be a V x T matrix where each row corresponds to a data location (if it was originally an array, the locations will be voxels in spatial order). Each row will be a time series with each noise PC regressed from it. This entry will be NULL if there was no data.

The entry "noise" is a list of noise PC scores, their corresponding variance, and their ROI mask, for each noise ROI.

If the data ROI is not all TRUE, the entry "ROI_data" will have the ROI mask for the data.

References

See Also

CompCor_HCP

[Package fMRItools version 0.4.7 Index]