FSL/TBSS: Determine anatomical labels from clusters using Python

After some time building more and more contrast maps with FSL/TBSS, I needed some way to compile information - anatomical in particular - from clusters in a thresholded map. The typical information that may then be reported in a paper. I was probably not the first one to look for this (as suggested here) but I could not find any tool (like a Nipype interface) or recipe suited to my needs. Only later I found out about AtlasReader which creates activation tables with some extra nilearn-type snapshots. It also seems that fslpy has a wrapper to FSL's atlasquery, which does what I want, except that I wanted something closer to FSL's autoaq and possibility to get the outputs as DataFrames.

FSL/TBSS comes indeed with that useful command (atlasquery) which returns the name and proportions of the regions from any given reference atlas (among the ones supplied with FSL) that would show an overlap with clusters from any binary map.

Hence the following Python functions (named after the original commands) are just wrappers around atlasquery and autoaq and convert their outputs to pandas DataFrames.

See the full code there.

data = atlasquery('/tmp/tmpsi1gyceh.nii.gz', 
                  'JHU White-Matter Tractography Atlas')
data.sort_values(by='pc', ascending=False).head()

tract	pc
Forceps minor	5.2468
Inferior longitudinal fasciculus L	1.794
Inferior fronto-occipital fasciculus L	1.7061
Anterior thalamic radiation L	1.6814
Superior longitudinal fasciculus L	1.4276

The input map is assumed to be binary. If it is not, then one can use autoaq and give a specific threshold for the input map (default: 0.95 (equivalent to p<0.05)). Two dataframes will be returned as original results come in multiple sections.

data = autoaq('/path/to/map_FA_tfce_corrp_tstat3.nii.gz', 
              'JHU White-Matter Tractography Atlas', 
              thr=0.95)
data[0]  

ClusterIndex	Voxels	MAX	MAX X (mm)	MAX Y (mm)	MAX Z (mm)	COG X (mm)	COG Y (mm)	COG Z (mm)	pc_tract
1	25356	0.988	14	27	16	-7.98	-5.61	16.5	9% Anterior thalamic radiation L

data[1].sort_values(by='pc', ascending=False).head()

ClusterIndex	tract	pc
1	Forceps minor	5.2026
1	Inferior longitudinal fasciculus L	1.8074
1	Inferior fronto-occipital fasciculus L	1.7149
1	Anterior thalamic radiation L	1.6879
1	Superior longitudinal fasciculus L	1.438

These two commands have been integrated to the little Python module that I use for TBSS-related work.