antsrMotionCalculation

Correct time-series data for motion.

antsrMotionCalculation(
  img,
  fixed,
  mask,
  typeofTransform = c("Rigid", "QuickRigid", "BOLDRigid", "Affine", "AffineFast",
    "BOLDAffine", "SyN", "SyNOnly"),
  getMotionDescriptors = TRUE,
  verbose = FALSE,
  num_threads = 1,
  seed = NULL,
  ...
)

Arguments

img

antsImage, usually ND where D=4.
fixed

Fixed image to register all timepoints to. If not provided, mean image is used.
mask

mask for image (ND-1). If not provided, estimated from data.
typeofTransform

One of "Affine", "Rigid", '"BOLDAffine", "BOLDRigid", "QuickRigid".
getMotionDescriptors

computes dvars and framewise displacement. May take additional memory.
verbose

enables verbose output.
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.
...

extra parameters passed to antsRegistration

Value

List containing:

  • moco_img Motion corrected time-series image.

  • moco_params Data frame of translation parameters.

  • moco_avg_img Average motion-corrected image.

  • moco_mask Mask used to calculate framewise displacement.

  • fd Time-series mean and max displacements.

  • dvars DVARS, derivative of frame-wise intensity changes.

Note

For reproducible results, you should run Sys.setenv(ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS = 1), which is what the num_threads = 1 flag will do. See https://github.com/ANTsX/ANTs/wiki/antsRegistration-reproducibility-issues and https://github.com/ANTsX/ANTsR/issues/210#issuecomment-377511054 for discussion

Examples

Sys.setenv(ITK_GLOBAL_DEFAULT_NUMBER_OF_THREADS = 1)
Sys.setenv(ANTS_RANDOM_SEED = 1)
set.seed(120)
simimg<-makeImage(rep(5,4), rnorm(5^4))
testthat::expect_equal(mean(simimg), 0.0427369860965759)
res = antsrMotionCalculation( simimg , seed = 1234)
res2 = antsrMotionCalculation( simimg , seed = 1234)
res3 = antsrMotionCalculation( simimg, num_threads = 1, seed = 1 )
        testthat::expect_equal(res, res2)
# testthat::expect_failure(testthat::expect_equal(res, res3))
print(res$fd)
#>   MeanDisplacement MaxDisplacement
#> 1         8.759284        8.759284
#> 2         4.722396        4.722396
#> 3         9.079914        9.079914
#> 4         3.254630        3.254630
#> 5         0.000000        0.000000
print(res3$fd)
#>   MeanDisplacement MaxDisplacement
#> 1         8.759284        8.759284
#> 2         4.722396        4.722396
#> 3         9.079914        9.079914
#> 4         3.254630        3.254630
#> 5         0.000000        0.000000
print(res$moco_params)
#>      MOCOparam1 MOCOparam2 MOCOparam3 MOCOparam4 MOCOparam5 MOCOparam6
#> [1,]  0.8070312 -2.7196524  -7.722021          0          0          0
#> [2,]  0.6403608  0.7210882   0.331462          0          0          0
#> [3,] -3.5773988  0.7025864  -1.792493          0          0          0
#> [4,]  3.4404235 -2.8812182   2.718754          0          0          0
#> [5,]  2.5139089  0.2271850   2.987108          0          0          0
print(res3$moco_params)
#>      MOCOparam1 MOCOparam2 MOCOparam3 MOCOparam4 MOCOparam5 MOCOparam6
#> [1,]  0.8070312 -2.7196524  -7.722021          0          0          0
#> [2,]  0.6403608  0.7210882   0.331462          0          0          0
#> [3,] -3.5773988  0.7025864  -1.792493          0          0          0
#> [4,]  3.4404235 -2.8812182   2.718754          0          0          0
#> [5,]  2.5139089  0.2271850   2.987108          0          0          0