-------------------------------------------------------------------------
This program is designed to help line up the major axes of an
anatomical volume with those of the volumetric field of view in
which it sits. A benefit of this would be to have slices that are
more parallel to standard viewing planes and/or a bit more
uniform/standardized across a group. This may be useful, for
example, if you want to use an anatomical for registration of other
data (e.g., diffusion data going to be processed using TORTOISE, esp
if coloring by local orientation), and you want *that* data to be
more regularly oriented for viewing, as well.
This program works by registering (affinely, 9 DOF) the input volume
to some user-defined reference image, but in the end then only
applying the translation+rotation parts of the registration to the
input volume. Before the registration is done, some polishing of
the input volume is performed, in order to remove outliers, but none
of these steps are applied to the output volume itself. Thus, the
idea is to distort the original brain as little as possible (NB:
smoothing will occur as part of this process, e.g., due to rotation
and any regridding), just to reorient it in space. The output
volume can be up/downsampled at the same time, if desired.
You probably *wouldn't* want to use this if your anatomical data set
really fills up its volume (i.e., has no space to rotate/resituation
itself). In that case, you might want to pre-zeropad the volume?
REQUIRES: AFNI.
Ver. 4.32 (PA Taylor, Sep 27, 2021)
-------------------------------------------------------------------------
RUNNING:
This script has two *required* arguments ('-inset ...' and '-refset
...'), and the rest are optional:
$ fat_proc_axialize_anat \
-inset IN_FILE \
-refset REF_FILE \
{-mode_t2w | -mode_t1w} \
-prefix PPP \
{-workdir WWW} \
{-out_match_ref} \
{-do_ceil_out} \
{-extra_al_wtmask WT } \
{-extra_al_cost CC} \
{-extra_al_inps II} \
{-extra_al_opts SS} \
{-focus_mask MMM} \
{-focus_by_ss} \
{-remove_inf_sli II} \
{-pre_align_center_mass} \
{-pre_center_mass} \
{-post_lr_symm} \
{-no_pre_lr_symm} \
{-no_clean} \
{-qc1_ulay_range UMIN UMAX} \
{-no_qc_view} \
{-qc_prefix QCP}
where:
-inset IN_FILE :is the full name of the input anatomical volume.
-refset REF_FILE :is the full name of the reference volume, such as
TT or MNI or something (probably you want to match
the contrast of your anatomical INFILE, whether
there is a skull or not, etc.).
-prefix PPP :output prefix for files and snapshots (required).
-out_match_ref :switch to have the final output volume be in the same
'space' (FOV, spatial resolution) as the REF_FILE.
Might be useful for standardizing the reference
output across a group, or at least centering the brain
in the FOV. (This applies a '-master REF_FILE' to the
final 3dAllineate in the script.)
-mode_t2w :switch to alter some intermediate steps (turn off
unifizing and raise voxel ceiling threshold).
This is particularly useful (= essential,
probably) when dealing with a (adult) T2w image,
which tends to be bright in the CSF and darker in
other tissues; default options are for dealing
with (adult) T1w brains, where the opposite is the
case.
-mode_t1w :similar to the preceding option, but specifying an
image with (human, adult) t1w-like contrast
has been input.
NB ---> one of these 'mode_*' setting MUST be picked.
-do_ceil_out :for the final output volume, apply a ceiling based
on the 98%ile value from within an automasked volume
of the dset. This reduces the influence of (sometimes
very) large spiky voxels. Seems like it might be
useful for later alignments.
-extra_al_wtmask WT:
Axialization is generally based on an overall
whole brain alignment. If you want, however, you
can add extra emphasis to part of the weight mask WT
for deciding what is good alignment. For example,
you might make a WB mask of values ~1 and a make
a subcortical volume have larger values ~5 or so, so
that that part of the brain's alignment carries more
weight (in this example, behaving more like AC-PC
alignment, potentially).
-extra_al_cost CC :specify a cost function for 3dAllineate to work
with (default is 'lpa'; one might investigate
'lpc', esp. if contrasts differ between the
IN_FILE and REF_FILE, or 'nmi').
-extra_al_inps II :specify extra options when *calculating* the warp
with 3dAllineate. These could be any
option+argument combination from the 3dAllineate
helpfile (except the cost function would be done
with "-extra_al_cost CC").
-extra_al_opts SS :specify extra output options when *applying* the
warp with 3dAllineate at the end. One I could see
being useful would be having "-newgrid X", where X
is desired final resolution of the data.
-focus_by_ss :make a mask by simply skullstripping input data
set, which gets applied early on to focus the
processing+alignment; the final, axialized volume
will not have the mask applied, it's just used to
help get rid of non-brain garbage. Might be very
useful if the input volume has _lots_ of non-brain
material.
-focus_mask MMM :input a mask of the inset that gets applied early
on to focus the processing+alignment; the final,
axialized volume will not have the mask applied,
it's just used to help get rid of non-brain
garbage. Note: before application, MMM gets binarized
to 1 where MMM>0 and 0 elsewhere.
-remove_inf_sli II :sometimes data is acquired with lots of nonbrain
volume in the FOV, particularly neck and things like
that. While necks are important, they also might
move the center of mass estimate of the brain
far lower than it should be. You can get rid of this
by applying this option, to remove 'II' number of
slices from the inferior part of the FOV.
-pre_align_center_mass :
pre-align the centers of mass of the volumes; might help
in conjunction with '-remove_inf_sli ...' above, when
there is a large amount of non-brain material
-pre_center_mass :pre-recenter input center of mass to (0, 0, 0); probably
the '-pre_align_center_mass' would be more useful, but
this can be used similarly.
-no_pre_lr_symm :a pre-alignment left-right symmetrization is
performed by default, but you can turn it off if you
desire (probably wouldn't want to in most cases,
unless *weird* stuff were happening).
-post_lr_symm :a post-alignment left-right symmetrization can be
added, if desired.
-workdir WWW :the name of the working subdirectory in the output
directory can be specified
(default: __WORKING_axialize_anat).
-no_clean :is an optional switch to NOT remove working
directory '__WORKING_axialize_anat';
(default: remove working dir).
-no_cmd_out :by default, a copy of the command and file location
from which it is run is dumped into the WORKDIR
(file name: 'PREFIX*_cmd.txt').
If you don't want this to happen, then use this
switch.
-qc1_ulay_range UMIN UMAX
:provide a min (UMIN) and max (UMAX) range for
underlay grayscale bar (black=UMIN; white=UMAX).
For QC visualization only-- does not affect the
actual MRI data files.
-no_qc_view :turn off default+automatic QC image saving/viewing
(whyyy would you do this?).
-qc_prefix QCP :provide a prefix for the QC stuff, separate from
the PREFIX above.
------------------------------------------------------------------------
OUTPUTS:
PREFIX.nii.gz :an anatomical data set that is *hopefully*
regularly situated within its FOV volume. Thus,
the axial slices would sit nicely within a given
view window, etc.
WORKDIR :the working directory with intermediate files, so
you can follow along with the process and possibly
troubleshoot a bit if things go awry (what are the
odds of *that* happening?).
-------------------------------------------------------------------------
EXAMPLE:
fat_proc_axialize_anat \
-inset SUB001/ANATOM/T1.nii.gz \
-refset /somewhere/mni_icbm152_t1_tal_nlin_sym_09a_MSKD.nii.gz \
-mode_t1w \
-extra_al_opts "-newgrid 1.0" \
-focus_by_ss \
-prefix t2w_axlz
or
fat_proc_axialize_anat \
-inset SUB001/ANATOM/T2.nii.gz \
-refset /somewhere/mni_icbm152_t2_tal_nlin_sym_09a.nii.gz \
-extra_al_wtmask mni_icbm152_t2_relx_tal_nlin_sym_09a_ACPC_wtell.nii.gz \
-mode_t2w \
-prefix t2w_axlz
-------------------------------------------------------------------------
TIPS:
+ When analyzing adult T1w data, using the following option might
be useful:
-extra_al_inps "-nomask"
Using this, 3dAllineate won't try to mask a subregion for
warping/alignment, and I often find this helpful for T1w volumes.
+ If the input volume has lots of non-brain material (lots of neck or
even shoulders included), then consider "-focus_by_ss" or
"-focus_mask ..". It helps when trying to roughly align vols initially
with center of mass, esp. if using "-pre_align_center_mass". Also, for
T1w vols this might be particularly effective.
+ For centering data, using the '-out_match_ref' switch might be
useful; it might also somewhat, veeeery roughly help standardize
a group of subjects' data in terms of spatial resolution, centering
in FOV, etc.
+ To try to get something closer to AC-PC alignment, one can add in a
weight mask with '-extra_al_wtmask ...' that has the ~subcortical
region given extra weight.
