Differences between revisions 15 and 16
Deletions are marked like this. Additions are marked like this.
Line 9: Line 9:
Note: As of 2008-01-19, it looks to me like parts of this file were left-overs from the page of some unrelated command. I have moved these sections to the bottom "Obsolete?" section. Someone official can perhaps clean this up. -- GW
Line 13: Line 11:

Note: The "mri_" prefix suggests that this program works with MRI volume files or related data. Instead, the annotation files this program works with are associated with ''surface'' files. This program probably should be named with an "mris_" prefix for consistency. --GW
Line 20: Line 16:
== Flagged Arguments ==
||<style="vertical-align: top;">'''Category''' ||<style="vertical-align: top;">'''Flag''' ||<style="vertical-align: top;"><'''Args'''> ||<style="vertical-align: top;">'''Reqd''' ||<style="vertical-align: top;">'''Description''' ||
||<style="vertical-align: top;">Input ||<style="vertical-align: top;">--a2005s ||<style="vertical-align: top;"> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">Use 'aparc.a2005s' as the annotation base name, (Default: use 'aparc') ||
||<style="vertical-align: top;">Input ||<style="vertical-align: top;">--annotation ||<style="vertical-align: top;"><annotation> ||<style="vertical-align: top;">Y ||<style="vertical-align: top;">Selects input annotation file, as found in SUBJDIR/labels. Default is 'aparc'. ||
||<style="vertical-align: top;">Input ||<style="vertical-align: top;">--hemi ||<style="vertical-align: top;"><hemi> ||<style="vertical-align: top;">Y ||<style="vertical-align: top;">lh or rh. Used in conjunctions with surface name to compose surface file name. [Might be used with annotation name too? Not sure -- GW] ||
||<style="vertical-align: top;">Input ||<style="vertical-align: top;">--subject ||<style="vertical-align: top;"><subject> ||<style="vertical-align: top;">Y ||<style="vertical-align: top;">source subject ||
||<style="vertical-align: top;">Input ||<style="vertical-align: top;">--surface or --surf ||<style="vertical-align: top;"><surfacename> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">Name of surface. Default if omitted: 'white'. This selects the surface file that the program will read in order to create R,A,S coordinates for each vertex listed in a label file. ||
||<style="vertical-align: top;">Input ||<style="vertical-align: top;">--table ||<style="vertical-align: top;"> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">ERROR: Older versions of program worked in conjunction with separate colortable. Current versions expect to read colortable from annotation file. ||
||<style="vertical-align: top;">Output ||<style="vertical-align: top;">--border ||<style="vertical-align: top;"><borderfile> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">Creates an overlay file in which the boundaries of the parcellations are set to 1 and everything else is 0. This can then be loaded as an overlay in tksurfer. ||
||<style="vertical-align: top;">Output ||<style="vertical-align: top;">--labelbase ||<style="vertical-align: top;"><labelbase> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">If supplied, the program will compose output label filenames using the pattern 'labelbase-XXX.label' (where XXX is label number). (Default: compose label filenames based on label names found in annotation file.) ||
||<style="vertical-align: top;">Output ||<style="vertical-align: top;">--outdir ||<style="vertical-align: top;"><outdir> ||<style="vertical-align: top;">? ||<style="vertical-align: top;">Directory in which to place output label files. Complete path will be: 'outdir/hemi.name.label' (with 'name' composed according to other rules). Required unless specifying one of the other kinds of output. ||
||<style="vertical-align: top;">Output ||<style="vertical-align: top;">--seg ||<style="vertical-align: top;"><segfile> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">This option causes program to output a 'volume-encoded surface segmentation file'. This is simply the list of per-vertex label values (count = count of vertices), dumped into a file whose format looks like an FS volume file... which some other FS programs are equipped to load. (Ie: it is not actually volume data). See details below. ||
||<style="vertical-align: top;">Output ||<style="vertical-align: top;">--segbase ||<style="vertical-align: top;"><segbase (int)> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">Add segbase to each label value when outputting to a segfile. ||
||<style="vertical-align: top;">Output||<style="vertical-align: top;">--lobesStrict||<style="vertical-align: top;"><LobesFile>||<style="vertical-align: top;"> ||<style="vertical-align: top;">Use a slightly stricter lobe definition that adds the precentral to the 'frontal' and includes the postcentral with the 'parietal' lobe. The lobar annotation is saved to <LobesFile>.||
||<style="vertical-align: top;">Utility ||<style="vertical-align: top;">--debug ||<style="vertical-align: top;"> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">enable debugging options ||
||<style="vertical-align: top;">Utility ||<style="vertical-align: top;">--help ||<style="vertical-align: top;"> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">display help ||
||<style="vertical-align: top;">Utility ||<style="vertical-align: top;">--version ||<style="vertical-align: top;"> ||<style="vertical-align: top;">n ||<style="vertical-align: top;">display version ||
||<style="vertical-align: top;"> ||<style="vertical-align: top;">XXXXXXXXXXXXX ||<style="vertical-align: top;"> ||<style="vertical-align: top;">- ||<style="vertical-align: top;"> ||
== Required Flagged Arguments ==
Line 39: Line 18:
|| --subject <subjid> || source subject ||
|| --hemi <lh or rh> || hemisphere (with surface) ||

