@Atlasize


Script to turn a volumetric dataset into an AFNI atlas.
To make an atlas available for 'whereami_afni' queries, AFNI needs both
an atlas dataset and an entry for that atlas in an atlas file.
This script will tag the dataset as an atlas by adding the necessary
header information to the dataset and create an entry in the atlas file.

Note:
    For labeling surface-based datasets you should use programs
    MakeColorMap and ConvertDset. For details, see ConvertDest's -labelize
    and MakeColorMap's -usercolutfile and -suma_cmap options.

Usage: @Atlasize <-dset DSET>

   -dset DSET: Make DSET an atlas
   -space SPACE: Mark DSET as being in space SPACE
   -lab_file FILE cLAB cVAL: Labels and keys are in text file FILE.
                          cLAB is the index of column containing labels
                          vVAL is the index of column containing keys
                          (1st column is indexed at 0)
   -lab_file_delim COL_DELIM: Set column delimiter for -lab_file option
                              Default is ' ' (space), but you can set
                              your own. ';' for example. Note that the
                              delimiter is passed directly to awk's -F
   -longnames cLONGNAME: Additionally, allow for another column of long
                names for regions, e.g. amygdala for AMY
                cLONGNAME is the starting column for the longname continuing
                to the last name of the output
   -last_longname_col cLASTLONGNAME: limit longnames to nth column
   -atlas_type TP: Set the atlas type where TP is 'S' for subject-based
                and 'G' for group-based atlases, respectively.
                   A subject-based atlas will remain in the current
                directory. Its entry is added to the atlas file
                SessionAtlases.niml.
                   A group atlas will get copied to your custom atlas
                directory. If you do not have one, the script will
                help you create it. The entry for a group atlas is
                made in CustomAtlases.niml which will reside in your
                custom atlases directory specified by environment
                variable AFNI_SUPP_ATLAS_DIR which, if not set already
                can easily be added with something like:
                  @AfniEnv -set AFNI_SUPP_ATLAS_DIR ~/CustomAtlases
   -atlas_description DESCRP: Something with which to describe atlas
                         Default is 'My Atlas'
   -atlas_name NAME: Something by which to call for the atlas.
                     Default name is based on prefix of DSET.
   -auto_backup: When using -atlas_type G, a copy of dset is made in
                 your custom atlas directory. If the same dset with the
                 same name exists already, this option will back it up
                 and allow an overwrite. You could endup with a lot of
                 backed volumes and niml files, so you might want to
                 to cleanup now and then.
   -centers:    Add center of mass coordinates to atlas
   -centertype TYPE: Choose Icent, Dcent or cm for different ways
              to compute centers. See 3dCM for details
   -centermask DSET: Calculate center of mass locations for each ROI
              using a subset of voxels. Useful for atlases with
              identical labels in both hemispheres.
              See 3dCM -mask for details
   -skip_novoxels:  Skip regions without any voxels in the dataset

Global Help Options:
--------------------

   -h_web: Open webpage with help for this program
   -hweb: Same as -h_web
   -h_view: Open -help output in a GUI editor
   -hview: Same as -hview
   -all_opts: List all of the options for this script
   -h_find WORD: Search for lines containing WORD in -help
                 output. Seach is approximate.

 Examples:
    Say you have a dataset DSET with ROIs in it and that a text file
    named KEYS.txt contains the assignment of labels to integer keys:
      1   Amygda
      2   Hippo
      5   Cerebellum
      ....
    You can turn DSET into an atlas which gets handled in a special
    manner in AFNI's interactive GUI and in whereami_afni.

    There are two classes of atlases:
    Single-subject atlases are ROIs dsets or parcellations like those
    created by freesurfer and handled in @SUMA_Make_Spec_FS, or perhaps
    ones you would create by drawing regions on the anatomy.
    Single-subject datasets and their accompanying SessionAtlases.niml
    file usually reside in that subject's directory.

      Case 1, single-subject atlas:
            @Atlasize -space MNI -dset atlas_for_joe.nii \
                      -lab_file keys.txt 1 0

    Launching afni in that directory will now show atlas_for_joe.nii as
    an atlas: Special colors, labels appear next to voxel values, and
    in slice windows if you turn labels on (right click on gray scale,
    and set Labels menu) Whereami queries will also return results from
    the new atlas.

      Case 1.1, dset is already an atlas but it is not in an atlas file
                and therefore is not visible from whereami_afni.
             @Atlasize -dset atlas_for_joe.nii

    Note: For NIFTI volumes, all changes are made in the header
    extension, so non-AFNI programs should not be bothered by this.

      Case 2, Group-level atlases:
    These atlases are stored in your custom atlas directory (the
    scipt will help you create it), along with the CustomAtlases.niml
    file.
    If you have not set up your custom atlas directory, just run:

         @AfniEnv -set AFNI_SUPP_ATLAS_DIR ~/MyCustomAtlases/

    Then:
         @Atlasize -space MNI -dset atlas_for_all.nii \
                   -lab_file keys.txt 1 0 -atlas_type G

    In ~/MyCustomAtlases/ you will now find  atlas_for_all.nii along
    along with a modified CustomAtlases.niml file.

    Launching afni from any directory will make atlas_for_all.nii
    available, in addition to the other atlases in afni's bin
    directory.