AFNI program: @SSwarper

Output of -help


 EOF

This script has dual purposes for processing a given subject's
anatomical volume:
    + to skull-strip the brain, and 
    + to calculate the warp to a reference template/standard space.
Automatic snapshots of the registration are created, as well, to help 
the QC process.

This program cordially ties in directly with afni_proc.py, so you can
run it beforehand, check the results, and then provide both the
skull-stripped volume and the warps to the processing program.  That
is convenient!

Current version = 1.2
Authorship      = RW Cox

# -----------------------------------------------------------------

USAGE

    @SSwarper          \
        -input  AA        \
        -base   BB        \
        -subid  SS        \
       {-odir OD}         \
       {-minp MP}

where:

  -input  AA :(req) an anatomical dataset, *not* skull-stripped, with
              resolution about 1 mm.

  -base   BB :(req) a base template dataset, with contrast similar to
              the input AA dset, probably from some kind of standard
              template.  
              NB: this dataset is not *just* a standard template,
              because it is not a single volume-- read about its
              composition in the NOTES on the 'The Template Dataset', 
              below.
              The program first checks if the dset BB exists as
              specified; if not, then if just the filename has been
              provided it searches the AFNI_GLOBAL_SESSION,
              AFNI_PLUGINPATH, and afni bin directory (in that order)
              for the named dataset.

  -subid  SS :(req) name code for output datasets (e.g., 'sub007').

  -odir   OD :(opt) output directory for all files from this program
              (def: directory of the '-input AA').

  -minp   MP :(opt) minimum patch size on final 3dQwarp (def: 11).

The template dataset 'MNI152_2009_template_SSW.nii.gz' is supplied
with AFNI binaries and is described later in this help (it is
identical to the originally-named 'MNI152_2009_template.nii.gz').  You
can make other reference base templates in whatever space you prefer,
but note that it must have several subvolumes of information
included-- see NOTES on the 'The Template Dataset', below.

# ----------------------------------------------------------------------

OUTPUTS

Suppose the -prefix is 'sub007' (because you scanned Bond, JamesBond?).  
Then the outputs from this script will be"

  anatU.sub007.nii        = intensity uniform-ized original dataset;
  anatS.sub007.nii        = first pass skull-stripped original dataset;
  anatSS.sub007.nii       = second pass skull-stripped original dataset;
  anatQQ.sub007.nii       = skull-stripped dataset nonlinearly warped to
                            the base template space;
  anatQQ.sub007.aff12.1D  = affine matrix to transform original dataset
                            to base template space;
  anatQQ.sub007_WARP.nii  = incremental warp from affine transformation
                            to nonlinearly aligned dataset;
  AMsub007.jpg            = 3x3 snapshot image of the anatQQ.sub007.nii
                            dataset with the edges from the base template
                            overlaid -- to check the alignment;
  MAsub007.jpg            = similar to the above, with the roles of the
                            template and the anatomical datasets reversed.

* The .aff12.1D and _WARP.nii transformations need to be catenated to get
  the full warp from orginal space to the base space; example:
    3dNwarpApply -nwarp 'anatQQ.sub007_WARP.nii anatQQ.sub007.aff12.1D' ...

* It is important to examine (at least) the two .jpg snapshot images to
  make sure that the skull-stripping and nonlinear warping worked well.

* The inputs needed for the '-tlrc_NL_warped_dsets' option to afni_proc.py
  are (in this order):
    anatQQ.sub007.nii anatQQ.sub007.aff12.1D anatQQ.sub007_WARP.nii

* When B-O-B uses this script for skull-stripping plus warping, He
  gives afni_proc.py these options (among others), after running
  @SSwarper successfully -- here, 'subj' is the subject
  identifier:

  |  set btemplate = MNI152_2009_template_SSW.nii.gz    
  |  set tpath = `@FindAfniDsetPath ${btemplate}`
  |  if( "$tpath" == "" ) exit 1                    
  |                                                 
  |  afni_proc.py                                                  \
  |    [...other stuff here: processing blocks, options...]        \
  |    -copy_anat anatSS.${subj}.nii                               \
  |    -anat_has_skull no                                          \
  |    -align_opts_aea -ginormous_move -deoblique on -cost lpc+ZZ  \
  |    -volreg_align_to MIN_OUTLIER                                \
  |    -volreg_align_e2a                                           \
  |    -volreg_tlrc_warp -tlrc_base $tpath/$btemplate              \
  |    -tlrc_NL_warp                                               \
  |    -tlrc_NL_warped_dsets                                       \
  |       anatQQ.${subj}.nii                                       \
  |       anatQQ.aff12.1D                                          \
  |       anatQQ.${subj}_WARP.nii

# -------------------------------------------------------------------

NOTES

+ The Template dataset

  Any reference base template dataset, such as
  MNI152_2009_template_SSW.nii.gz, must have the first *4* volumes here
  (and can have the optional 5th for later uses, as described):
    [0] = skull-stripped template brain volume
    [1] = skull-on template brain volume
    [2] = weight mask for nonlinear registration, with the
          brain given greater weight than the skull
    [3] = binary mask for the brain
    [4] = binary mask for gray matter plus some CSF (slightly dilated)
          ++ this volume is not used in this script
          ++ it is intended for use in restricting FMRI analyses
             to the 'interesting' parts of the brain
          ++ this mask should be resampled to your EPI spatial
             resolution (see program 3dfractionize), and then
             combined with a mask from your experiment reflecting
             your EPI brain coverage (see program 3dmask_tool).

+ You Know My Methods, Watson

  #1: Uniform-ize the input dataset's intensity via 3dUnifize.
       ==> anatU.sub007.nii
  #2: Strip the skull with 3dSkullStrip, with mildly agressive settings.
       ==> anatS.sub007.nii
  #3: Nonlinearly warp (3dQwarp) the result from #1 to the skull-on
      template, driving the warping to a medium level of refinement.
  #4: Use a slightly dilated brain mask from the template to
      crop off the non-brain tissue resulting from #3 (3dcalc).
  #5: Warp the output of #4 back to original anatomical space,
      along with the template brain mask, and combine those
      with the output of #2 to get a better skull-stripped
      result in original space (3dNwarpApply and 3dcalc).
       ==> anatSS.sub007.nii
  #6  Restart the nonlinear warping, registering the output
      of #5 to the skull-off template brain volume (3dQwarp).
       ==> anatQQ.sub007.nii (et cetera)
  #7  Use @snapshot_volreg3 to make the pretty pictures.
       ==> AMsub007.jpg and MAsub007.jpg

+ Temporary files

  If the script crashes for some reason, it might leave behind files
  whose names start with 'junk.SSwarper' -- you should delete these
  files manually.

# -------------------------------------------------------
  Author: Bob, Bob, there is one Bob, He spells it B-O-B.
# -------------------------------------------------------


This page auto-generated on Fri Jul 6 16:51:48 EDT 2018