:orphan:

.. _ahelp_adjunct_tort_plot_dp_align:

**************************
adjunct_tort_plot_dp_align
**************************

.. contents:: :local:


| 

    

OVERVIEW
========

.. code-block:: none

    
    When processing DWI data with TORTOISE's DIFFPREP, you (yes, you!) can
    view some of the output alignment parameters.  In particular, this
    program displays the rigid-body alignment parameters (3 rotations and
    3 translations), which might give you a sense of subject motion.
    (Note that due to the presence of other distortions and effects in DWI
    data, more than just subject motion is likely shown via these params.)
    
    This (AFNI) program has been tested on TORTOISE versions 3.1* - 3.2.
    We hope to keep it up-to-date on future versions, as well.
    
    auth = PA Taylor (NIMH, NIH, USA)
    

OUTPUTS
=======

.. code-block:: none

    
    This program outputs multiple files with the user's specified PREFIX:
    
      PREFIX_align.1D : text file, 6 columns of data corresponding to the
                        6 rigid-body alignment parameters estimated by
                        DIFFPREP (in order, left-to-right):
                          del x (for axial data, RL translation)
                          del y (for axial data, AP translation)
                          del z (for axial data, IS translation)
                          Rx    (for axial data, rotation around x axis)
                          Ry    (for axial data, rotation around y axis)
                          Rz    (for axial data, rotation around z axis)
                        Units are mm and deg.  One row per input DWI volume.
    
      PREFIX_enorm.1D : text file with 1 column of data, the Euclidean
                        norm (enorm) of the differences of the rigid body
                        alignment parameters.  Essentially, a scalar
                        estimate of motion.  Units are "~mm", which means
                        "approx mm":
                        ... Combining rotation+translation is at first odd
                        to see, but for the typical human brain, rotation
                        by 1 deg causes the edge of the brain to move
                        about 1 mm.  Hence this approximation.  This seems
                        to provide a good sense of when motion is "large"
                        and when it isn't (because this is an L2-norm of
                        motion estimates).
    
       PREFIX.jpg     : a plot of enorm and the alignment parameters, made
                        using AFNI's 1dplot.  
    
       PREFIX.svg     : a plot of enorm and the alignment parameters, made
                        using AFNI's 1dplot.py -- this is a fancier plot,
                        requiring Python+Matplotlib to be installed on the
                        computer.  This script automatically checks to see
                        if those dependencies are installed, and will make
                        this image if it can; otherwise, it skips it.
                        SVG is a vector graphic format, so it makes for nice
                        line plots.
                        Some aspects of the enorm plot (e.g., y-axis range
                        and an extra horizontal line for visualization
                        fun) can be controlled for this image.
    

USAGE
=====

.. code-block:: none

    
        adjunct_tort_plot_dp_align               \
            -input   DIFFPREP_TRANSFORM_FILE     \
            -prefix  OUTPUT                      \
    
    where:
    
        -input III    : name of DIFFPREP-produced file to parse, probably
                        ending  in "_transformations.txt".
    
        -prefix PPP   : base of output files;  can contain path information.
                        Should *not* include any extension (each output adds
                        their own appropriate one). 
    
        -enorm_max EM : specify max value of y-axis of enorm plot in SVG image.
                        (Def value of y-axis range is to just show all values.)
                        Can be useful to have a constant value across a study,
                        so you see relative differences easily when flipping 
                        through images.      
    
      -enorm_hline EH : specify value of a horizontal, dotted, bright cyan
                        line for the enorm plot in SVG image. (Default: none.)
                        Can help with visualization.  No censoring happens
                        from this.
                        
      -no_svg         : opt to turn off even *checking* to plot an SVG version
                        of the figure (default is to check+do if possible).
                        I don't know why you would use this option... the SVG
                        is nice.
    

EXAMPLE
=======

.. code-block:: none

    
      # 1.  Make plots of the transformation information, with "-enorm_*
            .." values picked for convenience, as a good fraction of voxel
            size (say, max is 50-75% of voxel edge length):
    
      adjunct_tort_plot_dp_align                                              \
            -input       SUBJ_001/dwi_03_ap/ap_proc_eddy_transformations.txt  \
            -prefix      SUBJ_001/dwi_03_ap/QC/ap_proc                        \
            -enorm_max   1                                                    \
            -enorm_hline 0.5