Main functions

Example dataset from RAVELData

library(EveTemplate)
library(RAVEL)
library(RAVELData)

We first get the path of the NIfTI files for the 4 scans stored in the R package RAVELData. The scans were corrected for inhomogeneity and non-linearly registered to the Eve Template after skull stripping.

dir <- file.path(find.package("RAVELData"), "extdata")
input.files  <- list.files(dir, full.names=TRUE, pattern="processed.nii.gz")

RAVEL requires a set of control voxels to infer the unwanted variation. We use a CSF mask that was created using the intersection of all 4 subject-specific CSF masks, also stored in RAVELData:

control.mask <- list.files(dir, full.names=TRUE, pattern="mask_intersection.nii.gz")

Finally, we also need to provide a brain mask. Since the 4 scans were registered to the Eve Template, we use the Eve Template brain mask accessible through the R package EveTemplate:

brain.mask   <- EveTemplate::getEvePath("Brain_Mask")

No normalization

Y.raw <- normalizeRaw(input.files=input.files,
    brain.mask=brain.mask,
    returnMatrix=TRUE
)

Histogram matching normalization

Y.hm <- normalizeHM(input.files=input.files,
    brain.mask=brain.mask,
    returnMatrix=TRUE,
    type="T1"
)

WhiteStripe normalization

Y.ws <- normalizeWS(input.files=input.files,
    brain.mask=brain.mask,
    returnMatrix=TRUE,
    WhiteStripe_Type="T1"
)

Whole-brain z-score normalization

Y.zscore <- normalizeZScore(input.files=input.files,
    brain.mask=brain.mask,
    returnMatrix=TRUE
)

RAVEL normalization

We perform RAVEL intensity normalization using $k=1$ component to tesimate the unwanted variation. For the sake of time, we specify WhiteStripe=FALSE, but we recommend to always use the default WhiteStripe=TRUE as we have shown that the combination WhiteStripe + RAVEL is best at normalizing data.

Y.ravel <- normalizeRAVEL(input.files=input.files,
    control.mask=control.mask,
    brain.mask=brain.mask,
    k=1, 
    returnMatrix=TRUE,
    WhiteStripe=FALSE
)

If returnMatrix=FALSE, NIfTI objects containing the RAVEL-normalized values will be saved to disk instead.

Creation of a control voxels mask

The function maskIntersect will produce the intersection of a list of binary masks. For instance, to produce an intersection mask of all 4 CSF masks stored in RAVELData, we would do the following:

dir <- file.path(find.package("RAVELData"), "extdata")
masks <- list.files(dir, full.names=TRUE, pattern="*mask*.nii*")
mask  <- maskIntersect(masks, output.file="csf_mask_intersection.nii.gz")

An additional argument, prob, can control the percentage of participants in which the control voxel appears.

Controling for biological covariates in RAVEL

In removing the unwanted variation estimated using control voxels, it is possible to preserve biological variation by specifying biological covariates in the normalizeRAVEL function, similar to ComBat harmonization.

For instance, suppose we want to normalize intensities across participants using CSF, and also want to make sure that we don't remove variation in intensities associated with age. We first need to build a model matrix for the biological covariates (here age):

age <- c(70,62,43,76) #Simulated age
gender <- c("M", "M", "F", "F")
mod <- model.matrix(~age+gender)
mod

Note that while the model matrix has an intercept column, this will be automatically handled internally by the normalizeRAVEL function. To run RAVEL while adjusting for age and gender, we include mod as an argument as follows:

Y.ravel.mod <- normalizeRAVEL(input.files=input.files,
    control.mask=control.mask,
    brain.mask=brain.mask,
    k=1, 
    mod=mod,
    returnMatrix=TRUE,
    WhiteStripe=FALSE
)


Jfortin1/RAVEL documentation built on Sept. 14, 2023, 10:33 a.m.