vignettes/ravel.Rmd
ravel.RmdnormalizeRaw: no normalizationnormalizeWS: WhiteStripe normalizationnormalizeHM: Histogram Matching normalizationnormalizeZScore: Whole-brain z-score normalizationnormalizeRAVEL: RAVEL normalizationRAVELData
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")
Y.raw <- normalizeRaw(input.files=input.files,
brain.mask=brain.mask,
returnMatrix=TRUE
)
Y.hm <- normalizeHM(input.files=input.files,
brain.mask=brain.mask,
returnMatrix=TRUE,
type="T1"
)
Y.ws <- normalizeWS(input.files=input.files,
brain.mask=brain.mask,
returnMatrix=TRUE,
WhiteStripe_Type="T1"
)
Y.zscore <- normalizeZScore(input.files=input.files,
brain.mask=brain.mask,
returnMatrix=TRUE
)We perform RAVEL intensity normalization using
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.
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.
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## (Intercept) age genderM
## 1 1 70 1
## 2 1 62 1
## 3 1 43 0
## 4 1 76 0
## attr(,"assign")
## [1] 0 1 2
## attr(,"contrasts")
## attr(,"contrasts")$gender
## [1] "contr.treatment"
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
)