== Optional Arguments ==
|| --label <int> || extract only a single label ||
|| --labelbase || output will be base-XXX.label ||
|| --outdir dir || output will be dir/hemi.name.label ||
|| --seg segfile || output will be segmentation 'volume' ||
|| --ctab colortable || colortable like FreeSurferColorLUT.txt ||
|| --border borderfile || output will be a binary overlay of the parc borders ||
|| --annotation annotation || selects input annotation file, as found in SUBJECTS_DIR/labels. Default is 'aparc' ||
|| --sd <SUBJECTS_DIR> || specify SUBJECTS_DIR on the command line ||
|| --surface surfacename || name of surface, default is 'white' if omitted. This selects the surface file that the program will read in order to create RAS coordinates for each vertex listed in a label file. Argument can also be --surf ||
|| --stat statfile || surface overlay file (curv or volume format) ||
|| --lobes <lobesfile> || create an annotation based on cortical lobes. Note that the precentral and postcentral labels are not included as part of the 'frontal' or 'parietal' lobes. The lobar annotation is saved to <lobesfile>. ||
|| --lobesStrict <lobesfile> || use a slightly stricter lobe definition that adds the precentral to the 'frontal' and includes the postcentral with the 'parietal' lobe. The lobar annotation is saved to <lobesfile>. ||
|| --lobesStrictPHCG <lobesfile> || use stricter lobe definition, and adds an additional lobe called parahippocampalgyrus which includes parahippocampal, entorhinal, temporalpole, and fusiform. The lobar annotation is saved to <lobesfile>. ||
Line 41: Line 37:
The main purpose of this program is to convert an annotation file into multiple label files. Optionally it can create output files that contain label information in other forms. (This program cannot export the annotation file's LUT to text format -- if you need to do that, for example to verify it, you could use [[mris_anatomical_stats]]. The main purpose of this program is to convert an annotation file into multiple label files or into a segmentation 'volume'. It can also create a border overlay. Optionally it can create output files that contain label information in other forms. (This program cannot export the annotation file's LUT to text format -- if you need to do that, for example to verify it, you could use [[mris_anatomical_stats]].
Line 48: Line 44:
  * If --outdir dir is used, then the output will be dir/hemi.name.label, where 'name' is the corresponding name in the lookup table in the annotation file.
  * If --labelbase is used, name of the file is composed using the pattern: labelbase-XXX.label, where XXX is the zero-padded 3 digit annotation index. (I assume that "annotation index" means label value. Not sure what happens for label values > 999. --GW) If labelbase includes a directory path, that directory must already exist.
 * If --outdir dir is used, then the output will be dir/hemi.name.label, where 'name' is the corresponding name in the lookup table in the annotation file.
 * If --labelbase is used, name of the file is composed using the pattern: labelbase-XXX.label, where XXX is the zero-padded 3 digit annotation index. If labelbase includes a directory path, that directory must already exist.
Line 101: Line 97:
= Obsolete? =
== Positional Arguments ==
== Required Flagged Arguments ==
||--srcreg ||srcreg.dat ||
||--targreg ||targreg.dat ||


== Optional Flagged Arguments ==
||--targsubj subjid ||default is talairach ||
||--xfm xfmrname ||xfm file name relative to transforms ||
||--sd subjects_dir ||default is env SUBJECTS_DIR ||
||--fvol funcvol ||path to example functional volume ||
||--help ||
||--version ||


== Positional Arguments ==
== Required Flagged Arguments ==
||--srcreg ||srcreg.dat ||
||--targreg ||targreg.dat ||


== Optional Flagged Arguments ==
||--targsubj subjid ||default is talairach ||
||--xfm xfmrname ||xfm file name relative to transforms ||
||--sd subjects_dir ||default is env SUBJECTS_DIR ||
||--fvol funcvol ||path to example functional volume ||
||--help ||
||--version ||

Index

Software version described:

  • $Date: 2007/11/16 20:32:50 $
  • $Revision: 1.15 $
  • Use usage or version option to see version you are using

Name

mri_annotation2label - Inputs an annotation file and produces corresponding label files.

Synopsis

mri_annotation2label [Flagged arguments]

Arguments

Required Flagged Arguments

--subject <subjid>

source subject

--hemi <lh or rh>

hemisphere (with surface)

Optional Arguments

--label <int>

extract only a single label

--labelbase

output will be base-XXX.label

--outdir dir

output will be dir/hemi.name.label

--seg segfile

output will be segmentation 'volume'

--ctab colortable

colortable like FreeSurferColorLUT.txt

--border borderfile

output will be a binary overlay of the parc borders

--annotation annotation

selects input annotation file, as found in SUBJECTS_DIR/labels. Default is 'aparc'

--sd <SUBJECTS_DIR>

specify SUBJECTS_DIR on the command line

--surface surfacename

name of surface, default is 'white' if omitted. This selects the surface file that the program will read in order to create RAS coordinates for each vertex listed in a label file. Argument can also be --surf

--stat statfile

surface overlay file (curv or volume format)

--lobes <lobesfile>

create an annotation based on cortical lobes. Note that the precentral and postcentral labels are not included as part of the 'frontal' or 'parietal' lobes. The lobar annotation is saved to <lobesfile>.

--lobesStrict <lobesfile>

use a slightly stricter lobe definition that adds the precentral to the 'frontal' and includes the postcentral with the 'parietal' lobe. The lobar annotation is saved to <lobesfile>.

--lobesStrictPHCG <lobesfile>

use stricter lobe definition, and adds an additional lobe called parahippocampalgyrus which includes parahippocampal, entorhinal, temporalpole, and fusiform. The lobar annotation is saved to <lobesfile>.

Description

The main purpose of this program is to convert an annotation file into multiple label files or into a segmentation 'volume'. It can also create a border overlay. Optionally it can create output files that contain label information in other forms. (This program cannot export the annotation file's LUT to text format -- if you need to do that, for example to verify it, you could use mris_anatomical_stats.

Inputs are specified via subject, hemisphere, and optionally, if the defaults are not wanted, a base name for the annotation, and a specific surface to be used for the R,A,S coordinates that will be placed in the label files.

  • By default, the base name for the annotation file is 'aparc', so that the actual input annotation file is SUBJECTS_DIR/subject/label/lh.aparc.annot or rh.aparc.annot.
  • A separate label file is created for each annotation index.
  • The output file names can take one of two forms:
  • If --outdir dir is used, then the output will be dir/hemi.name.label, where 'name' is the corresponding name in the lookup table in the annotation file.
  • If --labelbase is used, name of the file is composed using the pattern: labelbase-XXX.label, where XXX is the zero-padded 3 digit annotation index. If labelbase includes a directory path, that directory must already exist.
  • If there are no points in the annotation file for a particular index, no label file is created.
  • The xyz (R,A,S) coordinates in the label file are obtained from the values at that vertex of the specified surface. The default surface is 'white'. Other options include 'pial' and 'orig'.

Details for 'seg' output file label numbers

The seg option causes the program to output a 'volume-encoded surface segmentation file'. This is simply the list of per-vertex label values (count = count of vertices), dumped into a file whose format looks like an FS volume file... which some other FS programs are equipped to load. (Ie: it is not actually volume data). See details below.

The label values stored in this situation may be recorded verbatim, or may be increased by an offset amount segbase. By default, these label values are intended to match the index for the label as found in $FREESURFER_HOME/FreeSurferColorLUT.txt; This requires that the annotation file base name be either aparc or aparc.a2005s, in order to invoke the following behavior: If aparc and hemi=lh, then segbase=1000, with segbase values for rh and for aparc.a2005s. This makes the index match that found in aparc+aseg.mgz. If the annotation is neither aparc nor aparc.a2005s, then segbase=0. This behavior can be overridden by manually specifying a segbase with --segbase.

(This doesn't sound like the complete story to me, because I don't see how the label values got into the annotation file with their segbase offsets removed in the first place. --GW).

Probably applies to obsolete version

The human-readable names that correspond to the annotation indices for aparc depend upon how the annotations were created. They are created with the program mris_ca_label, and the human readable names are in the file given as the argument to the -t flag. Unfortunately, this information is not maintained inside the annotation file, and it must be supplied to mri_annotation2label through the --table flag.

Examples

Example 1

mri_annotation2label --subject LW \
  --hemi rh \
  --labelbase ./labels/aparc-rh

This will get annotations from $SUBJECTS_DIR/LW/label/rh_aparc.annot and then create about 94 label files: aparc-rh-001.label, aparc-rh-002.label, ... Note that the directory 'labels' must already exist.

Example 2

mri_annotation2label --subject LW \
  --hemi rh
  --outdir ./labels

This will do the same thing as above except that the output files will have names of the form lh.S_occipital_anterior.label

Bugs

If the name of the label base does not include a forward slash (ie, '/') then the program will attempt to put the label files in $SUBJECTS_DIR/subject/label. So, if you want the labels to go into the current directory, make sure to put a './' in front of the label base.

Testing

  1. Start tksurfer:
    • tksurfer -LW lh inflated read_annotations lh_aparc
    • When a point is clicked on, it prints out a lot of info, including something like:
      • annot = S_temporalis_sup (93, 3988701) (221, 220, 60)
      This indicates that annotion number 93 was hit. Save this point.
  2. Start another tksurfer and load the label:
    • tksurfer -LW lh inflated [edit label field and hit the 'Read' button]
    • Verify that label pattern looks like the annotation as seen in the tksurfer window from step 1.
  3. Load label into tkmedit
    • tkmedit LW T1 [Load the label]
    • [Goto the point saved from step 1]

See Also

mris_label2annot, LabelsClutsAnnotationFiles

Reporting Bugs

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

mri_annotation2label (last edited 2017-12-04 12:27:47 by MorganFogarty)