---------------------------------------------------------------------------
@simulate_motion - create simulated motion time series
This program is meant to simulate motion in an EPI time series based only
on the motion parameters and an input volume.
The main action is to take the EPI (motion base) volume and (inverse) warp
it according to the motion parameters. In theory, the result could be run
through 3dvolreg to generate a similar set of motion parameters.
Note: if slice timing is provided (via the -epi or -epi_timing datasets),
then slices will be generated individually at the interpolated offset
into each TR.
An "aligned" result could then be computed via -warp_method and related
options. Methods include:
VOLREG: run 3dvolreg on result
VR_PARAMS: apply the motion parameters, instead
VOLREG_AND_WARP: 3dvolreg, then combine the transformations with
anat alignment and standard space transformation
VR_PARAMS_AND_WARP: catenate volreg params with affine transformation
WARP: re-apply complete motion param/anat align/standard
space transformations
How to use the result:
The resulting time series can be used to create regressors of no
interest, when trying to regress out motion artifacts (from either
task or resting state analysis). Ways it can be used:
a. Grab the first N (e.g. 6) principle components, and use them along
with other motion parameters. To do this, just run 3dpc with the
simulated time series and an appropriate mask.
b. First make the time series orthogonal to the motion parameters, and
only then take the first N principle components. For example, run
3dDeconvolve to remove the original motion parameters, and use the
resulting errts dataset as input to 3dpc.
c. Do voxel-wise regression with single, blurred or locally averaged
time series via 3dTfitter.
Note that if censoring is being done, such TRs would have to be
removed, as 3dTfitter does not have a -censor option.
i) extract usable TRs with '1d_tool.py -show_trs_uncensored ...'
ii) pass the X-matrix and extracted series to 3dTfitter
Eventually these methods can be put into afni_proc.py. Please pester
Rick if you have interest in any method that has not been implemented.
usage: @simulate_motion [options] -epi EPI_DSET -motion_file MOTION_PARAMS
needed inputs: EPI volume, motion parameters
output: motion simulated EPI time series
examples:
1a. process in orig space, no slice timing
Create a time series that has motion similar to what would include
the given motion_file.
@simulate_motion -epi pb01.FT.r01.tshift+orig"[2]" -prefix msim.1a \
-motion_file dfile_rall.1D
1b. process in orig space, with slice timing
@simulate_motion -epi pb01.FT.r01.tshift+orig"[2]" -prefix msim.1b \
-motion_file dfile_rall.1D \
-epi_timing pb00.FT.r01.tcat+orig
1c. use post-tlrc volreg base (slice timing not an option, of course)
@simulate_motion -epi pb02.FT.r01.volreg+tlrc"[2]" -prefix msim.1c \
-motion_file dfile_rall.1D \
examples with -warp_method ...
2. apply 3dvolreg to realign the time series
Note that running 3dvolreg should produce a 1Dfile that is similar to the
input motion file.
@simulate_motion -epi pb01.FT.r01.tshift+orig"[2]" -prefix msim.2.vr \
-motion_file dfile_rall.1D \
-warp_method VOLREG
3. instead of re-running 3dvolreg, apply the original volreg params
Note that running 3dvolreg should produce a 1Dfile that is similar to the
input motion file.
@simulate_motion -epi pb01.FT.r01.tshift+orig"[2]" -prefix msim.3.vrp \
-motion_file dfile_rall.1D \
-warp_method VR_PARAMS
4. like #2, but include a transformation that would align to the anatomy
and warp to standard space
The additional -warp_1D option requires a corresponding -warp_master for
the resulting grid.
@simulate_motion -epi pb01.FT.r01.tshift+orig"[2]" -prefix msim.4.vrw \
-motion_file dfile_rall.1D \
-warp_method VOLREG_AND_WARP \
-warp_1D anat_std.aff12.1D \
-warp_master pb02.FT.r01.volreg+tlrc
5. no 3dvolreg or params, those transformations are already in -warp_1D
(such as that used in the end by afni_proc.py, if align and std space)
Also, include -wsync5 interpolation.
@simulate_motion -epi pb01.FT.r01.tshift+orig"[2]" -prefix msim.5.warp \
-motion_file dfile_rall.1D \
-warp_method WARP \
-warp_1D mat_rall.warp.aff12.1D \
-warp_master pb02.FT.r01.volreg+tlrc \
-wsinc5
informational options:
-help : show this help
-hist : show program modification history
-todo : show current todo list
-ver : show program version
required parameters:
-epi EPI : provide input volume or time series
(only a volreg base is needed, though more is okay)
If slice timing is to be used, the number of slices
must match that of the -epi_timing dataset. So it
should not be the case where one view is +orig and
the other +tlrc, for example.
-motion_file MOTFILE : specify motion parameter file (as output by 3dvolreg)
options:
-epi_timing DSET : provide EPI dataset with slice timing
(maybe -epi no longer has slice times)
-prefix PREFIX : prefix for data results
(default = motion_sim.NUM_TRS)
-save_workdir : do not remove 'work' directory
-test : only test running the program, do not actually
create a simulated motion dataset
(not so useful anymore)
-verb LEVEL : specify a verbose level (default = 1)
-vr_base INDEX : 0-based index of volreg base in EPI dataset
-warp_method METHOD : specify a METHOD for forward alignment/transform
e.g. -warp_method WARP
default: NONE
NONE: do nothing after inverse motion
VOLREG: run 3dvolreg on result
VR_PARAMS: re-apply the motion parameters on the result
VOLREG_AND_WARP: apply both VOLREG and WARP methods
Run 3dvolreg on result, then combine the registration
transformations with those of anat alignment and
standard space transformation.
* requires -warp_1D and -warp_master
VR_PARAMS_AND_WARP: catenate volreg params with affine transformation
(such as aligning to anat and going to standard space)
WARP: re-apply the complete motion param/anat align/standard
space transformations
* requires -warp_1D and -warp_master
-warp_1D : specify a 12 parameter affine transformation,
presumably to go from orig space to standard space,
or including a volreg transformation
e.g. -warp_1D mat_rall.warp.aff12.1D
This command must be paired with -warp_master, and
requires -warp_method WARP or VOLREG_AND_WARP.
-warp_master DSET : specify a grid master dataset for the -warp_1D xform
e.g. -warp_master pb02.FT.r01.volreg+tlrc
This DSET should probably be one of the volreg+tlrc
results from an afni_proc.py script.
-wsinc5 : use wsinc5 interpolation in 3dAllineate
-------------------------------------------------------
R Reynolds May, 2013
