adjunct_tort_plot_dp_align¶
OVERVIEW¶
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¶
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¶
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. 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
