Multi-run normalization, filtering and nuisance estimation for fMRI.

This function leverages structural image processing based on ANTs cortical thickness to implement standard functional image processing recommendations. The function will crop out the first k time frames, do motion correction and produce a variety of nuisance regressors. It will also do spatial and temporal filtering as well as interpolation between time frames that exceed a given framewise displacement. Finally, we return maps to the common coordinate system. Output may be trimmed in the future but currently provides access at different stages: merging versus filtering and normalized, fused BOLD images in both subject and template space.

fMRINormalization(
  img,
  steadyT = 20,
  fdthresh = Inf,
  repeatMotionEst = 2,
  freqLimits = c(0.01, 0.1),
  nCompCor = 0,
  polydegree = NA,
  structuralImage = NULL,
  structuralSeg = NULL,
  structuralNodes = NULL,
  templateMap = NULL,
  templateImage = NULL,
  smoothingSigmas = NA,
  extraRuns = list(),
  verbose = FALSE
)

Arguments

img

input time series antsImage.

steadyT

number of seconds for steady state (used to remove initial volumes)

fdthresh

threshold for framewise displacement. determines what time frames should be interpolated. Set typically between 0.1 and 0.5 or Inf.

repeatMotionEst

number of times to repeat motion estimation. We recommend the value 2, in general. The first run improves the template estimate such that the 2nd run gives a more accurate correction.

freqLimits

pair defining bandwidth of interest from low to high.

nCompCor

number of compcor components to use in CSF plus WM mask.

polydegree

eg 4 for polynomial nuisance variables.

structuralImage

the structural antsImage of the brain.

structuralSeg

a 3 or greater class tissue segmentation of the structural image.

structuralNodes

regions of interest for network analysis, in the structural image space.

templateMap

antsRegistration output mapping template space (as moving) to struturalImage (fixed).

templateImage

template reference space to which we map the BOLD image.

smoothingSigmas

4-vector defining amount of smoothing in FWHM units.

extraRuns

a list containing additional BOLD images (runs) to be merged with the first image.

verbose

enables visualization as well as commentary.

Value

outputs a list containing:

  • fusedImg: runs fused into one image and corrected if polydegree set

  • fusedImgFilt: runs fused into one image and filtered

  • seg2bold: strutural segmentation in BOLD space.

  • nodes2bold: strutural nodes in BOLD space.

  • boldToTemplate: BOLD fusedImg mapped to template space.

  • mapsToTemplate: invertible maps from BOLD to template space.

  • runID: Identifies which run over time series.

  • boldMat: Matrix of filtered BOLD data.

  • boldMask: BOLD mask.

  • motionCorr: Motion corrected data.

  • polyNuis: Polynomial nuisance variables.

  • timevals: Temporal variables.

  • nuisance: Nuisance variables.

  • FD: mean framewise displacement.

  • badtimes: time frames that are above FD threshold.

  • dmnAtBOLDres: Default mode network at BOLD resolution in MNI space.

  • seg2template: Segmentation in BOLD resolution MNI space.

  • networkPriors2Bold: WIP: standard network priors in BOLD space.

  • powersLabels: Powers nodes in BOLD space i.e. fusedImg.

  • powersPoints: Powers points in BOLD space i.e. fusedImg.

  • connMatNodes: User provided nodal system connectivity matrix.

  • connMatNodesPartialCorr: TUser provided nodal system partial correlation matrix.

Author

Avants BB, Duda JT

Examples

# this example is long-running ( perhaps 10 minutes on an OSX laptop 2016 )
if (FALSE) { # \dontrun{
exrun <- fMRINormalization(verbose = TRUE) # will download ex data
myid <- "BBAvants" # some MRI data
pre <- paste("~/rsfTest/", sep = "")
fn <- list.files(pre,
  full.names = TRUE, recursive = TRUE,
  pattern = glob2rx(paste(myid, "*rsfMRI0.nii.gz", sep = ""))
)
img <- antsImageRead(fn)
sfn <- list.files(pre,
  full.names = TRUE, recursive = TRUE,
  pattern = glob2rx(paste(myid, "*BrainSegmentation.nii.gz", sep = ""))
)
seg <- antsImageRead(sfn)
t1fn <- list.files(pre,
  full.names = TRUE, recursive = TRUE,
  pattern = glob2rx(paste(myid, "*BrainSegmentation0N4.nii.gz", sep = ""))
)
t1 <- antsImageRead(t1fn)
tt <- fMRINormalization(img,
  repeatMotionEst = 1,
  structuralImage = t1, structuralSeg = seg, verbose = TRUE
)
# bold to template
antsApplyTransforms(mni, getAverageOfTimeSeries(img),
  transformlist = tt$mapsToTemplate$toTemplate,
  whichtoinvert = tt$mapsToTemplate$toTemplateInversion
)
# template to bold
antsApplyTransforms(getAverageOfTimeSeries(img), mni,
  transformlist = tt$mapsToTemplate$toBold,
  whichtoinvert = tt$mapsToTemplate$toBoldInversion
)
} # }