R: Anatomical CompCor for HCP NIFTI and CIFTI data

CompCor_HCP {fMRItools}

R Documentation

Anatomical CompCor for HCP NIFTI and CIFTI data

Description

Wrapper to CompCor for HCP-format data. Can be used to clean the surface-based CIFTI data with aCompCor using the noise PCs and ROIs calculated from the NIFTI fMRI data and NIFTI mask. Can also be used to just obtain the noise PCs and ROIs without performing aCompCor, if the CIFTI data is not provided.

Usage

CompCor_HCP(
  nii,
  nii_labels,
  ROI_noise = c("wm_cort", "csf"),
  noise_nPC = 5,
  noise_erosion = NULL,
  idx = NULL,
  cii = NULL,
  brainstructures = c("left", "right"),
  center = TRUE,
  scale = TRUE,
  DCT = 0,
  nuisance_too = NULL,
  verbose = FALSE
)

Arguments

`nii`	`I` by `J` by `K` by `T` NIFTI object or array (or file path to the NIFTI) which contains whole-brain data, including the noise ROIs. In the HCP, the corresponding file is e.g. "../Results/rfMRI_REST1_LR/rfMRI_REST1_LR.nii.gz"
`nii_labels`	`I` by `J` by `K` NIFTI object or array (or file path to the NIFTI) which contains the corresponding labels to each voxel in `nii`. Values should be according to this table: https://surfer.nmr.mgh.harvard.edu/fswiki/FsTutorial/AnatomicalROI/FreeSurferColorLUT . In the HCP, the corresponding file is "ROIs/Atlas_wmparc.2.nii.gz".
`ROI_noise`	A list of numeric vectors. Each entry should represent labels in `nii_labels` belonging to a single noise ROI, named by that entry's name. Or, this can be a character vector of at least one of the following: `"wm_cort"` (cortical white matter), `"wm_cblm"` (cerebellar white matter), `"csf"` (cerebrospinal fluid). In the latter case, these labels will be used: `"wm_cort"` `c(3000:4035, 5001, 5002)` `"wm_cblm"` `c(7, 46)` `"csf"` `c(4, 5, 14, 15, 24, 31, 43, 44, 63, 250, 251, 252, 253, 254, 255))` These default ROIs are based on this forum post: https://www.mail-archive.com/hcp-users@humanconnectome.org/msg00931.html Default: `c("wm_cort", "csf")`
`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).
`idx`	A numeric vector indicating the timepoints to use, or `NULL` (default) to use all idx. (Indexing begins with 1, so the first timepoint has index 1 and the last has the same index as the length of the scan.)
`cii`	`"xifti"` (or file path to the CIFTI) from which the noise ROI components will be regressed. In the HCP, the corresponding file is e.g. "../Results/rfMRI_REST1_LR/rfMRI_REST1_LR_Atlas_MSMAll.dtseries.nii". If not provided, only the noise components will be returned (no data will be cleaned).
`brainstructures`	Choose among "left", "right", and "subcortical". Default: `c("left", "right")` (cortical data only)
`center`, `scale`	Center the columns of the data by median, and scale the columns of the data by MAD? Default: `TRUE` for both. Affects both `X` and the noise data. `center` also applies to `nuisance_too` so if it is `FALSE`, `nuisance_too` must already be centered.
`DCT`	Add DCT bases to the nuisance regression? Use an integer to indicate the number of cosine bases. Use `0` (default) to forgo detrending. The data must be centered, either before input or with `center`.
`nuisance_too`	A matrix of nuisance signals to add to the nuisance regression. Should have `T` rows. `NULL` to not add additional nuisance regressors (default).
`verbose`	Should occasional updates be printed? Default: `FALSE`.

Value

The noise components, and if cii is provided, the cleaned surface-based data as a "xifti" object.

References