AFNI program: adjunct_tort_plot_dp_align

Output of -help


OVERVIEW ~1~

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 ~1~

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 ~1~

    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 ~1~

  # 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
This page auto-generated on Thu Oct 31 09:42:59 PM EDT 2024