AFNI program: @simulate_motion

Output of -help

---------------------------------------------------------------------------
@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
---------------------------------------------------------------------------
This page auto-generated on Thu Oct 31 09:45:21 PM EDT 2024