@SUMA_Make_Spec_FS


++ Running @SUMA_Make_Spec_FS version: 2.2.1

OVERVIEW

@SUMA_Make_Spec_FS - prepare for surface viewing in SUMA

This script goes through the following steps:
    + verify existence of necessary programs
      (afni, to3d, suma, mris_convert)
    + determine the location of surface and COR files
    + creation of ascii surface files via 'mris_convert'
    + creation of left and right hemisphere SUMA spec files
    + creation of an AFNI dataset from the COR files via 'to3d'
    + creation of AFNI datasets from various .mgz volumes created
      by FreeSurfer. The segmentation volumes with aseg in the
      name are best viewed in AFNI with the FreeSurfer_Seg_255
      colormap. See bottom of @SUMA_FSvolToBRIK -help for more
      info.
    + renumbered data sets output, to replace old '*rank*' file data
      sets. Also new tissue maps based on FS functions and
      labels. Collectively, these are the '*REN*' dsets in the output
      directory.  (Rank dsets are no longer output by default, from
      Nov, 2019; instead, use -make_rank_dsets if really needed.)
    + convenience dsets for afni_proc.py processing with tissue-based
      regressors (fs_ap_* files: subset of ventricle and WM maps)

    + all created files are stored in a new SUMA directory

USAGE

      @SUMA_Make_Spec_FS [options] -sid SUBJECT_ID

examples ('-NIFTI' is really useful-- see below!):

      @SUMA_Make_Spec_FS -help
      @SUMA_Make_Spec_FS -NIFTI -sid subject1
      @SUMA_Make_Spec_FS -NIFTI -fspath subject1/surface_stuff -sid subject1
      @SUMA_Make_Spec_FS -NIFTI -sid 3.14159265 -debug 1

OPTIONS

-help    : show this help information

-debug LEVEL    : print debug information along the way
      e.g. -debug 1
      the default level is 0, max is 2

      A debug level of 2 will "set echo", so one can follow the actual
      commands executed in the script.

-fs_setup       : source $FREESURFER_HOME/SetUpFreeSurfer.csh

      This might be useful on OS X, as FreeSurfer uses DYLD_LIBRARY_PATH,
      which does not propagate to child shells.  Then this program would
      require them to source SetUpFreeSurfer.csh from .cshrc, which might
      happen too often and could be irrirating.

      With -fs_setup, that will happen from within this script, so it is
      not necessary to do from the .cshrc file.

-fspath PATH    : path to 'surf' and 'orig' directories
      e.g. -fspath subject1/surface_info
      the default PATH value is './', the current directory

      This is generally the location of the 'surf' directory,
      though having PATH end in surf is OK.  The mri/orig
      directory should also be located here.

      Note: when this option is provided, all file/path
      messages will be with respect to this directory.

-extra_annot_labels L1 L2 ...  : convert extra annot files into ROI dsets
      e.g. -extra_annot_labels aparc

      FS typically outputs annotaion files:
            lh.aparc.a2005s.annot
            rh.aparc.a2005s.annot
            lh.aparc.a2009s.annot
            rh.aparc.a2009s.annot
      from each of which Make_Spec extracts a colormap, ROI and a
      displayable surface dataset.

      Use this option to specify other labels to extract.

      If LABEL is specified, then expected annotation files will be:
            lh.LABEL.annot
            rh.LABEL.annot

-extra_fs_dsets AA BB CC ...
                : FS calculates many types of data on the surface,
      listed in their surf/ output directory.  By default, this
      program brings the following ones into the SUMA surface realm:
            thickness   curv   sulc
      which get turned into 'std.141.{l,r}h.curv.niml.dset' and
      '{l,r}h.curv.gii.dset' files, for example.
      This option allows the user to list *other* dsets to include,
      as well.  Ones that users have selected are, for example:
            volume   area   area.pial   curv.pial

-make_rank_dsets : before Nov 14, 2019, *rank* dsets used to be
      created by this command by default; these dsets mapped the
      FreeSurfer ROI numbering to a 1..N set of labels, where N
      was the number of ROIs.  Because this number might *not* be
      constant across a group (though, the ROI string labels in
      each would be), we don't recommend using these; the *REN*
      dsets are renumbered in a consistent, mapped way, and so
      those are more useful.  The present option is purely for
      backward compatability, for Zome Special Scientists out
      there who might still use these dsets.

-use_mgz        : use MGZ volumes even if COR volumes are there

-neuro          : use neurological orientation
      e.g. -neuro
      the default is radiological orientation

      In the default radiological orientation, the subject's
      right is on the left side of the image.  In the
      neurological orientation, left is really left.

    * This is not compatible with -NIFTI.

-nocor: This option is no longer supported because it created
        GIFTI surfaces with coordinates in RAI, rather than LPI
        which is the GIFTI standard. While using RAI surfaces
        within AFNI/SUMA is not problematic, the resultant GIFTI
        surfaces do not port well to other software.
        The replacement option for -nocor is -GNIFTI but the
        surfaces will have negated coordinates along the x and y
        compared to those with -nocor.
        GIFTI surfaces produced with SUMA programs compiled before
        August 1st 2013 will have their X and Y coordinates
        negated and will no longer line up with the anatomy.
        Correcting such surfaces can be done with ConvertSurface
        with the following command:

            ConvertSurface                \
                -i lh.smoothwm.gii        \
                -o_gii lh.smoothwm        \
                -overwrite                \
                -xmat_1D NegXY

        or for an entire SUMA directory:

            cd SUMA
            tcsh
            foreach ss (*.gii)
                ConvertSurface            \
                    -i $ss                \
                    -o_gii $ss            \
                    -overwrite            \
                    -xmat_1D NegXY
            end

