Error creating a Freesurfer annotation file with nibabel

I’m hoping to create a binary annotation file using Nibabel’s write_annot function (version 3.2.1). However, I keep getting this bug. A reproducible example is below:


import numpy as np
import nibabel as nib

# create binary mask
n_vertices = 10242
indices = np.random.randint(0, n_vertices, (50,))
mask = np.zeros((n_vertices), dtype=int)
mask[indices] = 1

ctab = np.array([[255, 255, 255, 0]])
names = ['mask']

nib.freesurfer.write_annot('mask.annot', labels=mask, ctab=ctab, names=names)

This produces:

IndexError                                Traceback (most recent call last)
<ipython-input-91-36733fdfa0f8> in <module>
     10 names = ['mask']
     11 
---> 12 nib.freesurfer.write_annot('mask.annot', labels=mask, ctab=ctab, names=names)

~/miniconda3/lib/python3.8/site-packages/nibabel/freesurfer/io.py in write_annot(filepath, labels, ctab, names, fill_ctab)
    542 
    543         # convert labels into coded CLUT values
--> 544         clut_labels = ctab[:, -1][labels]
    545         clut_labels[np.where(labels == -1)] = 0
    546 

IndexError: index 1 is out of bounds for axis 0 with size 1

I get the same error when fill_ctab=False and len(ctab)=5 (i.e. added label id to ctab).

Based on the error, ctab is being indexed with the labels. Not sure if this is a bug or something I’m doing wrong.

Thoughts? Thanks!

Hey @danjgale!

Your ctab array needs to have two rows (and your names list also nees to have two entries—though that isn’t enforced on file creation, the file will not be malformed and you won’t be able to load it).

You need a marker for the background value (0, in your case) in addition to the mask value:

import numpy as np
import nibabel as nib

# create binary mask
n_vertices = 10242
indices = np.random.randint(0, n_vertices, (50,))
mask = np.zeros((n_vertices), dtype=int)
mask[indices] = 1

ctab = np.array([[25, 25, 25, 0], [255, 255, 255, 255]])
names = ['background', 'mask']

nib.freesurfer.write_annot('mask.annot', labels=mask, ctab=ctab, names=names)

(N.B. If you provide an entry in ctab that is all zeros ([0, 0, 0, 0]) the values for your label array will get saved as -1 and not 0! Make sure your “zero” entry has at least some positive values.)

1 Like

Amazing, thank you!

RE: your note. Is there a reason why the values get saved as -1 rather than their original value?

From what I understand, it’s sort of a side effect of how annotation files are saved to disk. The full label array itself isn’t saved in the file, but rather the color table look-up values are (these are the values in the fifth column of the ctab array).

These look-up values are calculated via: (B * 256^2) + (G * 256) + (R), so when all of R, G, and B are 0, the look-up value is also 0. For some reason, when reading an annotation file that has a color table look-up value of 0, it gets interpreted as “no label” rather than “label = 0” (I am unclear if this is a FreeSurfer-specified thing or just a nibabel thing—I assume the former). Because of this, nibabel assigns it a value of -1 (see: nibabel/io.py at 62aea04248e70d7c4529954ca41685d7f75a0b1e · nipy/nibabel · GitHub).

Basically: I’m not too clear on exactly why, but it seems to be purposeful rather than accidental :sweat_smile:

1 Like
2 Likes