AFNI program: align_epi_anat.py

#++ align_epi_anat version: 1.17

    ===========================================================================
    align_epi_anat.py     - align EPI to anatomical datasets or vice versa
    
    This python script computes the alignment between an EPI and anatomical
    structural dataset and applies the resulting transformation to one or the
    other to bring them into alignment.
    This python script computes the transforms needed to align EPI and  
    anatomical datasets using a cost function tailored for this purpose. The  
    script combines multiple transformations, thereby minimizing the amount of 
    interpolation to the data.
    
    Basic Usage:
      align_epi_anat.py -anat anat+orig -epi epi+orig -epi_base 5
    
    The user must provide EPI and anatomical datasets and specify the EPI
    sub-brick to use as a base in the alignment.  

    Internally, the script always aligns the anatomical to the EPI dataset,
    and the resulting transformation is saved to a 1D file. 
    As a user option, The inverse of this transformation may be applied to the 
    EPI dataset in order to align it to the anatomical data instead.

    This program generates several kinds of output in the form of datasets
    and transformation matrices which can be applied to other datasets if
    needed. Time-series volume registration, oblique data transformations and
    talairach transformations will be combined as needed.
    
    Depending upon selected options, the script's output contains the following:
        Datasets:
          ANAT_al+orig: A version of the anatomy that is aligned to the EPI
          EPI_al+orig: A version of the EPI dataset aligned to the anatomy
          EPI_al+tlrc: A version of the EPI dataset aligned to a standard
                       template
        These transformations include slice timing correction and
          time-series registation by default.

        Transformation matrices:
          ANAT_al_mat.aff12.1D: matrix to align anatomy to the EPI
          EPI_al_mat.aff12.1D:  matrix to align EPI to anatomy 
                                   (inverse of above)
          EPI_vr_al_mat.aff12.1D: matrix to volume register EPI
          EPI_reg_al_mat.aff12.1D: matrix to volume register and align epi
                                      to anatomy (combination of the two
                                      previous matrices)

        Motion parameters from optional volume registration:
          EPI_reg_al_motion.1D: motion parameters from EPI time-series 
                                registration
          
    where the uppercase "ANAT" and "EPI" are replaced by the names of the
    input datasets, and the suffix can be changed from "_al" as a user
    option.
          
        You can use these transformation matrices to align other datasets:
         3dAllineate -cubic -1Dmatrix_apply epi_r1_al_mat.aff12.1D  \
                     -prefix epi_alman epi_r2+orig

             
    The goodness of the alignment should always be assessed. At the face of it,
    most of 3dAllineate's cost functions, and those of registration programs
    from other packages, will produce a plausible alignment but it may not be
    the best. You need to examine the results carefully if alignment quality is
    crucial for your analysis.

    In the absence of a gold standard, and given the low contrast of EPI data,
    it is difficult to judge alignment quality by just looking at the two
    volumes. This is the case, even when you toggle quickly between one volume
    and the next; turning overlay off and using 'u' key in the slice window.
    To aid with the assessment of alignment, you can use the -AddEdge option or
    call the @AddEdge script directly. See the help for @AddEdge for more
    information on that script.

    The default options assume the epi and anat datasets start off fairly close,
    as is normally the case when the epi dataset precedes or follows an 
    anatomical dataset acquisition. If the two data are acquired over separate
    sessions, or accurate coordinate data is not available in the dataset header
    (as sometimes occurs for oblique data), various options allow for larger
    movement including "-cmass cmass", "-big_move" and "-giant_move". Each of
    these options is described below. If datasets do not share the same space
    at all, it may be necessary to use the @Align_Centers script first.
    
    Although this script has been developed primarily for aligning anatomical T1
    data with EPI BOLD data, it has also been successfully applied for aligning
    similar modality data together also including T1-SPGR to T1-SPGR, T1-FLAIR
    to T1-SPGR, EPI to EPI, T1-SPGR at 7T to T1-SPGR at 3T, EPI-rat1 to
    EPI-rat2, .... If this kind of alignment is required, the default cost
    function, the localized Pearson Correlation (lpc), is not appropriate.
    Other cost functions like lpa or nmi have been seen to work well using 
    "-cost lpa".
        
    ---------------------------------------------
    REQUIRED OPTIONS:
    
    -epi dset   : name of EPI dataset
    -anat dset  : name of structural dataset
    -epi_base   : the epi base used in alignment 
                     (0/mean/median/max/subbrick#)

    MAJOR OPTIONS:
    -help       : this help message

    -anat2epi   : align anatomical to EPI dataset (default)
    -epi2anat   : align EPI to anatomical dataset
                  

    -suffix ssss: append the suffix to the original anat/epi dataset to use
                     in the resulting dataset names (default is "_al")
     
    -child_epi dset1 dset2 ... : specify other EPI datasets to align.
        Time series volume registration will be done to the same
        base as the main parent EPI dataset. 

    -child_anat dset1 dset2 ... : specify other anatomical datasets to align.
        The same transformation that is computed for the parent anatomical
        dataset is applied to each of the child datasets. This only makes
        sense for anat2epi transformations. Skullstripping is not done for
        the child anatomical dataset.

    -AddEdge    : run @AddEdge script to create composite edge images of
                  the base epi or anat dataset, the pre-aligned dataset and 
                  the aligned dataset. Datasets are placed in a separate
                  directory named AddEdge. The @AddEdge can then be used
                  without options to drive AFNI to show the epi and anat
                  datasets with the edges enhanced. For the -anat2epi case
                  (the default), the anat edges are shown in purple, and the
                  epi edges are shown in cyan (light blue). For the -epi2anat
                  case, the anat edges are shown in cyan, and the epi edges
                  are purple. For both cases, overlapping edges are shown in
                  dark purple.

    -big_move   : indicates that large displacement is needed to align the
                  two volumes. This option is off by default.
    -giant_move : even larger movement required - uses cmass, two passes and
                  very large angles and shifts. May miss finding the solution
                  in the vastness of space, so use with caution

    -partial_coverage: indicates that the EPI dataset covers only a part of 
                  the brain. Alignment will try to guess which direction should
                  not be shifted If EPI slices are known to be a specific 
                  orientation, use one of these other partial_xxxx options.
    -partial_axial
    -partial_coronal 
    -partial_sagittal

    -keep_rm_files : keep all temporary files (default is to remove them)
    -prep_only  : do preprocessing steps only
    -verb nn    : provide verbose messages during processing (default is 0)
    -anat_has_skull yes/no: Anat is assumed to have skull ([yes]/no)
    -epi_strip  :  method to mask brain in EPI data 
                   ([3dSkullStrip]/3dAutomask/None)
    -volreg_method : method to do time series volume registration of EPI data 
                   ([3dvolreg],3dWarpDrive). 3dvolreg is for 6 parameter 
                   (rigid-body) and 3dWarpDrive is for 12 parameter.

    A template registered anatomical dataset such as a talairach-transformed
       dataset may be additionally specified so that output data are
       in template space. The advantage of specifying this transform here is
       that all transformations are applied simultaneously, thereby minimizing 
       data interpolation.
       
    -tlrc_apar ANAT+tlrc : structural dataset that has been aligned to
                  a master template such as a tlrc dataset. If this option
                  is supplied, then an epi+tlrc dataset will be created.


    Other options:
    -ex_mode       : execute mode (echo/dry_run/quiet/[script]). "dry_run" can
                     be used to show the commands that would be executed 
                     without actually running them. 
                     "echo" shows the commands as they are executed.
                     "quiet" doesn't display commands at all.
                     "script" is like echo but doesn't show stdout, stderr 
                     header lines and "cd" lines.
                     "dry_run" can be used to generate scripts which can be
                     further customized beyond what may be available through
                     the options of this program.
    -Allineate_opts '-ssss  -sss' : options to use with 3dAllineate. Default
                     options are 
                     "-weight_frac 1.0 -maxrot 6 -maxshf 10 -VERB -warp aff "
    -volreg        : do volume registration on EPI dataset before alignment
                     ([on]/off)
    -volreg_opts   : options to use with 3dvolreg
    -volreg_base   : the epi base used in time series volume registration.
                     The default is to use the same base as the epi_base.
                     If another subbrick or base type is used, an additional
                     transformation will be computed between the volume
                     registration and the epi_base
                     (0/mean/median/max/subbrick#)

    -tshift        : do time shifting of EPI dataset before alignment ([on]/off)
    -tshift_opts   : options to use with 3dTshift
                     The script will determine if slice timing correction is
                     necessary unless tshift is set to off.

    -deoblique     : deoblique datasets before alignment ([on]/off)
    -deoblique_opts: options to use with 3dWarp deobliquing
                     The script will try to determine if either EPI or anat data
                     is oblique and do the initial transformation to align anat
                     to epi data using the oblique transformation matrices
                     in the dataset headers.
    
    -master_epi    : master grid resolution for aligned epi output
    -master_tlrc   : master grid resolution for epi+tlrc output
    -master_anat   : master grid resolution for aligned anatomical data output
                     (SOURCE/BASE/MIN_DXYZ/dsetname/n.nn)
                     Each of the 'master' options can be set to SOURCE,BASE,
                     a specific master dataset, MIN_DXYZ or a specified cubic 
                     voxel size in mm. 
                     
                     MIN_DXYZ uses the smallest voxel dimension as the basis
                     for cubic output voxel resolution within the bounding box
                     of the BASE dataset.
                     
                     SOURCE and BASE are used as in 3dAllineate help.
                     
                     The default value for master_epi and master_anat is SOURCE,
                     that is the output resolution and coordinates should be
                     the same as the input. This is appropriate for small
                     movements.
                   
                     For cases where either dataset is oblique (and larger
                     rotations can occur), the default becomes MIN_DXYZ.
                     
                     The default value for master_tlrc is MIN_DXYZ.

    Other obscure and experimental options that should only be handled with 
       care, lest they get out, are visible with -full_help or -option_help.

    Examples:
      # align anat to sub-brick 5 of epi+orig. In addition, do slice timing
      # correction on epi+orig and register all sub-bricks to sub-brick 5
      # (Sample data files are in AFNI_data4/sb23 in sample class data)

      align_epi_anat.py -anat sb23_mpra+orig -epi epi_r03+orig     \
                        -epi_base 5
      
      # Instead of aligning the anatomy to an epi, transform the epi
      # to match the anatomy. Transform other epi run datasets to be
      # in alignment with the first epi datasets and with the anatomical
      # reference dataset. Note that all epi sub-bricks from all runs
      # are transformed only once in the process combining volume
      # registration and alignment to the anatomical dataset in a single
      # transformation matrix

      align_epi_anat.py -anat sb23_mpra+orig -epi epi_r03+orig      \
                        -epi_base 5 -child_epi epi_r??+orig.HEAD    \
                        -epi2anat -suffix al2anat
      
      # Bells and whistles:
      # - create talairach transformed epi datasets (still one transform)
      # - do not execute, just show the commands that would be executed.
      #   These commands can be saved in a script or modified.
      # + a bunch of other options to tickle your mind
      # The talairach transformation requires auto-talairaching 
      # the anatomical dataset first

      @auto_tlrc -base ~/abin/TT_N27+tlrc -input sb23_mpra+orig
      align_epi_anat.py -anat sb23_mpra+orig -epi epi_r03+orig      \
                        -epi_base 6 -child_epi epi_r??+orig.HEAD    \
                        -ex_mode dry_run -epi2anat -suffix _altest  \
                        -tlrc_apar sb23_mpra_at+tlrc


    Our HBM 2008 abstract describing the alignment tools is available here: