Preprocess BOLD fMRI image data.

Preprocess fMRI data by performing compcor/motion correction, nuisance regression, band-pass filtering, and spatial smoothing.

preprocessfMRI(
  boldImage,
  maskImage = NULL,
  maskingMeanRatioThreshold = 0.75,
  initialNuisanceVariables,
  numberOfCompCorComponents = 6,
  doMotionCorrection = TRUE,
  useMotionCorrectedImage = FALSE,
  motionCorrectionAccuracyLevel = 1,
  meanBoldFixedImageForMotionCorrection = NULL,
  frequencyLowThreshold = NA,
  frequencyHighThreshold = NA,
  spatialSmoothingType = "none",
  spatialSmoothingParameters = 0,
  residualizeMatrix = TRUE,
  num_threads = 1,
  seed = NULL
)

Arguments

boldImage

4-D ANTs image fMRI data.
maskImage

3-D ANTs image defining the region of interest.
maskingMeanRatioThreshold

If mask image is not specified, a mask image is created using the specified threshold which is in terms of the mean of the average image ie 0.8 means threshold at 0.8 of the mean.
initialNuisanceVariables

Optional initial nuisance variables.
numberOfCompCorComponents

Numer of CompCor nuisance components.
doMotionCorrection

Boolean indicating whether motion correction should be performed and used in nuisance regression.
useMotionCorrectedImage

Boolean indicating whether or not the motion corrected image should be used in the rest of the pipeline. This is off by default to avoid additional interpolation.
motionCorrectionAccuracyLevel

Accuracy for the motion correcting registration: 0 = fast/debug parameters, 1 = intrasession parameters, or 2 = intersession/intersubject parameters.
meanBoldFixedImageForMotionCorrection

Optional target fixed image for motion correction.
frequencyLowThreshold

Lower threshold for bandpass filtering.
frequencyHighThreshold

Upper threshold for bandpass filtering.
spatialSmoothingType

Either none, gaussian (isotropic) or perona-malik (anisotropic) smoothing.
spatialSmoothingParameters

For gaussian smoothing, this is a single scalar designating the smoothing sigma (in mm). For perona-malik, a vector needs to be specified with the conductance parameter and the number of iterations, e.g. c(0.25, 5).
residualizeMatrix

boolean
num_threads

will execute Sys.setenv(ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS = num_threads) before running to attempt a more reproducible result. See https://github.com/ANTsX/ANTs/wiki/antsRegistration-reproducibility-issues for discussion. If NULL, will not set anything.
seed

will execute Sys.setenv(ANTS_RANDOM_SEED = seed) before running to attempt a more reproducible result. See https://github.com/ANTsX/ANTs/wiki/antsRegistration-reproducibility-issues for discussion. If NULL, will not set anything.

Value

List of:

  • cleanBOLDImage: Cleaned BOLD image.

  • maskImage: mask image.

  • DVARS: Framewise change in BOLD signal, as in Powers et al.

  • DVARSPostCleaning: DVARS after cleaning image.

  • FD: Framewise displacement.

  • globalSignal: Global signal.

  • nuisanceVariables: Nuisance variables used in denoising.

References

Power et al. 2012, "Spurious but systematic correlations in functional connectivity MRI networks arise from subject motion." NeuroImage 59, 2142-2154.

Author

Tustison NJ, Avants BB

Examples

set.seed(123)
n=8
nvox <- n*n*n*6
dims <- c(n,n,n,6)
boldImage <- makeImage(dims, rnorm(nvox) + 500) %>% iMath("PadImage", 2)
cleanfMRI <- preprocessfMRI(boldImage)