-GNIFTI/-GIFTI/-IFTI: same as -NIFTI

-NIFTI :Produce files in exchangeable formats. With this option
       :COR volumes are no longer used and output volumes
       :and surfaces are in alignment with the original
       :volume used to create the surface. All volumes are
        written out NIFTI format, and all surfaces are
        in GIFTI format.

        This option is incompatible with -neuro or -use_mgz

     ** Note: from 22 Feb 2013 through 20 Mar 2017, use of -NIFTI
              would distort standard mesh surfaces.  To evaluate
              effects of this, consider: MapIcosahedron -write_dist.

            * If you are seeing this message, that problem was fixed
              years ago.

NOTE for -NIFTI:
    If you really care that the volumes in SUMA/ are in exact
    register with the volume you passed to FreeSurfer, you
    should be sure that the volume passed to FreeSurfer has
    an even number of slices in all directions and a voxel
    resolution of 1x1x1, otherwise the resultant volumes in
    SUMA/ might be off by half a voxel or less in directions
    with odd number of slices. The reason has to do (I think)
    with FreeSurfer's resampling and volume centering approach.
    In either case, surfaces and volumes under SUMA/ will be in
    proper register.

    For example, when creating a surface model of the TT_N27 brain
    I padded the TT_N27+tlrc volume before submitting it to
    FreeSurfer with the following command:
       3dZeropad -L 1 -P 1 -S 1 -prefix anat.nii TT_N27+tlrc.HEAD

    After zeropadding, anat.nii remains in perfect register with
    TT_N27+tlrc by it has an even number of slices in all
    directions.  For example, running:
        3dinfo -n4  -d3 -prefix anat.nii
    produces:
        162  192  152   1    1.0     1.0     1.0     anat.nii

-inflate INF: Create modereately inflated surfaces using
              SurfSmooth. INF controls the amount of smoothness
              in the final image. It is the number of iterations
              in the command such as:
                SurfSmooth               \
                    -i lh.white.asc      \
                    -met NN_geom         \
                    -Niter 200           \
                    -o_gii               \
                    -surf_out lh.inf_200 \
                    -match_vol 0.01

              You can use multiple instances of -inflate to create
              inflations of various levels.
-set_space  SPACE: Set the space flag of all volumes to
        SPACE (orig, MNI, TLRC, MNIa). The default is
        orig space.
        You should only use this option when the volume you
        passed to FreeSurfer was not in 'orig' space.
        Use '3dinfo -space YOUR_DATASET' to find the space
        of a certain dataset.

-sid SUBJECT_ID : required subject ID for file naming

-ld LD : Create standard mesh surfaces with mesh density
         linear depth (see MapIcosahedron -help, option -ld)
         set to LD. You can use multiple -ld options.
         By default the script will run ld values of 141 and
         60.
-ldpref LDpref: Supply what ends up being the -prefix option
                for MapIcosahedron. By default it is std.LD.
                You need as many -ldpref as you have -ld
-no_ld: Do not run MapIcosahedron.

NOTES

Making use of FreeSurfer's -contrasurfreg output with MapIcosahedron:
This script will create SUMA versions of lh.rh.sphere.reg and
rh.lh.sphere.reg but in this current state, MapIcosahedron does
not attempt to use them for backward compatibility.
Should you want to create standard mesh surfaces with node
index correspondence across the hemispheres you will need to run
MapIcosahedron manually in the output SUMA/ directory.

For example:
      MapIcosahedron                        \
          -spec SUBJ_rh.spec -ld 60         \
          -dset_map rh.thickness.gii.dset   \
          -dset_map rh.curv.gii.dset        \
          -dset_map rh.sulc.gii.dset        \
          -morph rh.lh.sphere.reg.gii       \
          -prefix std.60.lhreg.

This command is very similar to the one use to create the default
output spec file std.60.SUBJ_rh.spec (look at the top of the spec
file for a record of the command that created it), except for the
last two options -morph and -prefix.  By using -morph
rh.lh.sphere.reg.gii the resultant standard-mesh right hemispheres
(std.60.lhreg.rh.*.gii) will have node index correspondence with
std.60.lh.*.gii surfaces.  To verify visually the correspondence,
run the following:

   count -column 0 36001 > std.60.lh.rh.nodeindex.1D.dset
   suma -noniml -spec std.60.SUBJ_lh.spec &
   suma -noniml -spec std.60.SUBJ_rh.spec &
   suma -noniml -spec std.60.lhreg.SUBJ_rh.spec &

Then load std.60.lh.rh.nodeindex.1D.dset into each of the three SUMA
windows. Note how the color pattern (node indices) matches between
SUBJ_lh and lhreg.SUBJ_rh surfaces, but NOT between SUBJ_lh and
SUBJ_rh surfaces.

COMMENTS

0. More help may be found at:
   https://afni.nimh.nih.gov/pub/dist/doc/htmldoc/SUMA/main_toc.html
1. Surface file names should look like 'lh.smoothwm'.
2. Patches of surfaces need the word patch in their name, in
   order to use the correct option for 'mris_convert'.
3. Flat surfaces must have .flat in their name.
4. You can tailor the script to your needs. Just make sure you
   rename it or risk having your modifications overwritten with
   the next SUMA version you install.

Authors to pester:
  R. Reynolds  (reynoldr@mail.nih.gov)
  Z. Saad      (saadz@mail.nih.gov)
  M. Beauchamp (michael.beauchamp@bcm.edu)