AnchorBar

AnchorBar (aka "Analyzer") is a Python program developed to maintain and compute set operations on FreeSurfer annotation files. It's kind of like SPM's MarsBar plugin, but for FreeSurfer.

Requirements

AnchorBar has a few dependencies that must be met:

1. argparse
2. sqlite3
3. hashlib
4. nibabel
5. random
6. numpy

Attempting to run the scripts will fail and report missing libraries. They can be installed using pip:

pip install nibabel

The utility is (currently) comprised of 3 scripts. Syntax help for each of these scripts can be obtained using the -h switch:

$ AnchorBar_tools.py -h
usage: AnchorBar_tools.py [-h] [--list] [--labels annot_id] [--db DB] [--rename annot_id new_shortname]
                         [--relabel annot_id label_id new_label_name] [--abbrev annot_id label_id abbrev_label_name]

Querying Available Annotations

AnchorBar_tools.py provides tools to list, rename and relabel annotations. Each annotation has a unique ID and descriptors indicating the hemisphere, a shortname used for naming labels generated from set operations, and a path indicating the file path of the source .annot file. The default set of annotations stored in annot.db includes the 10 pairs of lhrh annotations from fsaverage/label:

AnchorBar_tools.py --db annot.db --list

Adding Annotations

The most common use-case for adding annotations is when working with functional ROIs from group analyses. AnchorBar_init.py is the tool that imports new .annot files into the database for later operations. Imported annotations are associated with a unique identifier based on the labels and vertices that make up an annotation. This allows the scripts to recognize and ignore duplicate annotations that might have been given different names, but also to differentiate distinct annotations that happen to have the same name (as is common when working with functional ROIs).

The import process infers the hemisphere from the filename. Functional cluster annotations are unlikely to have an lh/rh prefix, and so will require renaming prior to importing (I like to stick them in the project copy of the fsaverage folder):

cp $SUBJECTS_DIR/RFX/myanalysis.lh/a_vs_b/glm.wls/osgm/cache.th30.abs.sig.ocn.annot $SUBJECTS_DIR/fsaverage/label/lh.a_vs_b.cache.th30.abs.annot
cp $SUBJECTS_DIR/RFX/myanalysis.rh/a_vs_b/glm.wls/osgm/cache.th30.abs.sig.ocn.annot $SUBJECTS_DIR/fsaverage/label/rh.a_vs_b.cache.th30.abs.annot

To add one or more new annotations (that you've renamed and saved to the fsaverage/label folder):

AnchorBar_init.py --db annot.db --annot $SUBJECTS_DIR/fsaverage/label/*.th30.abs.annot

Of course, the particular filename pattern in red in the above command may differ from what's shown here, depending on your file naming convention, but you get the idea. When this code executes, it will import all the files that end in "th30.abs.annot" that it finds. This is handy for importing annotations for multiple hemispheres and/or for multiple contrasts.

Renaming Imported Annotations

Imported annotations will be given a shortname that corresponds to the filename of the source annotation. These names can be unwieldy, so AnchorBar_tools.py allows you to assign a new shortname to stored annotations. First, list the annotations and note their shortnames and id values. Use the id when selecting the annotation for renaming. For example:

./AnchorBar_tools.py --db annot.db --list

*** Annotation List ***
id	LR shortname	path
1	lh aparc.a2005s	/usr/local/freesurfer/subjects/fsaverage/label
2	lh aparc.a2009s	/usr/local/freesurfer/subjects/fsaverage/label
...
25	lh a_v_b.th30.abs	/home/projects/mystudy/fsaverage/label
26	rh a_v_b.th30.abs	/home/projects/mystudy/fsaverage/label

If we wanted to remove the "th30.abs" part of the shortname for the last two annotations:

./AnchorBar_tools.py --db annot.db --rename 26 AvsB
./AnchorBar_tools.py --db annot.db --rename 25 AvsB

Now inspect the annotation database:

./AnchorBar_tools.py --db annot.db --list

*** Annotation List ***
id	LR shortname	path
1	lh aparc.a2005s	/usr/local/freesurfer/subjects/fsaverage/label
2	lh aparc.a2009s	/usr/local/freesurfer/subjects/fsaverage/label
...
25	lh AvsB	/home/projects/mystudy/fsaverage/label
26	rh AvsB	/home/projects/mystudy/fsaverage/label