## Note: This page was created with the CommandTemplate
##
## If you're modifying this page please take a look at the
## latest version of CommandTemplate to ensure that you're
## using the latest version of the CommandTemplate
##
## See HelpOnCommandTemplate for description of formatting

'''Index'''
<<TableOfContents>>

Software version described:
 * $Date: 2006/12/29 02:09:10 $
 * $Revision: 1.11 $
 * Use usage or version option to see version you are using

= mris_label2annot =
This command-line program amalgamates one or more label files, plus optionally a color lookup table, into a single annotation file. The concepts relating to label files and annotation files are described here: LabelsClutsAnnotationFiles.

= Synopsis =
mris_label2annot [Flagged args, see below]

= Arguments =
== Positional Arguments ==
none

== Flagged Arguments ==
||<^>'''Flag'''||<^> <'''Args'''> ||<^>'''Description'''||
||<^>--ctab||<^> <ctab_file> ||<^>Colortable file. File that defines the structure names, their indices, and their color. This must have the same format as that found in $FREESURFER_HOME/FreeSurferColorLUT.txt. <<BR>>The colortable file gets incorporated into the output annotation file. In addition, depending on other options, the names in colortable can be used by this program to find correspondingly-named label files. More details below.||
||<^>--l||<^> <label_file> ||<^>Repeat this flag and arg for each additional label file you want to include in the annotation file.||
||<^>--ldir||<^> <labeldir> ||<^>When seeking label files based on names in ctab, find the label files in labeldir.  This has no effect on the files specified by --l||
||<^>--ldir-default||<^> ||<^>Works like --ldir option, setting labeldir to the default label directory for the selected subject:<<BR>><<BR>>{SUBJECTS_DIR}/{SUBJECT}/label||
||<^>--s or --subject||<^> <subject> ||<^>FreeSurfer subject to work on||
||<^>--a or --annot||<^> <annot_name> ||<^>output annotation file  The actual file will be called 'hemi.annot_name.annot', and it will be created in directory subject/label. To avoid overwriting possibly valuable data, the program will not overwrite an existing file by the same name.||
||<^>--h or --hemi||<^> <hemi> ||<^>hemisphere (lh or rh)||
||<^>--no-unknown||<^> ||<^>Start label numbering at index 0 instead of index 1. Do not map unhit vertices (ie, vertices without a label) to 0.||
||<^>--help||<^> ||<^>print_help||
||<^>--version||<^> ||<^>print_version||
||<^>--checkopts||<^> ||<^>checkoptsonly = 1||
||<^>--debug||<^> ||<^>debug = 1||
||<^>--nhits||<^> <nhits_file> ||<^>This option creates a diagnostic file showing whether the cumulative effect of all the label files happens to assign more than one label to each vertex. The output file is a FreeSurfer 'overlay' format file, in which each vertex has an associated value, in this case the count of labels assigned to that vertex. This can be displayed in tksurfer as a color. Setting fthresh to 1.5 will distinguish good vertices (count<=1) from bad (count>=2).||
||<^>--nocheckopts||<^> ||<^>checkoptsonly = 0||
||<^>--offset||<^><IndexOffset> ||<^>Add to label number to get CTAB index.||
||<^>--sd||<^><SUBJECTS_DIR> ||<^>||
||<^>--noverbose||<^> ||<^>Turn off overlap and stat override messages.||
||<^>--maxstatwinner||<^> ||<^>Keep label with highest 'stat' value.||
||<^>--thresh||<^><thres> ||<^>threshold label by stats field.||
||<^>--surf||<^><surfname> ||<^>Default is orig.||

= Description =
This program is used to amalgamate one or more label files together into a single annotation file, usually including a color lookup table file. The concepts relating to label files and annotation files are described here: LabelsClutsAnnotationFiles.

= Examples =
== Example 1 ==
The following example is taken from mris_label2annot's help --GW
{{{
mris_label2annot --s bert --h lh 
  --ctab aparc.annot.ctab --a myaparc 
  --l lh.unknown.label 
  --l lh.bankssts.label
  --l lh.caudalanteriorcingulate.label 
  --nhits nhits.mgh
}}}

This will create lh.myaparc.annot in bert/labels using the three
labels specified. Any vertices that have multiple labels will then 
be stored in nhits.mgh (as a volume-encoded surface file).

(Note: this nhits.mgh detail is a bit obscure. The idea of an nhits file is simply to provide a list of values giving the count of labels found for each vertex. This needs to be presented to tksurfer for display as a colored overlay. Here FS's MRI volume format is used just as a container for that 1 x vertex_count array of values. --GW)

To view, run:
tksurfer bert lh inflated -overlay nhits.mgh -fthresh 1.5
Then File -> Label -> Import Annotation and select lh.myaparc.annot.

= Bugs =
None

= See Also =
[[mri_annotation2label]], LabelsClutsAnnotationFiles


= Reporting Bugs =
Report bugs to <analysis-bugs@nmr.mgh.harvard.edu>

= Document Author/s =
GrahamWideman