# -----------------------------------------------------------------------
This program is for bringing data sets into DWI space, with the
particular thought that bringing anatomically-defined ROI maps or EPI
data that are aligned to a subject's anatomical might be useful.
This might be useful after having run FreeSurfer, for example.
An affine transformation matrix between, say, a subject's T1w volume
and a DWI reference volume is calculated, and then applied to
follower data sets. The transformation can be applied either as 'NN'
(-> for preserving integer values in sets) or as 'wsinc5' (-> if one
has floating point values). The final dsets will reside in the DWI
space. Yay.
At the moment this program *assumes* that the input source ('-source
SSS') and reference base ('-base BBB') are from the same subject,
because only 12 DOF affine alignment is calculated (using
3dAllineate). Maybe something could be done with 3dQwarp in the
future. Maybe.
This program mainly assumes that the T1w and DWI reference volume
have similar contrasts expected for standard sequences and healthy
adult brains. This might still work for other applications, but
caveat emptor (even more than usual!). This would *not* be
recommended for aligning brains that aren't from the same subject.
Ver. 2.32 (PA Taylor, Sep 27, 2021)
# ----------------------------------------------------------------------
OUTPUT:
+ NIFTI file: aligned T1w volume.
+ NIFTI files: each follower DSET* ends up in the DWI/DTI space
and has a respective name PREFIX_DSET*.nii.gz.
+ QC snapshots of the T1w volume overlaying the DWI reference
volume, and also the T1w edges overlaying the ref vol.
+ QC snapshots of each of the follower dsets overlaying the DWI ref
volume.
# ----------------------------------------------------------------------
RUNNING:
fat_proc_map_to_dti \
-source SSS \
-base DDD \
-prefix PPP \
{-followers_NN DSET01 DSET02 DSET03 ...} \
{-followers_wsinc5 DSET1 DSET2 DSET3 ...} \
{-followers_surf SURF1 SURF2 SURF3 ...} \
{-followers_ndset NDSET1 NDSET2 NDSET3 ...} \
{-followers_spec SPEC1 SPEC2 SPEC3 ...} \
{-matrix MMM} \
{-workdir WWW} \
{-no_cmd_out} \
{-no_clean}
where:
-source SSS :T1w volume (required); 'source' volume from which we
are mapping, such as an anatomical volume in whose
space ROIs might have been defined. SSS gets
mapped into the '-base BBB' volume's space.
-base BBB :DWI reference volume (required; should be from same
subject as SSS), such as the b=0 (or minimally DWed
volume), for aligning to; subbrick selections are
allowed, so that dwi_dwi.nii'[0]', for example,
would be allowed. This is the base dset for the
alignment, with the purpose to bring other volumes
into the DWI/DTI space (see the '-followers* ...'
options, below). **NOTE**: BBB and SSS should be
from the same subject by this function, because
only affine alignment with 3dAllineate is
performed!
-prefix PPP :output prefix for files and snapshots. Required.
-followers_NN DSET01 DSET02 DSET03 ...
:apply the same transformation to 'follower' data
sets; one or more dsets can be listed, with each
assumed to overlay on the T1W source set. The 'NN'
interpolation of 3dAllineate is applied to these
dsets, so that integer values remain integer
valued; thus, these might be dsets with ROI maps
already created. NB: subbrick selectors are not
allowed on the DSETs here at present. Labeltables
attached to these dsets do get propagated, as well.
-followers_wsinc5 DSET1 DSET2 DSET3 ...
similar to the above '-followers_NN ...', except in
this case the final applied mapping is 'wsinc5', which
is appropriate, for example, for floating point values.
Again, a list of one or more volumes (sans subbrick
selectors) can be provided here. No labeltable is
propagated for these sets (I doubt they would have one,
anyways).
-followers_surf SURF1 SURF2 SURF3 ...
:similar to the above '-followers_* ...', except in
this case the mapping is applied to surface dsets, such
as '*.gii'. Per usual, a list of one or more surfaces
can be provided here.
-followers_ndset NDSET1 NDSET2 NDSET3 ...
:similar to the above '-followers_* ...', except in
this case the mapping is applied to '*.niml.dset' files,
such as '*.annot.niml.dset'. Per usual, a list of one or
more surfaces can be provided here. Prob wouldn't make
sense to use this without using '-followers_surf ...'.
-followers_spec SPEC1 SPEC2 SPEC3 ...
:similar to the above '-followers_* ...', except in
this case the mapping is applied to '*.spec' files.
Per usual, a list of one or more surfaces can be
provided here. Wouldn't make sense to use this without
using both '-followers_surf ...' and '-followers_ndset ...'
to map the dsets referred to in the file!
-matrix MMM :one can apply a pre-made matrix that has been made by
3dAllineate previously. With this option. If you want.
-cost CCC :one can apply any cost function CCC that is
accepted by 3dAllineate. The default is for
matching dsets of opposite contrast, such as a T1w
to a b=0 DWI, which is like a T2w contrast (def:
lpc).
-warp xxx :one can set the linear affine warp type through the
same warp arguments accepted by 3dAllineate: shift_only,
shift_rotate, shift_rotate_scale, affine_general, etc.
(def: affine_general).
-workdir WWW :specify a working directory, which can be removed;
(default name = '__WORKING_map_to_dti')
-no_cmd_out :don't save the command line call of this program
and the location where it was run (otherwise, it is
saved by default in the ODIR/).
-no_clean :do not delete temporary working directory (default is
to remove it to save disk space).
# ----------------------------------------------------------------------
EXAMPLE
fat_proc_map_to_dti \
-source brain.nii \
-base dwi_dwi.nii.gz'[0]' \
-prefix indt \
-followers_NN aparc*_REN_*.nii.gz \
-followers_surf std.141.*gii \
-followers_ndset std.141.*niml.dset \
-followers_spec std.141.*.spec
# -----------------------------------------------------------------------
